@hanzo/iam 0.1.0

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@hanzo/iam",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Hanzo IAM — OIDC auth, JWT validation, OAuth2 PKCE, user/org/billing APIs",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth.d.ts",
+      "import": "./dist/auth.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    },
+    "./billing": {
+      "types": "./dist/billing.d.ts",
+      "import": "./dist/billing.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepare": "npm run clean && npm run build",
+    "prepublishOnly": "npm run clean && npm run build",
+    "test": "node --test --import tsx src/**/*.test.ts"
+  },
+  "dependencies": {
+    "jose": "^6.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "@types/react": "^19.0.0",
+    "typescript": "^5.5.0"
+  },
+  "keywords": [
+    "hanzo",
+    "iam",
+    "casdoor",
+    "oidc",
+    "oauth2",
+    "pkce",
+    "auth",
+    "jwt",
+    "identity",
+    "access-management",
+    "sso"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hanzo-js/iam"
+  },
+  "homepage": "https://docs.hanzo.ai/services/iam/sdk",
+  "bugs": {
+    "url": "https://github.com/hanzo-js/iam/issues"
+  },
+  "author": "Hanzo AI <engineering@hanzo.ai>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,151 @@
+/**
+ * JWT validation using jose library + OIDC JWKS discovery.
+ *
+ * Validates access/ID tokens issued by Hanzo IAM (Casdoor).
+ */
+
+import { createRemoteJWKSet, jwtVerify, type JWTPayload } from "jose";
+import type { IamConfig, IamAuthResult, IamJwtClaims } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// JWKS key set cache (per issuer)
+// ---------------------------------------------------------------------------
+
+const jwksSets = new Map<string, ReturnType<typeof createRemoteJWKSet>>();
+
+function getJwksKeySet(jwksUri: string): ReturnType<typeof createRemoteJWKSet> {
+  let keySet = jwksSets.get(jwksUri);
+  if (!keySet) {
+    keySet = createRemoteJWKSet(new URL(jwksUri));
+    jwksSets.set(jwksUri, keySet);
+  }
+  return keySet;
+}
+
+/** Clear cached JWKS key sets (useful for testing or key rotation). */
+export function clearJwksCache(): void {
+  jwksSets.clear();
+}
+
+// ---------------------------------------------------------------------------
+// OIDC discovery cache (lightweight, no full client needed)
+// ---------------------------------------------------------------------------
+
+type CachedDiscovery = { jwksUri: string; issuer: string; fetchedAt: number };
+const discoveryCache = new Map<string, CachedDiscovery>();
+const DISCOVERY_TTL_MS = 5 * 60 * 1000;
+
+async function resolveJwksUri(serverUrl: string): Promise<{ jwksUri: string; issuer: string }> {
+  const baseUrl = serverUrl.replace(/\/+$/, "");
+  const cached = discoveryCache.get(baseUrl);
+  if (cached && Date.now() - cached.fetchedAt < DISCOVERY_TTL_MS) {
+    return { jwksUri: cached.jwksUri, issuer: cached.issuer };
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 8_000);
+  try {
+    const res = await fetch(`${baseUrl}/.well-known/openid-configuration`, {
+      signal: controller.signal,
+      headers: { Accept: "application/json" },
+    });
+    if (!res.ok) {
+      throw new Error(`OIDC discovery failed: ${res.status}`);
+    }
+    const body = (await res.json()) as { jwks_uri?: string; issuer?: string };
+    const jwksUri = body.jwks_uri;
+    const issuer = body.issuer ?? baseUrl;
+    if (!jwksUri) {
+      throw new Error("OIDC discovery response missing jwks_uri");
+    }
+    discoveryCache.set(baseUrl, { jwksUri, issuer, fetchedAt: Date.now() });
+    return { jwksUri, issuer };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Token validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a JWT access token against IAM's JWKS.
+ *
+ * Uses OIDC discovery to find the JWKS URI, then verifies the token
+ * signature, issuer, audience, and expiry using the `jose` library.
+ */
+export async function validateToken(
+  token: string,
+  config: IamConfig,
+): Promise<IamAuthResult> {
+  if (!token || typeof token !== "string") {
+    return { ok: false, reason: "iam_token_missing" };
+  }
+
+  let jwksUri: string;
+  let issuer: string;
+  try {
+    const discovery = await resolveJwksUri(config.serverUrl);
+    jwksUri = discovery.jwksUri;
+    issuer = discovery.issuer;
+  } catch {
+    return { ok: false, reason: "iam_discovery_failed" };
+  }
+
+  const keySet = getJwksKeySet(jwksUri);
+
+  let payload: JWTPayload;
+  try {
+    const result = await jwtVerify(token, keySet, {
+      issuer,
+      audience: config.clientId,
+      clockTolerance: 30, // 30s clock skew
+    });
+    payload = result.payload;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("expired")) {
+      return { ok: false, reason: "iam_token_expired" };
+    }
+    if (message.includes("audience")) {
+      // Retry without audience check - some Casdoor configs don't set aud
+      try {
+        const result = await jwtVerify(token, keySet, {
+          issuer,
+          clockTolerance: 30,
+        });
+        payload = result.payload;
+      } catch {
+        return { ok: false, reason: "iam_signature_invalid" };
+      }
+    } else {
+      return { ok: false, reason: "iam_signature_invalid" };
+    }
+  }
+
+  const claims = payload as unknown as IamJwtClaims;
+
+  if (!claims.sub) {
+    return { ok: false, reason: "iam_subject_missing" };
+  }
+
+  // Casdoor sub format is "org/username" - extract owner
+  const parts = claims.sub.split("/");
+  const owner = parts.length > 1 ? parts[0] : config.orgName ?? "unknown";
+
+  return {
+    ok: true,
+    userId: claims.sub,
+    email: typeof claims.email === "string" ? claims.email : undefined,
+    name:
+      typeof claims.name === "string"
+        ? claims.name
+        : typeof claims.preferred_username === "string"
+          ? claims.preferred_username
+          : undefined,
+    avatar: typeof claims.picture === "string" ? claims.picture : undefined,
+    owner,
+    claims,
+  };
+}

package/src/billing.ts

@@ -0,0 +1,238 @@
+/**
+ * Billing client for Hanzo IAM (Casdoor) — subscriptions, plans, pricing, usage.
+ */
+
+import type {
+  IamConfig,
+  IamSubscription,
+  IamPlan,
+  IamPricing,
+  IamPayment,
+  IamOrder,
+  IamApiResponse,
+} from "./types.js";
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+export class IamBillingClient {
+  private readonly baseUrl: string;
+  private readonly clientId: string;
+  private readonly clientSecret: string | undefined;
+  private readonly orgName: string | undefined;
+
+  constructor(config: IamConfig) {
+    this.baseUrl = config.serverUrl.replace(/\/+$/, "");
+    this.clientId = config.clientId;
+    this.clientSecret = config.clientSecret;
+    this.orgName = config.orgName;
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal HTTP helper
+  // -----------------------------------------------------------------------
+
+  private async request<T>(
+    path: string,
+    opts?: {
+      method?: string;
+      body?: unknown;
+      token?: string;
+      params?: Record<string, string>;
+    },
+  ): Promise<T> {
+    const url = new URL(path, this.baseUrl);
+    if (opts?.params) {
+      for (const [k, v] of Object.entries(opts.params)) {
+        url.searchParams.set(k, v);
+      }
+    }
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+    };
+    if (opts?.token) {
+      headers.Authorization = `Bearer ${opts.token}`;
+    }
+    if (opts?.body) {
+      headers["Content-Type"] = "application/json";
+    }
+    if (this.clientSecret && !opts?.token) {
+      const credentials = `${this.clientId}:${this.clientSecret}`;
+      const basic =
+        typeof Buffer !== "undefined"
+          ? Buffer.from(credentials).toString("base64")
+          : btoa(credentials);
+      headers.Authorization = `Basic ${basic}`;
+    }
+
+    try {
+      const res = await fetch(url.toString(), {
+        method: opts?.method ?? "GET",
+        headers,
+        body: opts?.body ? JSON.stringify(opts.body) : undefined,
+        signal: controller.signal,
+      });
+
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`IAM billing request failed (${res.status}): ${text}`.trim());
+      }
+
+      return (await res.json()) as T;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Subscriptions
+  // -----------------------------------------------------------------------
+
+  /** Get all subscriptions for an owner. */
+  async getSubscriptions(token?: string): Promise<IamSubscription[]> {
+    const owner = this.orgName ?? "admin";
+    const resp = await this.request<IamApiResponse<IamSubscription[]>>(
+      "/api/get-subscriptions",
+      { params: { owner }, token },
+    );
+    return resp.data ?? [];
+  }
+
+  /** Get a specific subscription by ID ("owner/name" format). */
+  async getSubscription(id: string, token?: string): Promise<IamSubscription | null> {
+    const resp = await this.request<IamApiResponse<IamSubscription>>(
+      "/api/get-subscription",
+      { params: { id }, token },
+    );
+    return resp.data ?? null;
+  }
+
+  /** Get the subscription for a specific user. */
+  async getUserSubscription(userId: string, token?: string): Promise<IamSubscription | null> {
+    const subs = await this.getSubscriptions(token);
+    return subs.find((s) => s.user === userId) ?? null;
+  }
+
+  // -----------------------------------------------------------------------
+  // Plans
+  // -----------------------------------------------------------------------
+
+  /** Get all plans for an owner. */
+  async getPlans(token?: string): Promise<IamPlan[]> {
+    const owner = this.orgName ?? "admin";
+    const resp = await this.request<IamApiResponse<IamPlan[]>>(
+      "/api/get-plans",
+      { params: { owner }, token },
+    );
+    return resp.data ?? [];
+  }
+
+  /** Get a specific plan by ID. */
+  async getPlan(id: string, token?: string): Promise<IamPlan | null> {
+    const resp = await this.request<IamApiResponse<IamPlan>>(
+      "/api/get-plan",
+      { params: { id }, token },
+    );
+    return resp.data ?? null;
+  }
+
+  // -----------------------------------------------------------------------
+  // Pricing
+  // -----------------------------------------------------------------------
+
+  /** Get all pricing configurations for an owner. */
+  async getPricings(token?: string): Promise<IamPricing[]> {
+    const owner = this.orgName ?? "admin";
+    const resp = await this.request<IamApiResponse<IamPricing[]>>(
+      "/api/get-pricings",
+      { params: { owner }, token },
+    );
+    return resp.data ?? [];
+  }
+
+  /** Get a specific pricing by ID. */
+  async getPricing(id: string, token?: string): Promise<IamPricing | null> {
+    const resp = await this.request<IamApiResponse<IamPricing>>(
+      "/api/get-pricing",
+      { params: { id }, token },
+    );
+    return resp.data ?? null;
+  }
+
+  // -----------------------------------------------------------------------
+  // Payments
+  // -----------------------------------------------------------------------
+
+  /** Get all payments for an owner. */
+  async getPayments(token?: string): Promise<IamPayment[]> {
+    const owner = this.orgName ?? "admin";
+    const resp = await this.request<IamApiResponse<IamPayment[]>>(
+      "/api/get-payments",
+      { params: { owner }, token },
+    );
+    return resp.data ?? [];
+  }
+
+  /** Get a specific payment by ID. */
+  async getPayment(id: string, token?: string): Promise<IamPayment | null> {
+    const resp = await this.request<IamApiResponse<IamPayment>>(
+      "/api/get-payment",
+      { params: { id }, token },
+    );
+    return resp.data ?? null;
+  }
+
+  // -----------------------------------------------------------------------
+  // Orders (if supported by IAM)
+  // -----------------------------------------------------------------------
+
+  /** Get all orders for an owner. */
+  async getOrders(token?: string): Promise<IamOrder[]> {
+    const owner = this.orgName ?? "admin";
+    const resp = await this.request<IamApiResponse<IamOrder[]>>(
+      "/api/get-orders",
+      { params: { owner }, token },
+    );
+    return resp.data ?? [];
+  }
+
+  /** Get a specific order by ID. */
+  async getOrder(id: string, token?: string): Promise<IamOrder | null> {
+    const resp = await this.request<IamApiResponse<IamOrder>>(
+      "/api/get-order",
+      { params: { id }, token },
+    );
+    return resp.data ?? null;
+  }
+
+  // -----------------------------------------------------------------------
+  // Convenience: check subscription status for an org
+  // -----------------------------------------------------------------------
+
+  /** Check if an org has an active subscription. */
+  async isSubscriptionActive(orgName: string, token?: string): Promise<{
+    active: boolean;
+    subscription: IamSubscription | null;
+    plan: IamPlan | null;
+  }> {
+    const subs = await this.getSubscriptions(token);
+    // Find subscription matching the org
+    const sub = subs.find(
+      (s) => s.owner === orgName && (s.state === "Active" || s.state === "active"),
+    ) ?? null;
+
+    if (!sub) {
+      return { active: false, subscription: null, plan: null };
+    }
+
+    let plan: IamPlan | null = null;
+    if (sub.plan) {
+      plan = await this.getPlan(sub.plan, token);
+    }
+
+    return { active: true, subscription: sub, plan };
+  }
+}