@socketfi/server 1.0.0

package/LICENSE

@@ -0,0 +1 @@
+Copyright 2026 SocketFi

package/README.md

@@ -0,0 +1,199 @@
+# @socketfi/server
+
+Server-side SDK for verifying SocketFi authentication tokens.
+
+---
+
+## Install
+
+```bash
+npm install @socketfi/server
+```
+
+---
+
+## Requirements
+
+- Node.js 18+
+
+---
+
+## Usage
+
+### ES Modules
+
+```ts
+import express from "express";
+import { SocketFi } from "@socketfi/server";
+
+const app = express();
+
+app.use(express.json());
+
+const socketfi = new SocketFi({
+  clientId: process.env.APP_CLIENT_ID!,
+  secretKey: process.env.APP_SECRET_KEY!,
+});
+
+app.post("/api/auth/verify", async (req, res) => {
+  try {
+    const authHeader = req.headers.authorization;
+
+    if (!authHeader?.startsWith("Bearer ")) {
+      return res.status(401).json({
+        success: false,
+        error: "Authorization header missing",
+      });
+    }
+
+    const token = authHeader.split(" ")[1];
+
+    const session = await socketfi.verifyAuth(token);
+
+    return res.json({
+      success: true,
+      user: {
+        userId: session.userId,
+        username: session.username,
+        wallet: session.wallet,
+      },
+    });
+  } catch (error) {
+    return res.status(401).json({
+      success: false,
+      error: error instanceof Error ? error.message : "Invalid SocketFi token",
+    });
+  }
+});
+```
+
+---
+
+### CommonJS
+
+```js
+const { SocketFi } = require("@socketfi/server");
+```
+
+---
+
+## Environment variables
+
+```env
+APP_CLIENT_ID=project_xxx
+APP_SECRET_KEY=sk_live_xxx
+```
+
+> `secretKey` must only be used on trusted backend servers.
+> Never expose it in browsers, mobile apps, or client-side code.
+
+---
+
+## Verification model
+
+SocketFi access tokens are signed using RS256 asymmetric cryptography.
+
+The SDK validates:
+
+- Token signature
+- Token expiration
+- Issuer
+- Audience (`clientId`)
+- Token type (`access`)
+- Signing algorithm
+
+Verification flow:
+
+- SocketFi private keys sign tokens.
+- SocketFi public keys verify tokens.
+- Your project's `secretKey` authenticates requests to the SocketFi key service.
+- Public keys are cached in memory for improved performance.
+- The SDK automatically refreshes public keys when:
+
+  - the cache expires
+  - token verification fails due to signature mismatch
+  - a JWT `kid` mismatch is detected
+
+---
+
+## Supported runtimes
+
+- Node.js
+- Express
+- Next.js API routes
+- NestJS
+- Fastify
+- Serverless functions
+
+Edge runtimes are not currently supported.
+
+---
+
+## Config
+
+```ts
+const socketfi = new SocketFi({
+  clientId: "project_xxx",
+  secretKey: "sk_live_xxx",
+});
+```
+
+---
+
+## API
+
+### `verifyAuth(token)`
+
+Verifies a SocketFi-issued access token and returns the authenticated session payload.
+
+```ts
+const session = await socketfi.verifyAuth(token);
+```
+
+Returned payload:
+
+```ts
+{
+  userId: string;
+  accountId?: string;
+  username?: string;
+  wallet?: SocketFiWallet;
+  clientId: string;
+  origin: string;
+  expiresAt?: Date;
+  accessToken: string;
+  raw: SocketFiAccessTokenPayload;
+}
+```
+
+`verifyAuth()` throws if:
+
+- the token is invalid
+- the token is expired
+- the token audience does not match your `clientId`
+- the token signature verification fails
+- the token type is invalid
+
+---
+
+### `clearKeyCache()`
+
+Clears the in-memory SocketFi public key cache.
+
+```ts
+socketfi.clearKeyCache();
+```
+
+---
+
+## Stability
+
+This SDK follows semantic versioning.
+
+Breaking API changes are introduced only in major releases.
+
+---
+
+## License
+
+Apache-2.0

package/dist/index.cjs

