@iqauth/sdk 2.6.3 → 2.7.0

package/docs/guides/effective-permissions.md

@@ -0,0 +1,171 @@
+# Effective permissions: `useEffectivePermissions` + wildcard utilities
+
+Some IQAuth apps have hundreds of permission nodes. Stuffing the full set
+into the JWT `entitlements` claim is impractical — tokens grow past header
+limits and rotation gets expensive. The canonical pattern is:
+
+1. Keep the JWT small. Carry only the **roles** + a *coarse* subset of
+   `entitlements` for instant first-paint gating.
+2. Fetch the **full** effective permission set on demand from the issuer
+   and use it for fine-grained UI gating.
+3. Use the **same** wildcard semantics on the client and the server so the
+   two halves can never drift and produce the classic "user can see the
+   page but every API call 403s" foot-gun.
+
+The SDK ships:
+
+- `hasPermission(set, id)` and `expandPermissions(set)` — pure utilities
+  re-exported from `@iqauth/sdk`.
+- `useEffectivePermissions({ appKey })` — React hook in `@iqauth/sdk/react/permissions` (separate sub-entry so the main React entry never pulls in TanStack Query unless you actually use this hook). Re-exported from
+  `@iqauth/sdk/react`.
+
+## Wildcard semantics
+
+Permission ids are dot-separated keys: `metrics`, `metrics.read`,
+`billing.invoices.delete`. Two wildcard forms are supported:
+
+| Pattern         | Matches                                                       |
+| --------------- | ------------------------------------------------------------- |
+| `*`             | Every permission id (root wildcard).                          |
+| `<prefix>.*`    | `<prefix>` itself **and** every descendant.                   |
+
+Examples:
+
+- `metrics.*` matches `metrics`, `metrics.read`, `metrics.foo.bar`.
+- `metrics.*` does **not** match `metric`, `metricsX`, or
+  `billing.metrics`.
+- `*` matches everything, including any wildcard query.
+
+Wildcards in the middle of an id (e.g. `metrics.*.read`) are treated as
+literal strings and match nothing useful — keep wildcards at the leaf.
+
+`expandPermissions(set)` normalizes a set: dedupes, sorts, and strips
+entries already implied by a broader wildcard. It does **not** enumerate
+descendants of a wildcard (that set is open-ended).
+
+```ts
+import { expandPermissions, hasPermission } from "@iqauth/sdk";
+
+expandPermissions(["metrics.*", "metrics.read", "billing.read"]);
+// → ["billing.read", "metrics.*"]
+
+hasPermission(["metrics.*"], "metrics.foo.bar"); // true
+hasPermission(["metrics.read"], "metrics.write"); // false
+```
+
+## When to use the hook vs raw `entitlements`
+
+- **JWT `entitlements`** — instant, sync, available the moment the user is
+  authenticated. Good for top-level navigation gating where a small,
+  hand-picked subset is enough. **Hard size budget: keep `entitlements`
+  under ~50 entries to stay well under header limits across proxies.**
+- **`useEffectivePermissions()`** — async, network-backed, returns the
+  *complete* per-app set. Good for granular feature gating, action
+  buttons, admin-only fields. Cached for 5 minutes per
+  `(user, tenant, appKey)`.
+
+The hook automatically falls back to `claims.entitlements` while the
+fetch is in flight, so first paint is never blocked.
+
+## React usage
+
+The hook is backed by [TanStack Query](https://tanstack.com/query). The
+SDK declares `@tanstack/react-query` as an **optional** peer dependency
+— install it (`npm i @tanstack/react-query`) and mount a
+`QueryClientProvider` somewhere above `<IQAuthProvider/>`:
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { IQAuthProvider } from "@iqauth/sdk/react";
+
+const queryClient = new QueryClient();
+
+<QueryClientProvider client={queryClient}>
+  <IQAuthProvider publishableKey={…}>
+    <App />
+  </IQAuthProvider>
+</QueryClientProvider>
+```
+
+Then anywhere inside:
+
+```tsx
+import { SignedIn } from "@iqauth/sdk/react";
+import { useEffectivePermissions } from "@iqauth/sdk/react/permissions";
+
+function BillingPanel() {
+  const { permissions, hasPermission, isLoading, error, refetch } =
+    useEffectivePermissions({ appKey: "iqreuse" });
+
+  if (error) return <p>Couldn't load permissions: {error.message}</p>;
+
+  return (
+    <section aria-busy={isLoading}>
+      {hasPermission("billing.invoices.read") && <InvoiceList />}
+      {hasPermission("billing.invoices.write") && <NewInvoiceButton />}
+      {/* Wildcards work too — granted via `billing.*` or `*` */}
+      {hasPermission("billing.invoices.delete") && <DeleteInvoiceButton />}
+    </section>
+  );
+}
+```
+
+### What the hook returns
+
+```ts
+{
+  permissions: string[];                       // normalized set
+  hasPermission: (id: string) => boolean;      // wildcard-aware
+  isLoading: boolean;
+  error: { code: string; message: string } | null;
+  refetch: () => Promise<void>;                // bypass staleTime
+}
+```
+
+### Behaviour
+
+- **Caching.** Results are cached in-memory for 5 minutes per
+  `(issuer, tenantId, userId, appKey)`. Repeat mounts within the window
+  do not refetch. Override with `staleTime` (ms).
+- **Single-flight.** Concurrent renders/mounts share one in-flight
+  request — you will not see a thundering herd of `/permissions/effective`
+  calls when many components mount at once.
+- **No focus refetch.** The hook does **not** refetch on window focus.
+  Trigger `refetch()` after a mutation that changes permissions
+  (group assignment, role change, override write).
+- **Platform admin short-circuit.** If the JWT carries
+  `roles: ["platform_admin", …]` the hook returns `permissions: ["*"]`
+  and `hasPermission` always returns `true` without a network round trip.
+- **Entitlements fallback.** While the first fetch is in flight,
+  `permissions` is seeded from `claims.entitlements` so first paint isn't
+  blocked. The fetch result replaces this on success.
+
+### Endpoint shape
+
+The hook calls the existing issuer endpoint:
+
+```
+GET /api/v1/tenants/{tenantId}/users/{userId}/permissions/effective?appKey=<appKey>
+```
+
+It expects an `ApiResponse.success(...)` body whose `data` is an array of
+`{ scope: string; effect: "allow" | "deny"; … }` rows (the same shape
+returned by `permissionService.resolveEffectivePermissions`). Rows with
+`effect === "deny"` are stripped and the remaining `scope` strings are
+fed through `expandPermissions()`.
+
+No new server route is required.
+
+### Server-side parity
+
+Use the **same** utilities for server-side authorization checks so the
+two halves cannot drift:
+
+```ts
+import { hasPermission } from "@iqauth/sdk";
+
+// Inside an Express/Fastify/Hono route handler:
+if (!hasPermission(grantedPermissionSet, "billing.invoices.delete")) {
+  return res.status(403).json({ error: { code: "PERMISSION_DENIED" } });
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iqauth/sdk",
-  "version": "2.6.3",
+  "version": "2.7.0",
   "description": "TypeScript SDK for IQAuth — the canonical way for all IQ projects to integrate with IQAuthService",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -29,6 +29,11 @@
       "import": "./dist/react.mjs",
       "require": "./dist/react.js"
     },
+    "./react/permissions": {
+      "types": "./dist/react-permissions.d.ts",
+      "import": "./dist/react-permissions.mjs",
+      "require": "./dist/react-permissions.js"
+    },
     "./server": {
       "types": "./dist/server.d.ts",
       "import": "./dist/server.mjs",
@@ -96,7 +101,7 @@
     "docs"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/browser-session.ts src/browser.ts src/react.ts src/server.ts src/server/handlers.ts src/express.ts src/fastify.ts src/hono.ts src/next.ts src/mobile.ts src/service.ts src/ws.ts src/test.ts src/webhooks.ts src/locales.ts src/cli/index.ts --format cjs,esm --dts --clean --external react --external react-dom --external next/headers",
+    "build": "tsup src/index.ts src/browser-session.ts src/browser.ts src/react.ts src/react-permissions.ts src/server.ts src/server/handlers.ts src/express.ts src/fastify.ts src/hono.ts src/next.ts src/mobile.ts src/service.ts src/ws.ts src/test.ts src/webhooks.ts src/locales.ts src/cli/index.ts --format cjs,esm --dts --clean --external react --external react-dom --external next/headers --external @tanstack/react-query",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -108,7 +113,8 @@
   },
   "peerDependencies": {
     "react": ">=18",
-    "react-dom": ">=18"
+    "react-dom": ">=18",
+    "@tanstack/react-query": ">=4"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -116,9 +122,13 @@
     },
     "react-dom": {
       "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@tanstack/react-query": "^5.60.5",
     "@types/jsonwebtoken": "^9.0.7",
     "@types/node": "^20.0.0",
     "@types/react": "^18.0.0",

package/dist/chunk-UKZLOHZG.mjs

@@ -1,83 +0,0 @@
-// src/webhooks.ts
-import crypto from "crypto";
-var WebhookSignatureError = class extends Error {
-  constructor(code, message) {
-    super(message);
-    this.name = "WebhookSignatureError";
-    this.code = code;
-  }
-};
-function toBuffer(p) {
-  if (typeof p === "string") return Buffer.from(p, "utf8");
-  if (Buffer.isBuffer(p)) return p;
-  return Buffer.from(p);
-}
-function parseHeader(header) {
-  let t = NaN;
-  const v1 = [];
-  for (const part of header.split(",")) {
-    const [k, v] = part.split("=", 2);
-    if (!k || v === void 0) continue;
-    const key = k.trim();
-    const value = v.trim();
-    if (key === "t") t = Number(value);
-    else if (key === "v1") v1.push(value);
-  }
-  return { t, v1 };
-}
-function timingSafeEqualHex(a, b) {
-  if (a.length !== b.length) return false;
-  try {
-    return crypto.timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
-  } catch {
-    return false;
-  }
-}
-function verifyWebhookSignature(opts) {
-  const headerRaw = Array.isArray(opts.header) ? opts.header[0] : opts.header;
-  if (!headerRaw || typeof headerRaw !== "string") {
-    throw new WebhookSignatureError("MISSING_HEADER", "Missing X-IQAuth-Signature header");
-  }
-  if (!opts.secret) {
-    throw new WebhookSignatureError("MISSING_SECRET", "secret is required");
-  }
-  const { t, v1 } = parseHeader(headerRaw);
-  if (!Number.isFinite(t) || v1.length === 0) {
-    throw new WebhookSignatureError("MALFORMED_HEADER", `Could not parse signature header: ${headerRaw}`);
-  }
-  const tolerance = opts.toleranceSeconds ?? 300;
-  const now = opts.nowSeconds ?? Math.floor(Date.now() / 1e3);
-  if (Math.abs(now - t) > tolerance) {
-    throw new WebhookSignatureError(
-      "TIMESTAMP_OUT_OF_TOLERANCE",
-      `Signature timestamp ${t} is outside the ${tolerance}s tolerance window (now=${now})`
-    );
-  }
-  const body = toBuffer(opts.payload);
-  const expected = crypto.createHmac("sha256", opts.secret).update(`${t}.`).update(body).digest("hex");
-  const matched = v1.some((sig) => timingSafeEqualHex(sig, expected));
-  if (!matched) {
-    throw new WebhookSignatureError("SIGNATURE_MISMATCH", "Webhook signature does not match expected value");
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(body.toString("utf8"));
-  } catch {
-    throw new WebhookSignatureError("MALFORMED_BODY", "Webhook body is not valid JSON");
-  }
-  return parsed;
-}
-function isValidWebhookSignature(opts) {
-  try {
-    verifyWebhookSignature(opts);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export {
-  WebhookSignatureError,
-  verifyWebhookSignature,
-  isValidWebhookSignature
-};

package/dist/errors-CDdl24MP.d.mts

@@ -1,52 +0,0 @@
-/**
- * SOURCE REFS:
- * - Route file: src/lib/response.ts (error envelope: { success: false, error: { code, message } })
- * - All route files for error code extraction
- * - Verified claims: N/A (error module)
- * - Last verified: Phase 0 Research Summary
- */
-declare class IQAuthError extends Error {
-    code: string;
-    status?: number;
-    raw?: unknown;
-    constructor(code: string, message: string, status?: number, raw?: unknown);
-}
-declare const ErrorCodes: {
-    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
-    readonly INVALID_CREDENTIALS: "INVALID_CREDENTIALS";
-    readonly ACCOUNT_INACTIVE: "ACCOUNT_INACTIVE";
-    readonly ACCOUNT_LOCKED: "ACCOUNT_LOCKED";
-    readonly INSUFFICIENT_PERMISSIONS: "INSUFFICIENT_PERMISSIONS";
-    readonly TOKEN_INVALID: "TOKEN_INVALID";
-    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
-    readonly TOKEN_REVOKED: "TOKEN_REVOKED";
-    readonly USER_INACTIVE: "USER_INACTIVE";
-    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
-    readonly NOT_FOUND: "NOT_FOUND";
-    readonly SESSION_INVALID: "SESSION_INVALID";
-    readonly SESSION_EXPIRED: "SESSION_EXPIRED";
-    readonly REFRESH_TOKEN_REUSED: "REFRESH_TOKEN_REUSED";
-    readonly PASSWORD_EXPIRED: "PASSWORD_EXPIRED";
-    readonly PIN_EXPIRED: "PIN_EXPIRED";
-    readonly PASSWORD_POLICY_VIOLATION: "PASSWORD_POLICY_VIOLATION";
-    readonly MFA_INVALID_CODE: "MFA_INVALID_CODE";
-    readonly MFA_METHOD_UNAVAILABLE: "MFA_METHOD_UNAVAILABLE";
-    readonly MFA_RATE_LIMITED: "MFA_RATE_LIMITED";
-    readonly MFA_ENROLLMENT_REQUIRED: "MFA_ENROLLMENT_REQUIRED";
-    readonly API_KEY_REQUIRED: "API_KEY_REQUIRED";
-    readonly API_KEY_INVALID: "API_KEY_INVALID";
-    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
-    readonly ALREADY_EXISTS: "ALREADY_EXISTS";
-    readonly FORBIDDEN: "FORBIDDEN";
-    readonly OAUTH_NOT_CONFIGURED: "OAUTH_NOT_CONFIGURED";
-    readonly UPLOAD_ERROR: "UPLOAD_ERROR";
-    readonly EMAIL_SERVICE_UNAVAILABLE: "EMAIL_SERVICE_UNAVAILABLE";
-    readonly INVALID_CODE: "INVALID_CODE";
-    readonly CODE_ALREADY_USED: "CODE_ALREADY_USED";
-    readonly CODE_EXPIRED: "CODE_EXPIRED";
-    readonly CODE_IP_MISMATCH: "CODE_IP_MISMATCH";
-    readonly UNKNOWN_PAYLOAD: "UNKNOWN_PAYLOAD";
-};
-type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
-
-export { ErrorCodes as E, IQAuthError as I, type ErrorCode as a };

package/dist/errors-CDdl24MP.d.ts

@@ -1,52 +0,0 @@
-/**
- * SOURCE REFS:
- * - Route file: src/lib/response.ts (error envelope: { success: false, error: { code, message } })
- * - All route files for error code extraction
- * - Verified claims: N/A (error module)
- * - Last verified: Phase 0 Research Summary
- */
-declare class IQAuthError extends Error {
-    code: string;
-    status?: number;
-    raw?: unknown;
-    constructor(code: string, message: string, status?: number, raw?: unknown);
-}
-declare const ErrorCodes: {
-    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
-    readonly INVALID_CREDENTIALS: "INVALID_CREDENTIALS";
-    readonly ACCOUNT_INACTIVE: "ACCOUNT_INACTIVE";
-    readonly ACCOUNT_LOCKED: "ACCOUNT_LOCKED";
-    readonly INSUFFICIENT_PERMISSIONS: "INSUFFICIENT_PERMISSIONS";
-    readonly TOKEN_INVALID: "TOKEN_INVALID";
-    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
-    readonly TOKEN_REVOKED: "TOKEN_REVOKED";
-    readonly USER_INACTIVE: "USER_INACTIVE";
-    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
-    readonly NOT_FOUND: "NOT_FOUND";
-    readonly SESSION_INVALID: "SESSION_INVALID";
-    readonly SESSION_EXPIRED: "SESSION_EXPIRED";
-    readonly REFRESH_TOKEN_REUSED: "REFRESH_TOKEN_REUSED";
-    readonly PASSWORD_EXPIRED: "PASSWORD_EXPIRED";
-    readonly PIN_EXPIRED: "PIN_EXPIRED";
-    readonly PASSWORD_POLICY_VIOLATION: "PASSWORD_POLICY_VIOLATION";
-    readonly MFA_INVALID_CODE: "MFA_INVALID_CODE";
-    readonly MFA_METHOD_UNAVAILABLE: "MFA_METHOD_UNAVAILABLE";
-    readonly MFA_RATE_LIMITED: "MFA_RATE_LIMITED";
-    readonly MFA_ENROLLMENT_REQUIRED: "MFA_ENROLLMENT_REQUIRED";
-    readonly API_KEY_REQUIRED: "API_KEY_REQUIRED";
-    readonly API_KEY_INVALID: "API_KEY_INVALID";
-    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
-    readonly ALREADY_EXISTS: "ALREADY_EXISTS";
-    readonly FORBIDDEN: "FORBIDDEN";
-    readonly OAUTH_NOT_CONFIGURED: "OAUTH_NOT_CONFIGURED";
-    readonly UPLOAD_ERROR: "UPLOAD_ERROR";
-    readonly EMAIL_SERVICE_UNAVAILABLE: "EMAIL_SERVICE_UNAVAILABLE";
-    readonly INVALID_CODE: "INVALID_CODE";
-    readonly CODE_ALREADY_USED: "CODE_ALREADY_USED";
-    readonly CODE_EXPIRED: "CODE_EXPIRED";
-    readonly CODE_IP_MISMATCH: "CODE_IP_MISMATCH";
-    readonly UNKNOWN_PAYLOAD: "UNKNOWN_PAYLOAD";
-};
-type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
-
-export { ErrorCodes as E, IQAuthError as I, type ErrorCode as a };