@moon-x/node-sdk 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# @moon-x/node-sdk
+
+MoonX server-side SDK for Node.js. Verify MoonX-issued access and identity tokens with **zero runtime dependencies**.
+
+Works in Node 18+, Cloudflare Workers, Vercel Edge, Bun, and Deno — anywhere `globalThis.crypto.subtle` and `fetch` are available.
+
+## Install
+
+```bash
+npm i @moon-x/node-sdk
+# or
+pnpm add @moon-x/node-sdk
+```
+
+## Quick start
+
+```ts
+import { MoonXClient } from "@moon-x/node-sdk";
+
+const moonx = new MoonXClient({
+  publishableKey: process.env.MOONX_PUBLISHABLE_KEY!,
+  issuer: process.env.MOONX_AUTH_ISSUER, // optional, defaults to https://api.moonx-dev.com
+});
+
+// In a Next.js route / Express handler / etc.
+const session = await moonx.auth.verifySession({
+  accessToken: req.headers["x-moonx-access-token"]!,
+  identityToken: req.headers["x-moonx-identity-token"],
+});
+
+// session.access.sub        — user id
+// session.access.sid        — session id
+// session.identity?.email   — OIDC profile claim (present when identity token forwarded)
+// session.identity?.name
+// session.identity?.picture
+```
+
+## What it does
+
+When a MoonX-authenticated user calls your backend, the request carries one or both of:
+
+| Header | Token | Carries |
+|---|---|---|
+| `X-MoonX-Access-Token` | Access token | Minimal authorization claims (`sub`, `sid`, `aud`, `iss`, `exp`) |
+| `X-MoonX-Identity-Token` | Identity token | OIDC profile claims (`email`, `name`, `picture`, etc.) |
+
+`verifySession()` runs the full canonical check on both:
+
+1. Pin **audience** to your app id (rejects tokens from other MoonX apps even if cryptographically valid).
+2. Pin **issuer** to your configured MoonX deployment.
+3. Fetch the per-app public **JWKS** from MoonX (cached 5 min by default).
+4. Verify the **ES256 signature** against the fetched key.
+5. Check the token hasn't **expired**.
+6. (Identity token path) Verify the identity token's `sub` matches the access token's `sub` — closes the swap-in-someone-else's-identity-token attack.
+
+No shared secret with MoonX is required. The verification runs entirely against the public JWKS.
+
+## API
+
+### `new MoonXClient(config)`
+
+Construct once per process. Holds in-memory caches; reuse across requests.
+
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `publishableKey` | `string` | Yes | — |
+| `secretKey` | `string` | No (v0.1 unused) | — |
+| `issuer` | `string` | No | `https://api.moonx-dev.com` |
+| `baseUrl` | `string` | No | Same as `issuer` |
+| `jwksTtlMs` | `number` | No | `300_000` (5 min) |
+| `appResolveTtlMs` | `number` | No | `3_600_000` (1 hour) |
+| `fetch` | `typeof fetch` | No | `globalThis.fetch` |
+
+The publishable key (`moon_pk_*`) is the same one your iframe / browser SDK uses. It's safe to put in any env var, but in node-sdk it typically reads from a server-only env var alongside the secret key. The secret key (`moon_sk_*`) field is reserved for v0.2 (data + swaps modules).
+
+### `client.auth.verifyAccessToken(token)`
+
+Returns `Promise<AccessTokenClaims>`. Throws a `MoonXError` subclass on any failure.
+
+### `client.auth.verifyIdentityToken(token)`
+
+Returns `Promise<IdentityTokenClaims>`. Throws a `MoonXError` subclass on any failure.
+
+### `client.auth.verifySession({ accessToken, identityToken? })`
+
+Returns `Promise<{ access: AccessTokenClaims, identity: IdentityTokenClaims | null }>`. Identity is `null` when the caller didn't forward an identity token.
+
+Canonical entry point — use this from request handlers. Cross-checks the two tokens' subjects when both are present.
+
+## Errors
+
+All thrown errors extend `MoonXError`, which carries a `.code` property for programmatic handling:
+
+```ts
+import {
+  MoonXError,
+  ExpiredTokenError,
+  InvalidTokenError,
+  AudienceMismatchError,
+  SubjectMismatchError,
+  // ...
+} from "@moon-x/node-sdk";
+
+try {
+  await moonx.auth.verifySession({ accessToken, identityToken });
+} catch (err) {
+  if (err instanceof ExpiredTokenError) {
+    return new Response("session expired", { status: 401 });
+  }
+  if (err instanceof MoonXError) {
+    return new Response(err.message, { status: 401 });
+  }
+  throw err;
+}
+```
+
+### Error codes
+
+| Class | `.code` | Meaning |
+|---|---|---|
+| `MalformedTokenError` | `malformed_token` | Not a well-formed JWT |
+| `InvalidTokenError` | `invalid_signature` | Signature didn't verify against the JWKS |
+| `ExpiredTokenError` | `expired_token` | `exp` claim is in the past |
+| `AudienceMismatchError` | `audience_mismatch` | Token's `aud` ≠ this client's app id |
+| `IssuerMismatchError` | `issuer_mismatch` | Token's `iss` ≠ configured issuer |
+| `SubjectMismatchError` | `subject_mismatch` | Identity token's `sub` ≠ access token's `sub` |
+| `KidMismatchError` | `kid_mismatch` | Token's `kid` ≠ current JWKS key id (likely rotation) |
+| `UnsupportedAlgorithmError` | `unsupported_algorithm` | Token uses something other than ES256 |
+| `JwksFetchError` | `jwks_fetch_failed` | Couldn't fetch the JWKS from MoonX |
+| `AppResolutionError` | `app_resolution_failed` | Publishable-key → app-id lookup failed |
+| `ConfigurationError` | `configuration_error` | Bad `MoonXClient` config (e.g. swapped pk/sk) |
+
+### Type imports
+
+`AccessTokenClaims`, `IdentityTokenClaims`, `BaseTokenClaims`, and `VerifiedSession` are also exported from `@moon-x/core/types` — the single source of truth shared with the browser + RN SDKs. Either import path works:
+
+```ts
+// From node-sdk (convenience re-export):
+import type { AccessTokenClaims } from "@moon-x/node-sdk";
+
+// From core directly (matches the browser SDK call sites):
+import type { AccessTokenClaims } from "@moon-x/core/types";
+```
+
+## Why no JWT library?
+
+Auth providers ship server SDKs partly to abstract away `jose`-style JWT libraries, but every dependency is a supply-chain surface. This SDK uses only Web Crypto (`globalThis.crypto.subtle`) and `fetch`, both Node 18+ standard library. Result: a single `npm install` line on your audit.
+
+## Roadmap
+
+- **v0.1 (current)** — auth: `verifyAccessToken`, `verifyIdentityToken`, `verifySession`.
+- **v0.2 (pending [MX-124](https://linear.app/moonpay/issue/MX-124))** — adds `client.tokens.*`, `client.wallets.*`, `client.swaps.*` once the backend's secret-key middleware lands.

package/dist/index.d.mts

@@ -0,0 +1,163 @@
+import { AccessTokenClaims, IdentityTokenClaims, VerifiedSession } from '@moon-x/core/types';
+export { AccessTokenClaims, BaseTokenClaims, IdentityTokenClaims, VerifiedSession } from '@moon-x/core/types';
+
+interface AuthOptions {
+    baseUrl: string;
+    publishableKey: string;
+    expectedIssuer: string;
+    jwksTtlMs?: number;
+    appResolveTtlMs?: number;
+    fetch?: typeof fetch;
+}
+declare class Auth {
+    private readonly resolver;
+    private readonly jwks;
+    private readonly expectedIssuer;
+    constructor(opts: AuthOptions);
+    /**
+     * Verify an access token. Returns the claims on success; throws a
+     * typed `MoonXError` subclass on any failure.
+     */
+    verifyAccessToken(token: string): Promise<AccessTokenClaims>;
+    /**
+     * Verify an identity token. Returns the OIDC profile claims on
+     * success; throws a typed `MoonXError` subclass on any failure.
+     */
+    verifyIdentityToken(token: string): Promise<IdentityTokenClaims>;
+    /**
+     * 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.
+     */
+    verifySession(args: {
+        accessToken: string;
+        identityToken?: string | null;
+    }): Promise<VerifiedSession>;
+}
+
+interface MoonXClientConfig {
+    /**
+     * Required. The publishable key (`moon_pk_*`) for your MoonX app.
+     * Used to resolve the app id (which scopes audience pinning and
+     * JWKS lookups). Safe to also expose to the browser — that's what
+     * publishable keys are for — but in node-sdk it typically reads
+     * from a server env var.
+     */
+    publishableKey: string;
+    /**
+     * Optional. The secret key (`moon_sk_*`) for your MoonX app. Required
+     * for privileged endpoints (datalayer, swaps) — not used by v0.1
+     * (auth-only). Reserved for the v0.2 surface expansion.
+     *
+     * NEVER hardcode. NEVER expose to the browser. Always read from a
+     * server-only env var.
+     */
+    secretKey?: string;
+    /**
+     * Optional. The MoonX deployment that issued your tokens. Defaults
+     * to `https://api.moonx-dev.com`. Override when running against a
+     * different environment.
+     *
+     * If unset and the default doesn't match your deployment, every
+     * token will fail the issuer check with a clean `IssuerMismatchError`
+     * — easier to debug than a silent 401.
+     */
+    issuer?: string;
+    /**
+     * Optional. Base URL for MoonX API calls. Defaults to the same value
+     * as `issuer` when unset.
+     */
+    baseUrl?: string;
+    /**
+     * Optional. JWKS cache TTL in milliseconds. Default 5 minutes. Lower
+     * if you're concerned about key rotation responsiveness; higher if
+     * you want fewer round-trips.
+     */
+    jwksTtlMs?: number;
+    /**
+     * Optional. Cache TTL in milliseconds for the publishable-key → app-id
+     * lookup. Default 1 hour. The mapping is effectively immutable, so a
+     * long TTL is safe.
+     */
+    appResolveTtlMs?: number;
+    /**
+     * Optional. Override `fetch`. Useful in tests. Defaults to
+     * `globalThis.fetch`.
+     */
+    fetch?: typeof fetch;
+}
+
+/**
+ * MoonXClient is the entry point for the node SDK. Construct once per
+ * process and reuse across requests — the client holds in-memory caches
+ * for the publishable-key → app-id mapping and the per-app JWKS.
+ *
+ *     import { MoonXClient } from "@moon-x/node-sdk";
+ *
+ *     const moonx = new MoonXClient({
+ *       publishableKey: process.env.MOONX_PUBLISHABLE_KEY!,
+ *       issuer: process.env.MOONX_AUTH_ISSUER,
+ *     });
+ *
+ *     // In a Next.js route handler / Express handler / etc.
+ *     const session = await moonx.auth.verifySession({
+ *       accessToken: req.headers["x-moonx-access-token"]!,
+ *       identityToken: req.headers["x-moonx-identity-token"],
+ *     });
+ *     // session.access.sub        — user id
+ *     // session.access.sid        — session id
+ *     // session.identity?.email   — OIDC profile claim (when identity token sent)
+ *     // session.identity?.name    — etc.
+ *
+ * v0.1 ships the `auth` namespace only. The `tokens`, `wallets`, and
+ * `swaps` namespaces will land in v0.2 once the secret-key middleware
+ * (MX-124) ships on the backend.
+ */
+declare class MoonXClient {
+    readonly auth: Auth;
+    constructor(input: MoonXClientConfig);
+}
+
+type MoonXErrorCode = "malformed_token" | "invalid_signature" | "expired_token" | "audience_mismatch" | "issuer_mismatch" | "subject_mismatch" | "kid_mismatch" | "unsupported_algorithm" | "jwks_fetch_failed" | "app_resolution_failed" | "configuration_error";
+declare class MoonXError extends Error {
+    readonly code: MoonXErrorCode;
+    constructor(code: MoonXErrorCode, message: string);
+}
+declare class MalformedTokenError extends MoonXError {
+    constructor(message?: string);
+}
+declare class InvalidTokenError extends MoonXError {
+    constructor(message?: string);
+}
+declare class ExpiredTokenError extends MoonXError {
+    constructor(message?: string);
+}
+declare class AudienceMismatchError extends MoonXError {
+    constructor(expected: string, got: string | string[], message?: string);
+}
+declare class IssuerMismatchError extends MoonXError {
+    constructor(expected: string, got: string, message?: string);
+}
+declare class SubjectMismatchError extends MoonXError {
+    constructor(message?: string);
+}
+declare class KidMismatchError extends MoonXError {
+    constructor(message?: string);
+}
+declare class UnsupportedAlgorithmError extends MoonXError {
+    constructor(alg: string);
+}
+declare class JwksFetchError extends MoonXError {
+    constructor(message: string);
+}
+declare class AppResolutionError extends MoonXError {
+    constructor(message: string);
+}
+declare class ConfigurationError extends MoonXError {
+    constructor(message: string);
+}
+
+export { AppResolutionError, AudienceMismatchError, ConfigurationError, ExpiredTokenError, InvalidTokenError, IssuerMismatchError, JwksFetchError, KidMismatchError, MalformedTokenError, MoonXClient, type MoonXClientConfig, MoonXError, type MoonXErrorCode, SubjectMismatchError, UnsupportedAlgorithmError };

package/dist/index.d.ts

@@ -0,0 +1,163 @@
+import { AccessTokenClaims, IdentityTokenClaims, VerifiedSession } from '@moon-x/core/types';
+export { AccessTokenClaims, BaseTokenClaims, IdentityTokenClaims, VerifiedSession } from '@moon-x/core/types';
+
+interface AuthOptions {
+    baseUrl: string;
+    publishableKey: string;
+    expectedIssuer: string;
+    jwksTtlMs?: number;
+    appResolveTtlMs?: number;
+    fetch?: typeof fetch;
+}
+declare class Auth {
+    private readonly resolver;
+    private readonly jwks;
+    private readonly expectedIssuer;
+    constructor(opts: AuthOptions);
+    /**
+     * Verify an access token. Returns the claims on success; throws a
+     * typed `MoonXError` subclass on any failure.
+     */
+    verifyAccessToken(token: string): Promise<AccessTokenClaims>;
+    /**
+     * Verify an identity token. Returns the OIDC profile claims on
+     * success; throws a typed `MoonXError` subclass on any failure.
+     */
+    verifyIdentityToken(token: string): Promise<IdentityTokenClaims>;
+    /**
+     * 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.
+     */
+    verifySession(args: {
+        accessToken: string;
+        identityToken?: string | null;
+    }): Promise<VerifiedSession>;
+}
+
+interface MoonXClientConfig {
+    /**
+     * Required. The publishable key (`moon_pk_*`) for your MoonX app.
+     * Used to resolve the app id (which scopes audience pinning and
+     * JWKS lookups). Safe to also expose to the browser — that's what
+     * publishable keys are for — but in node-sdk it typically reads
+     * from a server env var.
+     */
+    publishableKey: string;
+    /**
+     * Optional. The secret key (`moon_sk_*`) for your MoonX app. Required
+     * for privileged endpoints (datalayer, swaps) — not used by v0.1
+     * (auth-only). Reserved for the v0.2 surface expansion.
+     *
+     * NEVER hardcode. NEVER expose to the browser. Always read from a
+     * server-only env var.
+     */
+    secretKey?: string;
+    /**
+     * Optional. The MoonX deployment that issued your tokens. Defaults
+     * to `https://api.moonx-dev.com`. Override when running against a
+     * different environment.
+     *
+     * If unset and the default doesn't match your deployment, every
+     * token will fail the issuer check with a clean `IssuerMismatchError`
+     * — easier to debug than a silent 401.
+     */
+    issuer?: string;
+    /**
+     * Optional. Base URL for MoonX API calls. Defaults to the same value
+     * as `issuer` when unset.
+     */
+    baseUrl?: string;
+    /**
+     * Optional. JWKS cache TTL in milliseconds. Default 5 minutes. Lower
+     * if you're concerned about key rotation responsiveness; higher if
+     * you want fewer round-trips.
+     */
+    jwksTtlMs?: number;
+    /**
+     * Optional. Cache TTL in milliseconds for the publishable-key → app-id
+     * lookup. Default 1 hour. The mapping is effectively immutable, so a
+     * long TTL is safe.
+     */
+    appResolveTtlMs?: number;
+    /**
+     * Optional. Override `fetch`. Useful in tests. Defaults to
+     * `globalThis.fetch`.
+     */
+    fetch?: typeof fetch;
+}
+
+/**
+ * MoonXClient is the entry point for the node SDK. Construct once per
+ * process and reuse across requests — the client holds in-memory caches
+ * for the publishable-key → app-id mapping and the per-app JWKS.
+ *
+ *     import { MoonXClient } from "@moon-x/node-sdk";
+ *
+ *     const moonx = new MoonXClient({
+ *       publishableKey: process.env.MOONX_PUBLISHABLE_KEY!,
+ *       issuer: process.env.MOONX_AUTH_ISSUER,
+ *     });
+ *
+ *     // In a Next.js route handler / Express handler / etc.
+ *     const session = await moonx.auth.verifySession({
+ *       accessToken: req.headers["x-moonx-access-token"]!,
+ *       identityToken: req.headers["x-moonx-identity-token"],
+ *     });
+ *     // session.access.sub        — user id
+ *     // session.access.sid        — session id
+ *     // session.identity?.email   — OIDC profile claim (when identity token sent)
+ *     // session.identity?.name    — etc.
+ *
+ * v0.1 ships the `auth` namespace only. The `tokens`, `wallets`, and
+ * `swaps` namespaces will land in v0.2 once the secret-key middleware
+ * (MX-124) ships on the backend.
+ */
+declare class MoonXClient {
+    readonly auth: Auth;
+    constructor(input: MoonXClientConfig);
+}
+
+type MoonXErrorCode = "malformed_token" | "invalid_signature" | "expired_token" | "audience_mismatch" | "issuer_mismatch" | "subject_mismatch" | "kid_mismatch" | "unsupported_algorithm" | "jwks_fetch_failed" | "app_resolution_failed" | "configuration_error";
+declare class MoonXError extends Error {
+    readonly code: MoonXErrorCode;
+    constructor(code: MoonXErrorCode, message: string);
+}
+declare class MalformedTokenError extends MoonXError {
+    constructor(message?: string);
+}
+declare class InvalidTokenError extends MoonXError {
+    constructor(message?: string);
+}
+declare class ExpiredTokenError extends MoonXError {
+    constructor(message?: string);
+}
+declare class AudienceMismatchError extends MoonXError {
+    constructor(expected: string, got: string | string[], message?: string);
+}
+declare class IssuerMismatchError extends MoonXError {
+    constructor(expected: string, got: string, message?: string);
+}
+declare class SubjectMismatchError extends MoonXError {
+    constructor(message?: string);
+}
+declare class KidMismatchError extends MoonXError {
+    constructor(message?: string);
+}
+declare class UnsupportedAlgorithmError extends MoonXError {
+    constructor(alg: string);
+}
+declare class JwksFetchError extends MoonXError {
+    constructor(message: string);
+}
+declare class AppResolutionError extends MoonXError {
+    constructor(message: string);
+}
+declare class ConfigurationError extends MoonXError {
+    constructor(message: string);
+}
+
+export { AppResolutionError, AudienceMismatchError, ConfigurationError, ExpiredTokenError, InvalidTokenError, IssuerMismatchError, JwksFetchError, KidMismatchError, MalformedTokenError, MoonXClient, type MoonXClientConfig, MoonXError, type MoonXErrorCode, SubjectMismatchError, UnsupportedAlgorithmError };