@@ -0,0 +1,412 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SocketFi: () => SocketFi,
+  SocketFiError: () => SocketFiError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/keys/public-key-cache.ts
+var import_jose = require("jose");
+
+// src/errors/SocketFiError.ts
+var SocketFiError = class extends Error {
+  code;
+  statusCode;
+  details;
+  cause;
+  constructor(params) {
+    super(params.message);
+    this.name = "SocketFiError";
+    this.code = params.code;
+    if (params.statusCode !== void 0) {
+      this.statusCode = params.statusCode;
+    }
+    if (params.details !== void 0) {
+      this.details = params.details;
+    }
+    if (params.cause !== void 0) {
+      this.cause = params.cause;
+    }
+  }
+};
+
+// src/errors/error-codes.ts
+var SOCKETFI_ERROR_CODES = {
+  CONFIG_ERROR: "config_error",
+  AUTH_TOKEN_REQUIRED: "auth_token_required",
+  INVALID_AUTH_TOKEN: "invalid_auth_token",
+  INVALID_TOKEN_TYPE: "invalid_token_type",
+  INVALID_CLIENT_ID: "invalid_client_id",
+  INVALID_ISSUER: "invalid_issuer",
+  INVALID_AUDIENCE: "invalid_audience",
+  PUBLIC_KEY_FETCH_FAILED: "public_key_fetch_failed",
+  PUBLIC_KEY_MISSING: "public_key_missing",
+  PUBLIC_KEY_IMPORT_FAILED: "public_key_import_failed",
+  PUBLIC_KEY_NOT_LOADED: "public_key_not_loaded",
+  NETWORK_ERROR: "network_error",
+  REQUEST_TIMEOUT: "request_timeout"
+};
+
+// src/http/request.ts
+async function requestJson(url, options) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method: options.method ?? "GET",
+      headers: {
+        accept: "application/json",
+        ...options.headers
+      },
+      signal: controller.signal
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      throw new SocketFiError({
+        code: SOCKETFI_ERROR_CODES.NETWORK_ERROR,
+        message: "socketfi_request_failed",
+        statusCode: res.status,
+        details: { url, response: data }
+      });
+    }
+    return data;
+  } catch (error) {
+    if (error?.name === "AbortError") {
+      throw new SocketFiError({
+        code: SOCKETFI_ERROR_CODES.REQUEST_TIMEOUT,
+        message: "socketfi_request_timeout",
+        statusCode: 408,
+        cause: error,
+        details: { url }
+      });
+    }
+    if (error instanceof SocketFiError) {
+      throw error;
+    }
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.NETWORK_ERROR,
+      message: "socketfi_request_failed",
+      cause: error,
+      details: { url }
+    });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// src/utils/normalize-url.ts
+function normalizeBaseUrl(url) {
+  return url.replace(/\/+$/, "");
+}
+function joinUrl(baseUrl, path) {
+  const cleanBase = normalizeBaseUrl(baseUrl);
+  const cleanPath = path.startsWith("/") ? path : `/${path}`;
+  return `${cleanBase}${cleanPath}`;
+}
+
+// src/config/defaults.ts
+var DEFAULT_SOCKETFI_API_URL = "https://api.socket.fi";
+var DEFAULT_SOCKETFI_ISSUER = "https://socket.fi";
+var DEFAULT_KEY_ENDPOINT = "/.well-known/socketfi-public-key";
+var DEFAULT_REQUEST_TIMEOUT_MS = 8e3;
+var DEFAULT_ALGORITHM = "RS256";
+var DEFAULT_KEY_CACHE_TTL_MS = 60 * 60 * 24 * 1e3;
+
+// src/keys/fetch-public-key.ts
+async function fetchSocketFiPublicKey(params) {
+  const url = joinUrl(
+    params.apiUrl,
+    params.keyEndpoint ?? DEFAULT_KEY_ENDPOINT
+  );
+  const data = await requestJson(url, {
+    timeoutMs: params.timeoutMs,
+    headers: {
+      "x-socketfi-client-secret": params.clientSecret
+    }
+  });
+  if (!data?.publicKey || typeof data.publicKey !== "string") {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.PUBLIC_KEY_MISSING,
+      message: "socketfi_public_key_missing",
+      statusCode: 502
+    });
+  }
+  if (data.alg !== "RS256") {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.PUBLIC_KEY_FETCH_FAILED,
+      message: "unsupported_socketfi_public_key_algorithm",
+      statusCode: 502,
+      details: { alg: data.alg }
+    });
+  }
+  return data;
+}
+
+// src/keys/public-key-cache.ts
+var PublicKeyCache = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  cached = null;
+  refreshPromise = null;
+  async get() {
+    if (this.cached && this.cached.expiresAt > Date.now()) {
+      return this.cached;
+    }
+    return this.refresh();
+  }
+  async refresh() {
+    if (!this.refreshPromise) {
+      this.refreshPromise = this.fetchAndImport().finally(() => {
+        this.refreshPromise = null;
+      });
+    }
+    return this.refreshPromise;
+  }
+  clear() {
+    this.cached = null;
+    this.refreshPromise = null;
+  }
+  async fetchAndImport() {
+    const response = await fetchSocketFiPublicKey({
+      apiUrl: this.config.apiUrl,
+      clientSecret: this.config.clientSecret,
+      timeoutMs: this.config.timeoutMs,
+      ...this.config.keyEndpoint ? { keyEndpoint: this.config.keyEndpoint } : {}
+    });
+    try {
+      const importedKey = await (0, import_jose.importSPKI)(
+        response.publicKey,
+        DEFAULT_ALGORITHM
+      );
+      const now = Date.now();
+      this.cached = {
+        kid: response.kid,
+        alg: response.alg,
+        publicKeyPem: response.publicKey,
+        importedKey,
+        fetchedAt: now,
+        expiresAt: now + this.config.cacheTtlMs
+      };
+      return this.cached;
+    } catch (error) {
+      throw new SocketFiError({
+        code: SOCKETFI_ERROR_CODES.PUBLIC_KEY_IMPORT_FAILED,
+        message: "socketfi_public_key_import_failed",
+        statusCode: 502,
+        cause: error
+      });
+    }
+  }
+};
+
+// src/auth/verifyAuth.ts
+var import_jose2 = require("jose");
+async function verifyAuth(params) {
+  const token = params.token;
+  if (!token || typeof token !== "string") {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.AUTH_TOKEN_REQUIRED,
+      message: "auth_token_required",
+      statusCode: 401
+    });
+  }
+  if (params.options?.forceRefreshKey) {
+    await params.keyCache.refresh();
+  }
+  try {
+    const result = await verifyWithCache(params);
+    return {
+      ...result,
+      accessToken: token
+    };
+  } catch (error) {
+    if (!shouldRefreshKey(error)) {
+      throw normalizeVerifyError(error);
+    }
+    await params.keyCache.refresh();
+    try {
+      const result = await verifyWithCache(params);
+      return {
+        ...result,
+        accessToken: token
+      };
+    } catch (retryError) {
+      throw normalizeVerifyError(retryError, true);
+    }
+  }
+}
+async function verifyWithCache(params) {
+  const header = (0, import_jose2.decodeProtectedHeader)(params.token);
+  if (header.alg !== DEFAULT_ALGORITHM) {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_AUTH_TOKEN,
+      message: "unsupported_auth_token_algorithm",
+      statusCode: 401,
+      details: { alg: header.alg }
+    });
+  }
+  const cachedKey = await params.keyCache.get();
+  if (header.kid && cachedKey.kid && header.kid !== cachedKey.kid) {
+    await params.keyCache.refresh();
+  }
+  const key = (await params.keyCache.get()).importedKey;
+  const { payload } = await (0, import_jose2.jwtVerify)(params.token, key, {
+    issuer: params.issuer,
+    audience: params.clientId,
+    algorithms: [DEFAULT_ALGORITHM]
+  });
+  return normalizeAccessPayload(payload, params.clientId);
+}
+function normalizeAccessPayload(payload, clientId) {
+  const typed = payload;
+  if (typed.type !== "access") {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_TOKEN_TYPE,
+      message: "invalid_token_type",
+      statusCode: 401,
+      details: { type: typed.type }
+    });
+  }
+  if (typed.clientId !== clientId) {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_CLIENT_ID,
+      message: "invalid_client_id",
+      statusCode: 401,
+      details: { expected: clientId, received: typed.clientId }
+    });
+  }
+  if (!typed.sub || typeof typed.sub !== "string") {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_AUTH_TOKEN,
+      message: "invalid_subject",
+      statusCode: 401
+    });
+  }
+  if (!typed.origin || typeof typed.origin !== "string") {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_AUTH_TOKEN,
+      message: "invalid_origin",
+      statusCode: 401
+    });
+  }
+  return {
+    userId: typed.sub,
+    ...typeof typed.accountId === "string" ? { accountId: typed.accountId } : {},
+    ...typeof typed.username === "string" ? { username: typed.username } : {},
+    wallet: typed.wallet,
+    clientId: typed.clientId,
+    origin: typed.origin,
+    ...typeof typed.exp === "number" ? { expiresAt: new Date(typed.exp * 1e3) } : {},
+    raw: typed
+  };
+}
+function shouldRefreshKey(error) {
+  return error instanceof import_jose2.errors.JWSSignatureVerificationFailed || error instanceof import_jose2.errors.JWSInvalid || error?.code === "ERR_JWS_SIGNATURE_VERIFICATION_FAILED" || String(error?.message || "").includes(
+    "signature verification failed"
+  );
+}
+function normalizeVerifyError(error, afterRefresh = false) {
+  if (error instanceof SocketFiError) return error;
+  if (afterRefresh && (error instanceof import_jose2.errors.JWSSignatureVerificationFailed || error?.code === "ERR_JWS_SIGNATURE_VERIFICATION_FAILED")) {
+    return new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_AUTH_TOKEN,
+      message: "socketfi_token_signature_mismatch_after_key_refresh",
+      statusCode: 401
+    });
+  }
+  if (error instanceof import_jose2.errors.JWTExpired) {
+    return new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_AUTH_TOKEN,
+      message: "auth_token_expired",
+      statusCode: 401,
+      details: {
+        claim: "exp"
+      }
+    });
+  }
+  if (error instanceof import_jose2.errors.JWTClaimValidationFailed) {
+    return new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_AUTH_TOKEN,
+      message: "invalid_auth_token_claim",
+      statusCode: 401,
+      details: {
+        claim: error.claim,
+        reason: error.reason
+      }
+    });
+  }
+  return new SocketFiError({
+    code: SOCKETFI_ERROR_CODES.INVALID_AUTH_TOKEN,
+    message: "invalid_auth_token",
+    statusCode: 401
+  });
+}
+
+// src/utils/assert.ts
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.CONFIG_ERROR,
+      message: `${name}_required`,
+      statusCode: 400,
+      details: { field: name }
+    });
+  }
+}
+
+// src/socketfi.ts
+var SocketFi = class {
+  clientId;
+  secretKey;
+  keyCache;
+  constructor(config) {
+    assertNonEmptyString(config.clientId, "clientId");
+    assertNonEmptyString(config.secretKey, "secretKey");
+    this.clientId = config.clientId;
+    this.secretKey = config.secretKey;
+    this.keyCache = new PublicKeyCache({
+      apiUrl: DEFAULT_SOCKETFI_API_URL,
+      clientSecret: this.secretKey,
+      timeoutMs: DEFAULT_REQUEST_TIMEOUT_MS,
+      cacheTtlMs: DEFAULT_KEY_CACHE_TTL_MS
+    });
+  }
+  async verifyAuth(token) {
+    return verifyAuth({
+      token,
+      clientId: this.clientId,
+      issuer: DEFAULT_SOCKETFI_ISSUER,
+      keyCache: this.keyCache
+    });
+  }
+  clearKeyCache() {
+    this.keyCache.clear();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SocketFi,
+  SocketFiError
+});

