@iqauth/sdk 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DispositionIQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# @iqauth/sdk
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/license-proprietary-lightgrey.svg)]()
+[![Module Format](https://img.shields.io/badge/format-CJS%20%2B%20ESM-blue.svg)]()
+[![Docs](https://img.shields.io/badge/docs-environment--specific-blue.svg)](./docs/)
+
+Type-safe TypeScript SDK for IQAuthService.
+
+## Five-line integration
+
+**React (client):**
+```tsx
+import { IQAuthProvider, SignedIn, SignedOut, RedirectToSignIn } from "@iqauth/sdk/react";
+
+<IQAuthProvider publishableKey={import.meta.env.VITE_IQAUTH_PUBLISHABLE_KEY}>
+  <SignedIn><App /></SignedIn>
+  <SignedOut><RedirectToSignIn /></SignedOut>
+</IQAuthProvider>
+```
+
+**Express / Fastify / Hono / Next.js (server):**
+```js
+import express from "express";
+import { iqAuth } from "@iqauth/sdk/express"; // or /fastify, /hono, /next
+
+const app = express();
+app.use(express.json());
+const auth = iqAuth({ publishableKey: process.env.IQAUTH_PUBLISHABLE_KEY, secretKey: process.env.IQAUTH_SECRET_KEY });
+auth.attachHelpers(app);  // mounts /api/iqauth/{callback,refresh,signout} (httpOnly cookies)
+app.use(auth);            // verifies Bearer or iqauth_at cookie; populates req.auth
+```
+
+The middleware is **cookie-aware** (Bearer header OR `iqauth_at` cookie) and the issuer is **auto-discovered from your publishable key** — no extra config.
+
+Working examples live in `examples/{react-vite,express,fastify,hono,next}/`.
+
+## CLI
+
+```sh
+npx iqauth init      # bootstrap a new app + write IQAUTH_* keys to .env
+npx iqauth doctor    # check .env, issuer reachability, JWKS, redirect URI
+npx iqauth keys list --app <id>
+npx iqauth keys rotate --app <id> --key-id <id> --yes
+npx iqauth dev       # run the bundled React example with your key
+```
+
+---
+
+## Environment Matrix
+
+This package is not one auth model for every environment. The safe integration pattern depends on where credentials live.
+
+| Environment | Recommended pattern | Refresh token owner | Primary SDK fit |
+|--------|--------|--------|--------|
+| First-party browser app | Backend proxy + `httpOnly` cookies | Backend only | Resource calls, server verification, shared API modules |
+| Native mobile app | Authorization code + PKCE + secure OS storage | Mobile app secure storage | Token-owning client patterns |
+| Server-side app | Direct token handling or request-scoped bearer verification | Server | Strong fit |
+| Service / automation | API key or dedicated service credentials | Service | Strong fit |
+
+## Start Here
+
+### First-party browser apps
+
+Do not treat this SDK's token-owning client as the default browser integration path.
+
+For first-party web applications:
+
+- proxy login, MFA, tenant selection, refresh, and logout through your backend
+- store access and refresh tokens in `httpOnly` cookies
+- restore session with a backend endpoint such as `/auth/me`
+- do not store refresh tokens in `localStorage`, `sessionStorage`, or browser-readable memory as your durable session model
+
+The browser should call your backend. Your backend should call IQAuth.
+
+### Native mobile apps
+
+Use authorization code flow with PKCE:
+
+- generate `state`, `nonce`, and PKCE verifier/challenge on device
+- complete auth in the system browser
+- exchange the authorization code
+- store tokens only in Keychain / Keystore / secure OS-backed storage
+
+### Server-side apps
+
+This SDK is a good fit for:
+
+- trusted backend services
+- Express resource servers
+- admin tooling
+- request-scoped token handling
+- bearer-token verification through JWKS
+
+### Service clients
+
+Prefer API keys or dedicated service credentials over interactive user session flows.
+
+## Current SDK Shape
+
+The current package surface is still token-oriented. That is acceptable for server, mobile, and service contexts, but it should not be read as a recommendation to store refresh tokens directly in first-party browser JavaScript.
+
+Use the package today with that distinction in mind:
+
+- server: recommended
+- mobile: acceptable with PKCE + secure storage discipline
+- browser first-party: use only behind a backend session boundary
+- service: recommended with API keys
+
+## Install
+
+```bash
+npm install @iqauth/sdk
+```
+
+Supports both CommonJS and ES Modules. Ships with TypeScript declarations.
+
+## Entry Points
+
+Use the entry point that matches your environment:
+
+```typescript
+import { createBrowserSessionClient } from "@iqauth/sdk/browser-session";
+import { createServerClient, ServerIQAuthClient } from "@iqauth/sdk/server";
+import { createMobileClient } from "@iqauth/sdk/mobile";
+import { createServiceClient } from "@iqauth/sdk/service";
+```
+
+## Server Quick Start
+
+Use the provided middleware by default for Express resource servers.
+
+```typescript
+import express from "express";
+import { createServerClient } from "@iqauth/sdk/server";
+
+const client = createServerClient({
+  baseUrl: "https://auth.dispositioniq.com",
+});
+
+const app = express();
+
+app.use("/api", client.middleware());
+
+app.get("/api/me", (req, res) => {
+  res.json({
+    sub: req.auth!.sub,
+    email: req.auth!.email,
+    tenantId: req.auth!.tenantId,
+    roles: req.auth!.roles,
+  });
+});
+```
+
+If you are building an Express API that accepts bearer tokens, the platform should use the SDK middleware rather than re-implementing token verification manually unless there is a concrete framework constraint.
+
+## Browser Quick Start
+
+Use a backend proxy. Example shape:
+
+```typescript
+// frontend
+await fetch("/auth/login", {
+  method: "POST",
+  credentials: "include",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ email, password }),
+});
+
+const me = await fetch("/auth/me", {
+  credentials: "include",
+}).then((res) => res.json());
+```
+
+```typescript
+// backend
+app.post("/auth/login", async (req, res) => {
+  const result = await iqauth.auth.login(req.body.email, req.body.password);
+  // set httpOnly cookies here, not localStorage in the browser
+});
+```
+
+For the full backend-proxy pattern, see the Fresh Implementation Guide.
+
+## Mobile Quick Start
+
+```typescript
+import { IQAuthClient } from "@iqauth/sdk";
+
+const client = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  accessToken: await secureStore.get("accessToken"),
+  refreshToken: await secureStore.get("refreshToken"),
+  onTokenRefresh: async (tokens) => {
+    await secureStore.set("accessToken", tokens.accessToken);
+    await secureStore.set("refreshToken", tokens.refreshToken);
+  },
+});
+```
+
+This is only appropriate when the tokens are stored in secure OS-backed storage and the login flow uses PKCE.
+
+## API Key Quick Start
+
+```typescript
+import { IQAuthClient } from "@iqauth/sdk";
+
+const client = new IQAuthClient({
+  baseUrl: "https://auth.dispositioniq.com",
+  apiKey: process.env.IQAUTH_API_KEY,
+});
+
+const keys = await client.apiKeys.list();
+```
+
+## Main Modules
+
+| Module | Access | Purpose |
+|--------|--------|---------|
+| `auth` | `client.auth` | Login, MFA, tenant selection, logout, password reset, OAuth |
+| `tokens` | `client.tokens` | JWT verification (RS256/JWKS), decode, expiry checks |
+| `sessions` | `client.sessions` | List and revoke sessions |
+| `users` | `client.users` | Profile and user management |
+| `permissions` | `client.permissions` | Role and entitlement helpers |
+| `oidc` | `client.oidc` | Discovery, JWKS, authorization helpers, code exchange |
+| `apiKeys` | `client.apiKeys` | API key create/list/revoke/introspect |
+| `webhooks` | `client.webhooks` | Endpoint CRUD, deliveries, test, secret rotation |
+| `mfa` | `client.mfa` | MFA enrollment, backup codes |
+| `branding` | `client.branding` | Branding config CRUD |
+
+## Express Middleware
+
+```typescript
+import { createServerClient } from "@iqauth/sdk/server";
+
+const client = createServerClient({
+  baseUrl: "https://auth.dispositioniq.com",
+});
+
+app.use(
+  "/admin",
+  client.middleware({
+    requiredRoles: ["tenant_admin", "platform_admin"],
+    requiredEntitlements: ["iqcapture"],
+  }),
+);
+```
+
+The middleware attaches verified claims to `req.auth` and is the recommended integration path for platforms consuming bearer tokens.
+
+## Error Handling
+
+All API errors throw `IQAuthError`.
+
+```typescript
+import { IQAuthError, ErrorCodes } from "@iqauth/sdk";
+
+try {
+  await client.auth.login(email, password);
+} catch (err) {
+  if (err instanceof IQAuthError && err.code === ErrorCodes.ACCOUNT_LOCKED) {
+    // handle lockout
+  }
+}
+```
+
+## Documentation
+
+- [App Integration Matrix](./docs/APP_INTEGRATION_MATRIX.md)
+- [Fresh Implementation Guide](./docs/FRESH_IMPLEMENTATION_GUIDE.md)
+- [Browser Session Migration Guide](./docs/BROWSER_SESSION_MIGRATION.md)
+- [Tarball Release Workflow](./docs/TARBALL_RELEASE_WORKFLOW.md)
+- [Auth Flows](./docs/guides/auth-flows.md)
+- [Session Management](./docs/guides/session-management.md)
+- [Mobile / Native Guide](./docs/guides/mobile-native.md)
+- [Server Platform Integration](./docs/guides/server-platform-integration.md)
+- [Service Automation Integration](./docs/guides/service-automation-integration.md)
+- [Token Verification](./docs/guides/token-verification.md)
+- [API Keys](./docs/guides/api-keys.md)
+- [Middleware Reference](./docs/guides/middleware-reference.md)
+- [Error Handling](./docs/guides/error-handling.md)
+- [V1 to V2 Upgrade Guide](./docs/V1_TO_V2_UPGRADE_GUIDE.md)
+- [Integration Prompts](./docs/integration-prompts/)
+
+## License
+
+Private — DispositionIQ internal use.

package/dist/browser-session.d.mts

@@ -0,0 +1,12 @@
+import { c as IQAuthBrowserSessionClientConfig, d as SessionUser } from './types-Cxl3bQHt.mjs';
+import { I as IQAuthClient } from './client-C1DXfB8Z.mjs';
+export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.mjs';
+import 'jsonwebtoken';
+
+declare class BrowserSessionIQAuthClient extends IQAuthClient {
+    constructor(config: Omit<IQAuthBrowserSessionClientConfig, "environment">);
+    getSessionUser(): Promise<SessionUser>;
+}
+declare function createBrowserSessionClient(config: Omit<IQAuthBrowserSessionClientConfig, "environment">): BrowserSessionIQAuthClient;
+
+export { BrowserSessionIQAuthClient, IQAuthBrowserSessionClientConfig, IQAuthClient, createBrowserSessionClient };

package/dist/browser-session.d.ts

@@ -0,0 +1,12 @@
+import { c as IQAuthBrowserSessionClientConfig, d as SessionUser } from './types-Cxl3bQHt.js';
+import { I as IQAuthClient } from './client-CggvJmmm.js';
+export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.js';
+import 'jsonwebtoken';
+
+declare class BrowserSessionIQAuthClient extends IQAuthClient {
+    constructor(config: Omit<IQAuthBrowserSessionClientConfig, "environment">);
+    getSessionUser(): Promise<SessionUser>;
+}
+declare function createBrowserSessionClient(config: Omit<IQAuthBrowserSessionClientConfig, "environment">): BrowserSessionIQAuthClient;
+
+export { BrowserSessionIQAuthClient, IQAuthBrowserSessionClientConfig, IQAuthClient, createBrowserSessionClient };