@moon-x/node-sdk 0.1.0

package/dist/index.mjs

@@ -0,0 +1,454 @@
+// src/errors.ts
+var MoonXError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "MoonXError";
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var MalformedTokenError = class extends MoonXError {
+  constructor(message = "token is not a well-formed JWT") {
+    super("malformed_token", message);
+    this.name = "MalformedTokenError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var InvalidTokenError = class extends MoonXError {
+  constructor(message = "token signature is invalid") {
+    super("invalid_signature", message);
+    this.name = "InvalidTokenError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ExpiredTokenError = class extends MoonXError {
+  constructor(message = "token has expired") {
+    super("expired_token", message);
+    this.name = "ExpiredTokenError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AudienceMismatchError = class extends MoonXError {
+  constructor(expected, got, message = `token audience does not match this app (expected ${expected}, got ${JSON.stringify(got)})`) {
+    super("audience_mismatch", message);
+    this.name = "AudienceMismatchError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var IssuerMismatchError = class extends MoonXError {
+  constructor(expected, got, message = `unexpected issuer (expected ${expected}, got ${got})`) {
+    super("issuer_mismatch", message);
+    this.name = "IssuerMismatchError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var SubjectMismatchError = class extends MoonXError {
+  constructor(message = "identity token subject does not match access token subject") {
+    super("subject_mismatch", message);
+    this.name = "SubjectMismatchError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var KidMismatchError = class extends MoonXError {
+  constructor(message = "token kid does not match any key in JWKS") {
+    super("kid_mismatch", message);
+    this.name = "KidMismatchError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var UnsupportedAlgorithmError = class extends MoonXError {
+  constructor(alg) {
+    super(
+      "unsupported_algorithm",
+      `unsupported token algorithm: ${alg} (only ES256 is supported)`
+    );
+    this.name = "UnsupportedAlgorithmError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var JwksFetchError = class extends MoonXError {
+  constructor(message) {
+    super("jwks_fetch_failed", message);
+    this.name = "JwksFetchError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AppResolutionError = class extends MoonXError {
+  constructor(message) {
+    super("app_resolution_failed", message);
+    this.name = "AppResolutionError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ConfigurationError = class extends MoonXError {
+  constructor(message) {
+    super("configuration_error", message);
+    this.name = "ConfigurationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/auth/app-resolver.ts
+var AppResolver = class {
+  constructor(baseUrl, publishableKey, opts = {}) {
+    this.cached = null;
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.publishableKey = publishableKey;
+    this.ttlMs = opts.ttlMs ?? 60 * 60 * 1e3;
+    this.fetcher = opts.fetch ?? globalThis.fetch;
+  }
+  async resolve() {
+    if (this.cached && Date.now() - this.cached.loadedAt < this.ttlMs) {
+      return this.cached.appId;
+    }
+    const appId = await this.fetch();
+    this.cached = { appId, loadedAt: Date.now() };
+    return appId;
+  }
+  async fetch() {
+    const url = `${this.baseUrl}/v0/sdk/apps/public/config`;
+    let res;
+    try {
+      res = await this.fetcher(url, {
+        headers: { Authorization: `PublicToken ${this.publishableKey}` },
+        signal: AbortSignal.timeout(5e3)
+      });
+    } catch (err) {
+      throw new AppResolutionError(
+        `app config fetch failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    if (!res.ok) {
+      throw new AppResolutionError(
+        `app config fetch returned HTTP ${res.status}`
+      );
+    }
+    const body = await res.json();
+    if (!body.id) {
+      throw new AppResolutionError("app config response missing 'id' field");
+    }
+    return body.id;
+  }
+};
+
+// src/auth/crypto.ts
+async function importEs256JwkPublicKey(jwk) {
+  if (jwk.kty !== "EC" || jwk.crv !== "P-256" || jwk.alg !== "ES256") {
+    throw new UnsupportedAlgorithmError(
+      `${jwk.alg} (${jwk.kty} ${jwk.crv})`
+    );
+  }
+  return globalThis.crypto.subtle.importKey(
+    "jwk",
+    {
+      kty: jwk.kty,
+      crv: jwk.crv,
+      x: jwk.x,
+      y: jwk.y,
+      ext: true
+    },
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["verify"]
+  );
+}
+async function verifyEs256Jwt(token, key) {
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    throw new MalformedTokenError("expected three segments separated by '.'");
+  }
+  const [headerB64, payloadB64, sigB64] = parts;
+  let header;
+  let payload;
+  try {
+    header = JSON.parse(base64UrlDecodeString(headerB64));
+    payload = JSON.parse(base64UrlDecodeString(payloadB64));
+  } catch {
+    throw new MalformedTokenError(
+      "token header or payload is not valid base64url-encoded JSON"
+    );
+  }
+  if (header.alg !== "ES256") {
+    throw new UnsupportedAlgorithmError(header.alg ?? "(missing)");
+  }
+  const signature = base64UrlDecodeBytes(sigB64);
+  if (signature.length !== 64) {
+    throw new MalformedTokenError(
+      `expected 64-byte ES256 signature, got ${signature.length}`
+    );
+  }
+  const signingInput = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+  const ok = await globalThis.crypto.subtle.verify(
+    { name: "ECDSA", hash: { name: "SHA-256" } },
+    key,
+    signature,
+    signingInput
+  );
+  if (!ok) {
+    throw new InvalidTokenError();
+  }
+  return { header, payload };
+}
+function base64UrlToBase64(s) {
+  const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - s.length % 4);
+  return s.replace(/-/g, "+").replace(/_/g, "/") + pad;
+}
+function base64UrlDecodeString(s) {
+  return new TextDecoder().decode(base64UrlDecodeBytes(s));
+}
+function base64UrlDecodeBytes(s) {
+  const bin = atob(base64UrlToBase64(s));
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+// src/auth/jwks.ts
+var JwksCache = class {
+  constructor(baseUrl, opts = {}) {
+    this.cache = /* @__PURE__ */ new Map();
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.ttlMs = opts.ttlMs ?? 5 * 60 * 1e3;
+    this.fetcher = opts.fetch ?? globalThis.fetch;
+  }
+  async getKey(appId) {
+    const cached = this.cache.get(appId);
+    if (cached && Date.now() - cached.loadedAt < this.ttlMs) {
+      return cached;
+    }
+    const fresh = await this.fetch(appId);
+    this.cache.set(appId, fresh);
+    return fresh;
+  }
+  /** Drop the cached entry for an app id. Useful after a 401 / kid mismatch
+   *  to force a re-fetch on the next call (in case the backend rotated). */
+  invalidate(appId) {
+    this.cache.delete(appId);
+  }
+  async fetch(appId) {
+    const url = `${this.baseUrl}/v0/sdk/.well-known/jwks/${appId}`;
+    let res;
+    try {
+      res = await this.fetcher(url, {
+        signal: AbortSignal.timeout(5e3)
+      });
+    } catch (err) {
+      throw new JwksFetchError(
+        `JWKS fetch failed for ${appId}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    if (!res.ok) {
+      throw new JwksFetchError(
+        `JWKS fetch returned HTTP ${res.status} for ${appId}`
+      );
+    }
+    const body = await res.json();
+    const jwk = body.keys?.find(
+      (k) => k.kty === "EC" && k.crv === "P-256" && k.alg === "ES256" && (k.use === "sig" || k.use === void 0)
+    );
+    if (!jwk) {
+      throw new JwksFetchError(
+        `JWKS for ${appId} contains no usable ES256 signing key`
+      );
+    }
+    const key = await importEs256JwkPublicKey(jwk);
+    return { key, kid: jwk.kid, loadedAt: Date.now() };
+  }
+};
+
+// src/auth/verify.ts
+async function verify(token, ctx) {
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    return verifyWithSig(token, ctx);
+  }
+  let unverifiedPayload;
+  try {
+    unverifiedPayload = JSON.parse(base64UrlDecodeString2(parts[1]));
+  } catch {
+    return verifyWithSig(token, ctx);
+  }
+  assertAudience(unverifiedPayload, ctx.pinnedAppId);
+  assertIssuer(unverifiedPayload, ctx.expectedIssuer);
+  return verifyWithSig(token, ctx);
+}
+async function verifyWithSig(token, ctx) {
+  const cached = await ctx.jwks.getKey(ctx.pinnedAppId);
+  const { header, payload } = await verifyEs256Jwt(token, cached.key);
+  if (header.kid && header.kid !== cached.kid) {
+    ctx.jwks.invalidate(ctx.pinnedAppId);
+    throw new KidMismatchError();
+  }
+  assertAudience(payload, ctx.pinnedAppId);
+  assertIssuer(payload, ctx.expectedIssuer);
+  assertNotExpired(payload);
+  return payload;
+}
+async function verifyAccessToken(token, ctx) {
+  const claims = await verify(token, ctx);
+  return claims;
+}
+async function verifyIdentityToken(token, ctx) {
+  const claims = await verify(token, ctx);
+  return claims;
+}
+async function verifySession(args, ctx) {
+  const access = await verifyAccessToken(args.accessToken, ctx);
+  if (!args.identityToken) {
+    return { access, identity: null };
+  }
+  const identity = await verifyIdentityToken(args.identityToken, ctx);
+  if (identity.sub !== access.sub) {
+    throw new SubjectMismatchError();
+  }
+  return { access, identity };
+}
+function assertAudience(payload, pinnedAppId) {
+  const raw = payload.aud;
+  const aud = Array.isArray(raw) ? raw[0] : raw;
+  if (aud !== pinnedAppId) {
+    throw new AudienceMismatchError(
+      pinnedAppId,
+      raw
+    );
+  }
+}
+function assertIssuer(payload, expected) {
+  if (payload.iss !== expected) {
+    throw new IssuerMismatchError(expected, String(payload.iss ?? "(missing)"));
+  }
+}
+function assertNotExpired(payload) {
+  const exp = payload.exp;
+  const now = Math.floor(Date.now() / 1e3);
+  if (typeof exp !== "number" || exp <= now) {
+    throw new ExpiredTokenError();
+  }
+}
+function base64UrlDecodeString2(s) {
+  const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - s.length % 4);
+  const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + pad;
+  return new TextDecoder().decode(
+    Uint8Array.from(atob(b64), (c) => c.charCodeAt(0))
+  );
+}
+
+// src/auth/index.ts
+var Auth = class {
+  constructor(opts) {
+    this.resolver = new AppResolver(opts.baseUrl, opts.publishableKey, {
+      ttlMs: opts.appResolveTtlMs,
+      fetch: opts.fetch
+    });
+    this.jwks = new JwksCache(opts.baseUrl, {
+      ttlMs: opts.jwksTtlMs,
+      fetch: opts.fetch
+    });
+    this.expectedIssuer = opts.expectedIssuer;
+  }
+  /**
+   * Verify an access token. Returns the claims on success; throws a
+   * typed `MoonXError` subclass on any failure.
+   */
+  async verifyAccessToken(token) {
+    const pinnedAppId = await this.resolver.resolve();
+    return verifyAccessToken(token, {
+      pinnedAppId,
+      expectedIssuer: this.expectedIssuer,
+      jwks: this.jwks
+    });
+  }
+  /**
+   * Verify an identity token. Returns the OIDC profile claims on
+   * success; throws a typed `MoonXError` subclass on any failure.
+   */
+  async verifyIdentityToken(token) {
+    const pinnedAppId = await this.resolver.resolve();
+    return verifyIdentityToken(token, {
+      pinnedAppId,
+      expectedIssuer: this.expectedIssuer,
+      jwks: this.jwks
+    });
+  }
+  /**
+   * Verify both tokens (identity optional). Cross-checks that the
+   * identity token's subject matches the access token's subject so a
+   * caller can't swap in another user's (still-valid) identity token.
+   *
+   * Canonical entry point for "this request is authorized AND we know
+   * who the user is" — call this from your request handlers.
+   */
+  async verifySession(args) {
+    const pinnedAppId = await this.resolver.resolve();
+    return verifySession(args, {
+      pinnedAppId,
+      expectedIssuer: this.expectedIssuer,
+      jwks: this.jwks
+    });
+  }
+};
+
+// src/config.ts
+var DEFAULT_ISSUER = "https://api.moonx-dev.com";
+function resolveConfig(input) {
+  if (!input.publishableKey) {
+    throw new ConfigurationError(
+      "MoonXClient: publishableKey is required"
+    );
+  }
+  if (!input.publishableKey.startsWith("moon_pk_")) {
+    throw new ConfigurationError(
+      "MoonXClient: publishableKey must start with 'moon_pk_' (got a string that doesn't \u2014 did you pass a secret key by mistake?)"
+    );
+  }
+  if (input.secretKey !== void 0 && !input.secretKey.startsWith("moon_sk_")) {
+    throw new ConfigurationError(
+      "MoonXClient: secretKey must start with 'moon_sk_' (got a string that doesn't)"
+    );
+  }
+  const issuer = input.issuer ?? DEFAULT_ISSUER;
+  if (!process.env.MOONX_AUTH_ISSUER_SILENT && input.issuer === void 0) {
+    console.warn(
+      `[@moon-x/node-sdk] issuer not set on MoonXClient \u2014 defaulting to ${DEFAULT_ISSUER}. Tokens issued by any other MoonX deployment will fail verification.`
+    );
+  }
+  return {
+    publishableKey: input.publishableKey,
+    secretKey: input.secretKey,
+    issuer,
+    baseUrl: input.baseUrl ?? issuer,
+    jwksTtlMs: input.jwksTtlMs ?? 5 * 60 * 1e3,
+    appResolveTtlMs: input.appResolveTtlMs ?? 60 * 60 * 1e3,
+    fetch: input.fetch ?? globalThis.fetch
+  };
+}
+
+// src/client.ts
+var MoonXClient = class {
+  constructor(input) {
+    const cfg = resolveConfig(input);
+    this.auth = new Auth({
+      baseUrl: cfg.baseUrl,
+      publishableKey: cfg.publishableKey,
+      expectedIssuer: cfg.issuer,
+      jwksTtlMs: cfg.jwksTtlMs,
+      appResolveTtlMs: cfg.appResolveTtlMs,
+      fetch: cfg.fetch
+    });
+  }
+};
+export {
+  AppResolutionError,
+  AudienceMismatchError,
+  ConfigurationError,
+  ExpiredTokenError,
+  InvalidTokenError,
+  IssuerMismatchError,
+  JwksFetchError,
+  KidMismatchError,
+  MalformedTokenError,
+  MoonXClient,
+  MoonXError,
+  SubjectMismatchError,
+  UnsupportedAlgorithmError
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@moon-x/node-sdk",
+  "version": "0.1.0",
+  "description": "MoonX server-side SDK for Node.js. Verify MoonX-issued access + identity tokens with zero runtime dependencies.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "moonx",
+    "moonpay",
+    "auth",
+    "jwt",
+    "jwks",
+    "wallet",
+    "sdk"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@moon-x/core": "0.2.0"
+  },
+  "devDependencies": {
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "1.6.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist .turbo node_modules"
+  }
+}