package/dist/index.d.cts

@@ -0,0 +1,71 @@
+type SocketFiConfig = {
+    clientId: string;
+    secretKey: string;
+};
+type SocketFiAccessTokenPayload = {
+    sub: string;
+    accountId?: string;
+    username?: string;
+    wallet?: unknown;
+    clientId: string;
+    origin: string;
+    type: "access";
+    iat?: number;
+    exp?: number;
+    iss?: string;
+    aud?: string | string[];
+    [key: string]: unknown;
+};
+type VerifyAuthResult = {
+    userId: string;
+    accountId?: string;
+    username?: string;
+    wallet: unknown;
+    clientId: string;
+    origin: string;
+    accessToken: string;
+    expiresAt?: Date;
+    raw: SocketFiAccessTokenPayload;
+};
+
+declare class SocketFi {
+    private readonly clientId;
+    private readonly secretKey;
+    private readonly keyCache;
+    constructor(config: SocketFiConfig);
+    verifyAuth(token: string): Promise<VerifyAuthResult>;
+    clearKeyCache(): void;
+}
+
+declare const SOCKETFI_ERROR_CODES: {
+    readonly CONFIG_ERROR: "config_error";
+    readonly AUTH_TOKEN_REQUIRED: "auth_token_required";
+    readonly INVALID_AUTH_TOKEN: "invalid_auth_token";
+    readonly INVALID_TOKEN_TYPE: "invalid_token_type";
+    readonly INVALID_CLIENT_ID: "invalid_client_id";
+    readonly INVALID_ISSUER: "invalid_issuer";
+    readonly INVALID_AUDIENCE: "invalid_audience";
+    readonly PUBLIC_KEY_FETCH_FAILED: "public_key_fetch_failed";
+    readonly PUBLIC_KEY_MISSING: "public_key_missing";
+    readonly PUBLIC_KEY_IMPORT_FAILED: "public_key_import_failed";
+    readonly PUBLIC_KEY_NOT_LOADED: "public_key_not_loaded";
+    readonly NETWORK_ERROR: "network_error";
+    readonly REQUEST_TIMEOUT: "request_timeout";
+};
+type SocketFiErrorCode = (typeof SOCKETFI_ERROR_CODES)[keyof typeof SOCKETFI_ERROR_CODES];
+
+declare class SocketFiError extends Error {
+    readonly code: SocketFiErrorCode;
+    readonly statusCode?: number;
+    readonly details?: Record<string, unknown>;
+    readonly cause?: unknown;
+    constructor(params: {
+        code: SocketFiErrorCode;
+        message: string;
+        statusCode?: number;
+        details?: Record<string, unknown>;
+        cause?: unknown;
+    });
+}
+
+export { SocketFi, type SocketFiConfig, SocketFiError, type VerifyAuthResult };

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+type SocketFiConfig = {
+    clientId: string;
+    secretKey: string;
+};
+type SocketFiAccessTokenPayload = {
+    sub: string;
+    accountId?: string;
+    username?: string;
+    wallet?: unknown;
+    clientId: string;
+    origin: string;
+    type: "access";
+    iat?: number;
+    exp?: number;
+    iss?: string;
+    aud?: string | string[];
+    [key: string]: unknown;
+};
+type VerifyAuthResult = {
+    userId: string;
+    accountId?: string;
+    username?: string;
+    wallet: unknown;
+    clientId: string;
+    origin: string;
+    accessToken: string;
+    expiresAt?: Date;
+    raw: SocketFiAccessTokenPayload;
+};
+
+declare class SocketFi {
+    private readonly clientId;
+    private readonly secretKey;
+    private readonly keyCache;
+    constructor(config: SocketFiConfig);
+    verifyAuth(token: string): Promise<VerifyAuthResult>;
+    clearKeyCache(): void;
+}
+
+declare const SOCKETFI_ERROR_CODES: {
+    readonly CONFIG_ERROR: "config_error";
+    readonly AUTH_TOKEN_REQUIRED: "auth_token_required";
+    readonly INVALID_AUTH_TOKEN: "invalid_auth_token";
+    readonly INVALID_TOKEN_TYPE: "invalid_token_type";
+    readonly INVALID_CLIENT_ID: "invalid_client_id";
+    readonly INVALID_ISSUER: "invalid_issuer";
+    readonly INVALID_AUDIENCE: "invalid_audience";
+    readonly PUBLIC_KEY_FETCH_FAILED: "public_key_fetch_failed";
+    readonly PUBLIC_KEY_MISSING: "public_key_missing";
+    readonly PUBLIC_KEY_IMPORT_FAILED: "public_key_import_failed";
+    readonly PUBLIC_KEY_NOT_LOADED: "public_key_not_loaded";
+    readonly NETWORK_ERROR: "network_error";
+    readonly REQUEST_TIMEOUT: "request_timeout";
+};
+type SocketFiErrorCode = (typeof SOCKETFI_ERROR_CODES)[keyof typeof SOCKETFI_ERROR_CODES];
+
+declare class SocketFiError extends Error {
+    readonly code: SocketFiErrorCode;
+    readonly statusCode?: number;
+    readonly details?: Record<string, unknown>;
+    readonly cause?: unknown;
+    constructor(params: {
+        code: SocketFiErrorCode;
+        message: string;
+        statusCode?: number;
+        details?: Record<string, unknown>;
+        cause?: unknown;
+    });
+}
+
+export { SocketFi, type SocketFiConfig, SocketFiError, type VerifyAuthResult };

