@kittl/sdk-backend

Backend helpers for Kittl apps.

Install

npm install @kittl/sdk-backend

Documentation

Guides and usage examples are in the Kittl SDK documentation.

Token verification

In your app frontend, get a short-lived Kittl user JWT with kittl.auth.getUserToken(). Verify that token on your app backend:

import { KittlSDK, TokenInvalidError } from '@kittl/sdk-backend';

// Initialize once (e.g. at module load time).
const kittlBackend = new KittlSDK({
  appId: process.env.KITTL_APP_ID!,
});

try {
  const payload = await kittlBackend.verifyUserToken(token);
  console.log(payload.sub);
} catch (error) {
  if (error instanceof TokenInvalidError) {
    // Return 401 Unauthorized.
  }

  throw error;
}

appId is used as the JWT audience, so tokens issued for a different app are rejected. The verified token's sub claim is a pseudonymous per-app user ID.

Persistent signing key cache

By default, signing keys are cached in memory per SDK instance for up to cacheMaxAgeMs (default: 1 hour) and up to cacheMaxEntries keys (default: 5). When process memory is not reused between requests, provide a persistent cache to reuse keys across restarts and cold starts — for example on edge, serverless, or other ephemeral backends.

import { KittlSDK, type SigningKeyCache } from '@kittl/sdk-backend';

const signingKeyCache: SigningKeyCache = {
  async get(key) {
    return await store.get(key);
  },
  async set(key, publicKeyPem, { ttlMs }) {
    await store.set(key, publicKeyPem, { ttlMs });
  },
};

// Initialize once (e.g. at module load time), not per request.
const kittlBackend = new KittlSDK({
  appId: process.env.KITTL_APP_ID!,
  signingKeyCache,
  onSigningKeyCacheError(error, context) {
    logger.warn({ error, ...context }, 'Kittl signing key cache error');
  },
});

Cache errors are reported through onSigningKeyCacheError and do not fail token verification; the SDK falls back to its in-memory signing key cache, then to Kittl's JWKS endpoint when needed.

The provided signingKeyCache is checked before the SDK's in-memory JWKS cache, so its get method is on the token verification path. Prefer low-latency storage and add local memoization in the adapter if remote I/O per verification would be too expensive for your runtime.