package/dist/index.js

@@ -0,0 +1,388 @@
+// src/keys/public-key-cache.ts
+import { importSPKI } from "jose";
+
+// src/errors/SocketFiError.ts
+var SocketFiError = class extends Error {
+  code;
+  statusCode;
+  details;
+  cause;
+  constructor(params) {
+    super(params.message);
+    this.name = "SocketFiError";
+    this.code = params.code;
+    if (params.statusCode !== void 0) {
+      this.statusCode = params.statusCode;
+    }
+    if (params.details !== void 0) {
+      this.details = params.details;
+    }
+    if (params.cause !== void 0) {
+      this.cause = params.cause;
+    }
+  }
+};
+
+// src/errors/error-codes.ts
+var SOCKETFI_ERROR_CODES = {
+  CONFIG_ERROR: "config_error",
+  AUTH_TOKEN_REQUIRED: "auth_token_required",
+  INVALID_AUTH_TOKEN: "invalid_auth_token",
+  INVALID_TOKEN_TYPE: "invalid_token_type",
+  INVALID_CLIENT_ID: "invalid_client_id",
+  INVALID_ISSUER: "invalid_issuer",
+  INVALID_AUDIENCE: "invalid_audience",
+  PUBLIC_KEY_FETCH_FAILED: "public_key_fetch_failed",
+  PUBLIC_KEY_MISSING: "public_key_missing",
+  PUBLIC_KEY_IMPORT_FAILED: "public_key_import_failed",
+  PUBLIC_KEY_NOT_LOADED: "public_key_not_loaded",
+  NETWORK_ERROR: "network_error",
+  REQUEST_TIMEOUT: "request_timeout"
+};
+
+// src/http/request.ts
+async function requestJson(url, options) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method: options.method ?? "GET",
+      headers: {
+        accept: "application/json",
+        ...options.headers
+      },
+      signal: controller.signal
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      throw new SocketFiError({
+        code: SOCKETFI_ERROR_CODES.NETWORK_ERROR,
+        message: "socketfi_request_failed",
+        statusCode: res.status,
+        details: { url, response: data }
+      });
+    }
+    return data;
+  } catch (error) {
+    if (error?.name === "AbortError") {
+      throw new SocketFiError({
+        code: SOCKETFI_ERROR_CODES.REQUEST_TIMEOUT,
+        message: "socketfi_request_timeout",
+        statusCode: 408,
+        cause: error,
+        details: { url }
+      });
+    }
+    if (error instanceof SocketFiError) {
+      throw error;
+    }
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.NETWORK_ERROR,
+      message: "socketfi_request_failed",
+      cause: error,
+      details: { url }
+    });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// src/utils/normalize-url.ts
+function normalizeBaseUrl(url) {
+  return url.replace(/\/+$/, "");
+}
+function joinUrl(baseUrl, path) {
+  const cleanBase = normalizeBaseUrl(baseUrl);
+  const cleanPath = path.startsWith("/") ? path : `/${path}`;
+  return `${cleanBase}${cleanPath}`;
+}
+
+// src/config/defaults.ts
+var DEFAULT_SOCKETFI_API_URL = "https://api.socket.fi";
+var DEFAULT_SOCKETFI_ISSUER = "https://socket.fi";
+var DEFAULT_KEY_ENDPOINT = "/.well-known/socketfi-public-key";
+var DEFAULT_REQUEST_TIMEOUT_MS = 8e3;
+var DEFAULT_ALGORITHM = "RS256";
+var DEFAULT_KEY_CACHE_TTL_MS = 60 * 60 * 24 * 1e3;
+
+// src/keys/fetch-public-key.ts
+async function fetchSocketFiPublicKey(params) {
+  const url = joinUrl(
+    params.apiUrl,
+    params.keyEndpoint ?? DEFAULT_KEY_ENDPOINT
+  );
+  const data = await requestJson(url, {
+    timeoutMs: params.timeoutMs,
+    headers: {
+      "x-socketfi-client-secret": params.clientSecret
+    }
+  });
+  if (!data?.publicKey || typeof data.publicKey !== "string") {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.PUBLIC_KEY_MISSING,
+      message: "socketfi_public_key_missing",
+      statusCode: 502
+    });
+  }
+  if (data.alg !== "RS256") {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.PUBLIC_KEY_FETCH_FAILED,
+      message: "unsupported_socketfi_public_key_algorithm",
+      statusCode: 502,
+      details: { alg: data.alg }
+    });
+  }
+  return data;
+}
+
+// src/keys/public-key-cache.ts
+var PublicKeyCache = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  cached = null;
+  refreshPromise = null;
+  async get() {
+    if (this.cached && this.cached.expiresAt > Date.now()) {
+      return this.cached;
+    }
+    return this.refresh();
+  }
+  async refresh() {
+    if (!this.refreshPromise) {
+      this.refreshPromise = this.fetchAndImport().finally(() => {
+        this.refreshPromise = null;
+      });
+    }
+    return this.refreshPromise;
+  }
+  clear() {
+    this.cached = null;
+    this.refreshPromise = null;
+  }
+  async fetchAndImport() {
+    const response = await fetchSocketFiPublicKey({
+      apiUrl: this.config.apiUrl,
+      clientSecret: this.config.clientSecret,
+      timeoutMs: this.config.timeoutMs,
+      ...this.config.keyEndpoint ? { keyEndpoint: this.config.keyEndpoint } : {}
+    });
+    try {
+      const importedKey = await importSPKI(
+        response.publicKey,
+        DEFAULT_ALGORITHM
+      );
+      const now = Date.now();
+      this.cached = {
+        kid: response.kid,
+        alg: response.alg,
+        publicKeyPem: response.publicKey,
+        importedKey,
+        fetchedAt: now,
+        expiresAt: now + this.config.cacheTtlMs
+      };
+      return this.cached;
+    } catch (error) {
+      throw new SocketFiError({
+        code: SOCKETFI_ERROR_CODES.PUBLIC_KEY_IMPORT_FAILED,
+        message: "socketfi_public_key_import_failed",
+        statusCode: 502,
+        cause: error
+      });
+    }
+  }
+};
+
+// src/auth/verifyAuth.ts
+import {
+  decodeProtectedHeader,
+  errors,
+  jwtVerify
+} from "jose";
+async function verifyAuth(params) {
+  const token = params.token;
+  if (!token || typeof token !== "string") {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.AUTH_TOKEN_REQUIRED,
+      message: "auth_token_required",
+      statusCode: 401
+    });
+  }
+  if (params.options?.forceRefreshKey) {
+    await params.keyCache.refresh();
+  }
+  try {
+    const result = await verifyWithCache(params);
+    return {
+      ...result,
+      accessToken: token
+    };
+  } catch (error) {
+    if (!shouldRefreshKey(error)) {
+      throw normalizeVerifyError(error);
+    }
+    await params.keyCache.refresh();
+    try {
+      const result = await verifyWithCache(params);
+      return {
+        ...result,
+        accessToken: token
+      };
+    } catch (retryError) {
+      throw normalizeVerifyError(retryError, true);
+    }
+  }
+}
+async function verifyWithCache(params) {
+  const header = decodeProtectedHeader(params.token);
+  if (header.alg !== DEFAULT_ALGORITHM) {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_AUTH_TOKEN,
+      message: "unsupported_auth_token_algorithm",
+      statusCode: 401,
+      details: { alg: header.alg }
+    });
+  }
+  const cachedKey = await params.keyCache.get();
+  if (header.kid && cachedKey.kid && header.kid !== cachedKey.kid) {
+    await params.keyCache.refresh();
+  }
+  const key = (await params.keyCache.get()).importedKey;
+  const { payload } = await jwtVerify(params.token, key, {
+    issuer: params.issuer,
+    audience: params.clientId,
+    algorithms: [DEFAULT_ALGORITHM]
+  });
+  return normalizeAccessPayload(payload, params.clientId);
+}
+function normalizeAccessPayload(payload, clientId) {
+  const typed = payload;
+  if (typed.type !== "access") {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_TOKEN_TYPE,
+      message: "invalid_token_type",
+      statusCode: 401,
+      details: { type: typed.type }
+    });
+  }
+  if (typed.clientId !== clientId) {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_CLIENT_ID,
+      message: "invalid_client_id",
+      statusCode: 401,
+      details: { expected: clientId, received: typed.clientId }
+    });
+  }
+  if (!typed.sub || typeof typed.sub !== "string") {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_AUTH_TOKEN,
+      message: "invalid_subject",
+      statusCode: 401
+    });
+  }
+  if (!typed.origin || typeof typed.origin !== "string") {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_AUTH_TOKEN,
+      message: "invalid_origin",
+      statusCode: 401
+    });
+  }
+  return {
+    userId: typed.sub,
+    ...typeof typed.accountId === "string" ? { accountId: typed.accountId } : {},
+    ...typeof typed.username === "string" ? { username: typed.username } : {},
+    wallet: typed.wallet,
+    clientId: typed.clientId,
+    origin: typed.origin,
+    ...typeof typed.exp === "number" ? { expiresAt: new Date(typed.exp * 1e3) } : {},
+    raw: typed
+  };
+}
+function shouldRefreshKey(error) {
+  return error instanceof errors.JWSSignatureVerificationFailed || error instanceof errors.JWSInvalid || error?.code === "ERR_JWS_SIGNATURE_VERIFICATION_FAILED" || String(error?.message || "").includes(
+    "signature verification failed"
+  );
+}
+function normalizeVerifyError(error, afterRefresh = false) {
+  if (error instanceof SocketFiError) return error;
+  if (afterRefresh && (error instanceof errors.JWSSignatureVerificationFailed || error?.code === "ERR_JWS_SIGNATURE_VERIFICATION_FAILED")) {
+    return new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_AUTH_TOKEN,
+      message: "socketfi_token_signature_mismatch_after_key_refresh",
+      statusCode: 401
+    });
+  }
+  if (error instanceof errors.JWTExpired) {
+    return new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_AUTH_TOKEN,
+      message: "auth_token_expired",
+      statusCode: 401,
+      details: {
+        claim: "exp"
+      }
+    });
+  }
+  if (error instanceof errors.JWTClaimValidationFailed) {
+    return new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.INVALID_AUTH_TOKEN,
+      message: "invalid_auth_token_claim",
+      statusCode: 401,
+      details: {
+        claim: error.claim,
+        reason: error.reason
+      }
+    });
+  }
+  return new SocketFiError({
+    code: SOCKETFI_ERROR_CODES.INVALID_AUTH_TOKEN,
+    message: "invalid_auth_token",
+    statusCode: 401
+  });
+}
+
+// src/utils/assert.ts
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new SocketFiError({
+      code: SOCKETFI_ERROR_CODES.CONFIG_ERROR,
+      message: `${name}_required`,
+      statusCode: 400,
+      details: { field: name }
+    });
+  }
+}
+
+// src/socketfi.ts
+var SocketFi = class {
+  clientId;
+  secretKey;
+  keyCache;
+  constructor(config) {
+    assertNonEmptyString(config.clientId, "clientId");
+    assertNonEmptyString(config.secretKey, "secretKey");
+    this.clientId = config.clientId;
+    this.secretKey = config.secretKey;
+    this.keyCache = new PublicKeyCache({
+      apiUrl: DEFAULT_SOCKETFI_API_URL,
+      clientSecret: this.secretKey,
+      timeoutMs: DEFAULT_REQUEST_TIMEOUT_MS,
+      cacheTtlMs: DEFAULT_KEY_CACHE_TTL_MS
+    });
+  }
+  async verifyAuth(token) {
+    return verifyAuth({
+      token,
+      clientId: this.clientId,
+      issuer: DEFAULT_SOCKETFI_ISSUER,
+      keyCache: this.keyCache
+    });
+  }
+  clearKeyCache() {
+    this.keyCache.clear();
+  }
+};
+export {
+  SocketFi,
+  SocketFiError
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@socketfi/server",
+  "version": "1.0.0",
+  "description": "Server-side SDK for verifying SocketFi authentication tokens.",
+  "license": "Apache-2.0",
+  "author": "SocketFi",
+  "homepage": "https://socket.fi",
+  "keywords": [
+    "socketfi",
+    "authentication",
+    "auth",
+    "jwt",
+    "passkeys",
+    "webauthn",
+    "wallet",
+    "embedded-wallet",
+    "stellar",
+    "soroban"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "dependencies": {
+    "jose": "^6.2.3"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}