@cleverclouds/auth-client 1.0.0 → 1.0.2

package/AGENTS.md

@@ -1,379 +1,379 @@
-# @cleverclouds/auth-client — AI Agent & LLM Implementation Guide
-
-> **Note for AI Coding Assistants (Claude, Cursor, Copilot, Antigravity, Devin, Codex):**  
-> Use this document as the authoritative specification when implementing or refactoring authentication and authorization in downstream applications using `@cleverclouds/auth-client`.
-
----
-
-## 1. Core Mental Model & Architectural Invariants
-
-CleverClouds Identity is a centralized SSO and Identity Management service. Downstream applications (e.g. `projects`, `hr`, `finance`, `ops`) delegate authentication and role/permission assignment to Identity.
-
-### Identity Boundary Rules
-1. **Zero Direct DB Access**: Downstream applications must **never** connect directly to the Identity MongoDB cluster. All communication flows over HTTPS backchannel calls or cryptographic cookies.
-2. **Identity vs. Domain Authorization**:
-   - Identity tells downstream apps: *Who is the user?* (`userId`, `email`, `name`, `status`), *What roles do they hold in THIS app?* (`roles: ["PROJECT_MANAGER"]`), and *What permissions do they have?* (`permissions: ["projects.*"]`).
-   - The downstream application remains **100% responsible** for resource-level authorization (e.g., whether user A owns project #42).
-3. **Mandatory HMAC Cookie Signing**: Downstream session cookies MUST be cryptographically signed using HMAC-SHA256 via a configured `sessionSecret`. The client strictly prohibits unsigned or unverified cookie consumption.
-4. **Single-Use Tickets**: SSO tickets (`cc_ticket_...`) are valid for **60 seconds** and are burned upon first exchange. Never reuse or cache tickets.
-5. **Open Redirect Defense**: When redirecting users post-callback, downstream handlers MUST validate `returnTo` URLs to ensure they are relative paths (starting with `/`, not `//` or `/\`) or match a strict whitelist.
-
----
-
-## 2. Package Entrypoints & Subpath Imports
-
-```typescript
-// 1. Core client, types, error classes, and standalone RBAC evaluators
-import {
-  CleverCloudsAuthClient,
-  hasPermission,
-  hasAnyPermission,
-  hasAllPermissions,
-  hasRole,
-  hasAnyRole,
-  CleverCloudsAuthError,
-  AppAccessDeniedError,
-  InvalidTicketError,
-  InvalidCredentialsError,
-} from '@cleverclouds/auth-client';
-
-// 2. Express.js middleware and route helpers
-import { createAuthMiddleware } from '@cleverclouds/auth-client/express';
-
-// 3. Next.js App Router helpers (Server Components, Route Handlers, Server Actions)
-import { getServerSession, protectRoute } from '@cleverclouds/auth-client/nextjs';
-
-// 4. Low-level HMAC-SHA256 cookie signer & verifier
-import { signCookie, verifyCookie } from '@cleverclouds/auth-client/cookies';
-```
-
----
-
-## 3. Required Environment Variables
-
-Downstream applications must define these environment variables:
-
-```env
-# URL where CleverClouds Identity is hosted
-CC_IDENTITY_URL=https://auth.cleverclouds.in
-
-# Application identifier registered in CleverClouds Identity
-CC_APP_SLUG=projects
-
-# Application API key generated in CleverClouds Identity Admin Console
-CC_APP_KEY=cc_app_projects_xxxxxxxxxxxxxxxx
-
-# Callback URL registered in application's redirectUrls
-CC_REDIRECT_URI=https://projects.cleverclouds.in/api/auth/callback
-
-# Strong secret for signing downstream session cookies (min 32 characters)
-SESSION_SECRET=super_strong_random_secret_at_least_32_chars_long
-```
-
----
-
-## 4. Initializing the Client Singleton
-
-Create a shared singleton instance (e.g. `src/lib/auth.ts` or `src/auth.ts`):
-
-```typescript
-import { CleverCloudsAuthClient } from '@cleverclouds/auth-client';
-
-export const auth = new CleverCloudsAuthClient({
-  identityBaseUrl: process.env.CC_IDENTITY_URL || 'http://localhost:3000',
-  applicationSlug: process.env.CC_APP_SLUG || 'projects',
-  applicationApiKey: process.env.CC_APP_KEY!,
-  redirectUri: process.env.CC_REDIRECT_URI || 'http://localhost:3001/api/auth/callback',
-  sessionSecret: process.env.SESSION_SECRET!, // Mandatory for session cookie signing
-});
-```
-
----
-
-## 5. Implementation Recipes
-
-### Pattern A: Express.js (API & SSR)
-
-```typescript
-import express from 'express';
-import cookieParser from 'cookie-parser';
-import { createAuthMiddleware } from '@cleverclouds/auth-client/express';
-import { auth } from './lib/auth.js';
-
-const app = express();
-app.use(express.json());
-app.use(cookieParser()); // REQUIRED: cookie-parser middleware must precede auth middleware
-
-// Initialize middleware adapter
-const {
-  requireAuth,
-  requirePermission,
-  requireRole,
-  handleCallback,
-  handleLogout,
-} = createAuthMiddleware(auth, {
-  cookieName: 'projects_session',
-  cookieOptions: {
-    httpOnly: true,
-    secure: process.env.NODE_ENV === 'production',
-    sameSite: 'lax',
-    path: '/',
-    maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
-  },
-});
-
-// 1. SSO Callback Route — Exchanges ticket and sets signed session cookie
-app.get('/api/auth/callback', handleCallback({
-  defaultReturnTo: '/dashboard',
-  allowedRedirectHosts: ['projects.cleverclouds.in', 'localhost:3001'],
-}));
-
-// 2. Logout Route — Clears session cookie and redirects
-app.get('/logout', handleLogout({
-  redirectTo: '/login',
-}));
-
-// 3. Authenticated Route — Attaches req.auth: VerificationResult
-app.get('/api/me', requireAuth(), (req, res) => {
-  res.json({
-    user: req.auth.user,
-    roles: req.auth.roles,
-    permissions: req.auth.permissions,
-  });
-});
-
-// 4. Permission-Gated Route (supports wildcards e.g. 'projects.*')
-app.post('/api/projects', requirePermission('projects.create'), async (req, res) => {
-  // Safe: user is guaranteed to have 'projects.create' or 'projects.*' or '*.*'
-  res.json({ message: 'Project created' });
-});
-
-// 5. Role-Gated Route (case-insensitive role check)
-app.delete('/api/projects/:id', requireRole('project_admin'), async (req, res) => {
-  res.json({ message: 'Project deleted' });
-});
-
-// Optional: Custom Login Trigger (redirects browser to Identity)
-app.get('/login', (req, res) => {
-  const returnTo = typeof req.query.returnTo === 'string' ? req.query.returnTo : '/dashboard';
-  const loginUrl = auth.getAuthorizationUrl({ returnTo });
-  res.redirect(loginUrl);
-});
-```
-
----
-
-### Pattern B: Next.js App Router (14/15)
-
-#### 1. Server Components & Route Handlers (`getServerSession`)
-
-```typescript
-// app/dashboard/page.tsx (Server Component)
-import { redirect } from 'next/navigation';
-import { getServerSession } from '@cleverclouds/auth-client/nextjs';
-import { auth } from '@/lib/auth';
-
-export default async function DashboardPage() {
-  const session = await getServerSession(auth, { cookieName: 'projects_session' });
-
-  if (!session) {
-    redirect(auth.getAuthorizationUrl({ returnTo: '/dashboard' }));
-  }
-
-  return (
-    <main>
-      <h1>Welcome, {session.user.name}</h1>
-      <p>Email: {session.user.email}</p>
-      <p>Roles: {session.roles.join(', ')}</p>
-    </main>
-  );
-}
-```
-
-#### 2. Route Guard Helper (`protectRoute`)
-
-```typescript
-// app/api/projects/route.ts (Route Handler)
-import { NextResponse } from 'next/server';
-import { protectRoute } from '@cleverclouds/auth-client/nextjs';
-import { auth } from '@/lib/auth';
-
-export async function POST(req: Request) {
-  const { authorized, session, response } = await protectRoute(auth, {
-    request: req,
-    permission: 'projects.create',
-    cookieName: 'projects_session',
-  });
-
-  if (!authorized) {
-    return response!; // Returns 401 Unauthorized or 403 Forbidden with JSON error
-  }
-
-  const body = await req.json();
-  return NextResponse.json({
-    success: true,
-    createdBy: session!.user.email,
-  });
-}
-```
-
-#### 3. SSO Callback Route Handler
-
-```typescript
-// app/api/auth/callback/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { auth } from '@/lib/auth';
-
-export async function GET(req: NextRequest) {
-  const ticket = req.nextUrl.searchParams.get('ticket');
-  const returnTo = req.nextUrl.searchParams.get('returnTo') || '/dashboard';
-
-  if (!ticket) {
-    return NextResponse.json({ error: 'Missing ticket' }, { status: 400 });
-  }
-
-  const exchange = await auth.exchangeTicket(ticket);
-  if (!exchange.success) {
-    return NextResponse.json({ error: exchange.error.message }, { status: 401 });
-  }
-
-  // Cryptographically sign session payload
-  const signedCookie = auth.signSessionCookie(exchange.data, {
-    expiresInSeconds: 7 * 24 * 60 * 60,
-  });
-
-  // Enforce relative redirect (anti-open-redirect)
-  const safePath = returnTo.startsWith('/') && !returnTo.startsWith('//') ? returnTo : '/dashboard';
-  const response = NextResponse.redirect(new URL(safePath, req.url));
-
-  response.cookies.set('projects_session', signedCookie, {
-    httpOnly: true,
-    secure: process.env.NODE_ENV === 'production',
-    sameSite: 'lax',
-    path: '/',
-    maxAge: 7 * 24 * 60 * 60,
-  });
-
-  return response;
-}
-```
-
----
-
-### Pattern C: Fastify / Raw Node HTTP
-
-```typescript
-import Fastify from 'fastify';
-import fastifyCookie from '@fastify/cookie';
-import { auth } from './lib/auth.js';
-
-const fastify = Fastify();
-fastify.register(fastifyCookie);
-
-// Authentication Hook
-fastify.addHook('preHandler', async (req, reply) => {
-  const cookieValue = req.cookies.projects_session;
-  if (!cookieValue) return;
-
-  const session = auth.verifySessionCookie(cookieValue);
-  if (session) {
-    (req as any).auth = session;
-  }
-});
-
-// Guard helper
-function requirePermission(permission: string) {
-  return async (req: any, reply: any) => {
-    if (!req.auth) {
-      return reply.status(401).send({ error: 'Unauthorized' });
-    }
-    if (!auth.hasPermission(req.auth.permissions, permission)) {
-      return reply.status(403).send({ error: 'Forbidden', required: permission });
-    }
-  };
-}
-```
-
----
-
-## 6. Role & Permission Evaluator Rules
-
-The library provides zero-dependency pure evaluation functions:
-
-```typescript
-import {
-  hasPermission,
-  hasAnyPermission,
-  hasAllPermissions,
-  hasRole,
-  hasAnyRole,
-} from '@cleverclouds/auth-client';
-
-// 1. Exact match
-hasPermission(['projects.read', 'projects.create'], 'projects.create'); // true
-
-// 2. Resource Wildcard matching (matches any action under the resource namespace)
-hasPermission(['projects.*'], 'projects.delete'); // true
-hasPermission(['projects.*'], 'finance.read');    // false
-
-// 3. Platform Wildcard matching
-hasPermission(['*.*'], 'anything.action');       // true
-hasPermission(['*'], 'anything.action');         // true
-
-// 4. Multi-permission helpers
-hasAnyPermission(['projects.read'], ['projects.write', 'projects.read']); // true
-hasAllPermissions(['projects.read'], ['projects.write', 'projects.read']); // false
-
-// 5. Role matching (case-insensitive)
-hasRole(['PROJECT_MANAGER'], 'project_manager'); // true
-hasAnyRole(['DEVELOPER'], ['ADMIN', 'DEVELOPER']); // true
-```
-
----
-
-## 7. TypeScript Type Definitions
-
-```typescript
-export interface AuthUser {
-  id: string;
-  email: string;
-  name: string;
-  status: 'ACTIVE' | 'INACTIVE' | 'SUSPENDED';
-  platformRole?: string;
-  avatarUrl?: string;
-}
-
-export interface ApplicationMetadata {
-  id: string;
-  slug: string;
-  name: string;
-}
-
-export interface VerificationResult {
-  valid: boolean;
-  user: AuthUser;
-  application: ApplicationMetadata;
-  roles: string[];
-  permissions: string[];
-}
-
-export interface ClientConfig {
-  identityBaseUrl?: string;     // Default: 'http://localhost:3000'
-  applicationSlug: string;      // e.g. 'projects'
-  applicationApiKey: string;    // 'cc_app_...'
-  redirectUri: string;          // e.g. 'http://localhost:3001/api/auth/callback'
-  sessionSecret?: string;       // Mandatory for cookie signing/verifying
-}
-```
-
----
-
-## 8. Critical Checklist for AI Agents
-
-When writing or refactoring code that uses `@cleverclouds/auth-client`, verify that:
-- [ ] `cookie-parser` is registered before `createAuthMiddleware` in Express apps.
-- [ ] `SESSION_SECRET` is passed in `ClientConfig` whenever cookies are used.
-- [ ] All redirect destinations in callbacks are checked for open redirects (`safePath.startsWith('/') && !safePath.startsWith('//')`).
-- [ ] `ticket` is validated and rejected with HTTP 400 if missing from callback queries.
-- [ ] Cookies are configured with `httpOnly: true`, `secure: true` (in production), and `sameSite: 'lax'`.
-- [ ] Domain authorization checks (e.g. database entity ownership) remain enforced downstream; do not assume identity permissions imply row-level database ownership.
+# @cleverclouds/auth-client — AI Agent & LLM Implementation Guide
+
+> **Note for AI Coding Assistants (Claude, Cursor, Copilot, Antigravity, Devin, Codex):**  
+> Use this document as the authoritative specification when implementing or refactoring authentication and authorization in downstream applications using `@cleverclouds/auth-client`.
+
+---
+
+## 1. Core Mental Model & Architectural Invariants
+
+CleverClouds Identity is a centralized SSO and Identity Management service. Downstream applications (e.g. `projects`, `hr`, `finance`, `ops`) delegate authentication and role/permission assignment to Identity.
+
+### Identity Boundary Rules
+1. **Zero Direct DB Access**: Downstream applications must **never** connect directly to the Identity MongoDB cluster. All communication flows over HTTPS backchannel calls or cryptographic cookies.
+2. **Identity vs. Domain Authorization**:
+   - Identity tells downstream apps: *Who is the user?* (`userId`, `email`, `name`, `status`), *What roles do they hold in THIS app?* (`roles: ["PROJECT_MANAGER"]`), and *What permissions do they have?* (`permissions: ["projects.*"]`).
+   - The downstream application remains **100% responsible** for resource-level authorization (e.g., whether user A owns project #42).
+3. **Mandatory HMAC Cookie Signing**: Downstream session cookies MUST be cryptographically signed using HMAC-SHA256 via a configured `sessionSecret`. The client strictly prohibits unsigned or unverified cookie consumption.
+4. **Single-Use Tickets**: SSO tickets (`cc_ticket_...`) are valid for **60 seconds** and are burned upon first exchange. Never reuse or cache tickets.
+5. **Open Redirect Defense**: When redirecting users post-callback, downstream handlers MUST validate `returnTo` URLs to ensure they are relative paths (starting with `/`, not `//` or `/\`) or match a strict whitelist.
+
+---
+
+## 2. Package Entrypoints & Subpath Imports
+
+```typescript
+// 1. Core client, types, error classes, and standalone RBAC evaluators
+import {
+  CleverCloudsAuthClient,
+  hasPermission,
+  hasAnyPermission,
+  hasAllPermissions,
+  hasRole,
+  hasAnyRole,
+  CleverCloudsAuthError,
+  AppAccessDeniedError,
+  InvalidTicketError,
+  InvalidCredentialsError,
+} from '@cleverclouds/auth-client';
+
+// 2. Express.js middleware and route helpers
+import { createAuthMiddleware } from '@cleverclouds/auth-client/express';
+
+// 3. Next.js App Router helpers (Server Components, Route Handlers, Server Actions)
+import { getServerSession, protectRoute } from '@cleverclouds/auth-client/nextjs';
+
+// 4. Low-level HMAC-SHA256 cookie signer & verifier
+import { signCookie, verifyCookie } from '@cleverclouds/auth-client/cookies';
+```
+
+---
+
+## 3. Required Environment Variables
+
+Downstream applications must define these environment variables:
+
+```env
+# URL where CleverClouds Identity is hosted
+CC_IDENTITY_URL=https://auth.cleverclouds.in
+
+# Application identifier registered in CleverClouds Identity
+CC_APP_SLUG=projects
+
+# Application API key generated in CleverClouds Identity Admin Console
+CC_APP_KEY=cc_app_projects_xxxxxxxxxxxxxxxx
+
+# Callback URL registered in application's redirectUrls
+CC_REDIRECT_URI=https://projects.cleverclouds.in/api/auth/callback
+
+# Strong secret for signing downstream session cookies (min 32 characters)
+SESSION_SECRET=super_strong_random_secret_at_least_32_chars_long
+```
+
+---
+
+## 4. Initializing the Client Singleton
+
+Create a shared singleton instance (e.g. `src/lib/auth.ts` or `src/auth.ts`):
+
+```typescript
+import { CleverCloudsAuthClient } from '@cleverclouds/auth-client';
+
+export const auth = new CleverCloudsAuthClient({
+  identityBaseUrl: process.env.CC_IDENTITY_URL || 'http://localhost:3000',
+  applicationSlug: process.env.CC_APP_SLUG || 'projects',
+  applicationApiKey: process.env.CC_APP_KEY!,
+  redirectUri: process.env.CC_REDIRECT_URI || 'http://localhost:3001/api/auth/callback',
+  sessionSecret: process.env.SESSION_SECRET!, // Mandatory for session cookie signing
+});
+```
+
+---
+
+## 5. Implementation Recipes
+
+### Pattern A: Express.js (API & SSR)
+
+```typescript
+import express from 'express';
+import cookieParser from 'cookie-parser';
+import { createAuthMiddleware } from '@cleverclouds/auth-client/express';
+import { auth } from './lib/auth.js';
+
+const app = express();
+app.use(express.json());
+app.use(cookieParser()); // REQUIRED: cookie-parser middleware must precede auth middleware
+
+// Initialize middleware adapter
+const {
+  requireAuth,
+  requirePermission,
+  requireRole,
+  handleCallback,
+  handleLogout,
+} = createAuthMiddleware(auth, {
+  cookieName: 'projects_session',
+  cookieOptions: {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax',
+    path: '/',
+    maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
+  },
+});
+
+// 1. SSO Callback Route — Exchanges ticket and sets signed session cookie
+app.get('/api/auth/callback', handleCallback({
+  defaultReturnTo: '/dashboard',
+  allowedRedirectHosts: ['projects.cleverclouds.in', 'localhost:3001'],
+}));
+
+// 2. Logout Route — Clears session cookie and redirects
+app.get('/logout', handleLogout({
+  redirectTo: '/login',
+}));
+
+// 3. Authenticated Route — Attaches req.auth: VerificationResult
+app.get('/api/me', requireAuth(), (req, res) => {
+  res.json({
+    user: req.auth.user,
+    roles: req.auth.roles,
+    permissions: req.auth.permissions,
+  });
+});
+
+// 4. Permission-Gated Route (supports wildcards e.g. 'projects.*')
+app.post('/api/projects', requirePermission('projects.create'), async (req, res) => {
+  // Safe: user is guaranteed to have 'projects.create' or 'projects.*' or '*.*'
+  res.json({ message: 'Project created' });
+});
+
+// 5. Role-Gated Route (case-insensitive role check)
+app.delete('/api/projects/:id', requireRole('project_admin'), async (req, res) => {
+  res.json({ message: 'Project deleted' });
+});
+
+// Optional: Custom Login Trigger (redirects browser to Identity)
+app.get('/login', (req, res) => {
+  const returnTo = typeof req.query.returnTo === 'string' ? req.query.returnTo : '/dashboard';
+  const loginUrl = auth.getAuthorizationUrl({ returnTo });
+  res.redirect(loginUrl);
+});
+```
+
+---
+
+### Pattern B: Next.js App Router (14/15)
+
+#### 1. Server Components & Route Handlers (`getServerSession`)
+
+```typescript
+// app/dashboard/page.tsx (Server Component)
+import { redirect } from 'next/navigation';
+import { getServerSession } from '@cleverclouds/auth-client/nextjs';
+import { auth } from '@/lib/auth';
+
+export default async function DashboardPage() {
+  const session = await getServerSession(auth, { cookieName: 'projects_session' });
+
+  if (!session) {
+    redirect(auth.getAuthorizationUrl({ returnTo: '/dashboard' }));
+  }
+
+  return (
+    <main>
+      <h1>Welcome, {session.user.name}</h1>
+      <p>Email: {session.user.email}</p>
+      <p>Roles: {session.roles.join(', ')}</p>
+    </main>
+  );
+}
+```
+
+#### 2. Route Guard Helper (`protectRoute`)
+
+```typescript
+// app/api/projects/route.ts (Route Handler)
+import { NextResponse } from 'next/server';
+import { protectRoute } from '@cleverclouds/auth-client/nextjs';
+import { auth } from '@/lib/auth';
+
+export async function POST(req: Request) {
+  const { authorized, session, response } = await protectRoute(auth, {
+    request: req,
+    permission: 'projects.create',
+    cookieName: 'projects_session',
+  });
+
+  if (!authorized) {
+    return response!; // Returns 401 Unauthorized or 403 Forbidden with JSON error
+  }
+
+  const body = await req.json();
+  return NextResponse.json({
+    success: true,
+    createdBy: session!.user.email,
+  });
+}
+```
+
+#### 3. SSO Callback Route Handler
+
+```typescript
+// app/api/auth/callback/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { auth } from '@/lib/auth';
+
+export async function GET(req: NextRequest) {
+  const ticket = req.nextUrl.searchParams.get('ticket');
+  const returnTo = req.nextUrl.searchParams.get('returnTo') || '/dashboard';
+
+  if (!ticket) {
+    return NextResponse.json({ error: 'Missing ticket' }, { status: 400 });
+  }
+
+  const exchange = await auth.exchangeTicket(ticket);
+  if (!exchange.success) {
+    return NextResponse.json({ error: exchange.error.message }, { status: 401 });
+  }
+
+  // Cryptographically sign session payload
+  const signedCookie = auth.signSessionCookie(exchange.data, {
+    expiresInSeconds: 7 * 24 * 60 * 60,
+  });
+
+  // Enforce relative redirect (anti-open-redirect)
+  const safePath = returnTo.startsWith('/') && !returnTo.startsWith('//') ? returnTo : '/dashboard';
+  const response = NextResponse.redirect(new URL(safePath, req.url));
+
+  response.cookies.set('projects_session', signedCookie, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax',
+    path: '/',
+    maxAge: 7 * 24 * 60 * 60,
+  });
+
+  return response;
+}
+```
+
+---
+
+### Pattern C: Fastify / Raw Node HTTP
+
+```typescript
+import Fastify from 'fastify';
+import fastifyCookie from '@fastify/cookie';
+import { auth } from './lib/auth.js';
+
+const fastify = Fastify();
+fastify.register(fastifyCookie);
+
+// Authentication Hook
+fastify.addHook('preHandler', async (req, reply) => {
+  const cookieValue = req.cookies.projects_session;
+  if (!cookieValue) return;
+
+  const session = auth.verifySessionCookie(cookieValue);
+  if (session) {
+    (req as any).auth = session;
+  }
+});
+
+// Guard helper
+function requirePermission(permission: string) {
+  return async (req: any, reply: any) => {
+    if (!req.auth) {
+      return reply.status(401).send({ error: 'Unauthorized' });
+    }
+    if (!auth.hasPermission(req.auth.permissions, permission)) {
+      return reply.status(403).send({ error: 'Forbidden', required: permission });
+    }
+  };
+}
+```
+
+---
+
+## 6. Role & Permission Evaluator Rules
+
+The library provides zero-dependency pure evaluation functions:
+
+```typescript
+import {
+  hasPermission,
+  hasAnyPermission,
+  hasAllPermissions,
+  hasRole,
+  hasAnyRole,
+} from '@cleverclouds/auth-client';
+
+// 1. Exact match
+hasPermission(['projects.read', 'projects.create'], 'projects.create'); // true
+
+// 2. Resource Wildcard matching (matches any action under the resource namespace)
+hasPermission(['projects.*'], 'projects.delete'); // true
+hasPermission(['projects.*'], 'finance.read');    // false
+
+// 3. Platform Wildcard matching
+hasPermission(['*.*'], 'anything.action');       // true
+hasPermission(['*'], 'anything.action');         // true
+
+// 4. Multi-permission helpers
+hasAnyPermission(['projects.read'], ['projects.write', 'projects.read']); // true
+hasAllPermissions(['projects.read'], ['projects.write', 'projects.read']); // false
+
+// 5. Role matching (case-insensitive)
+hasRole(['PROJECT_MANAGER'], 'project_manager'); // true
+hasAnyRole(['DEVELOPER'], ['ADMIN', 'DEVELOPER']); // true
+```
+
+---
+
+## 7. TypeScript Type Definitions
+
+```typescript
+export interface AuthUser {
+  id: string;
+  email: string;
+  name: string;
+  status: 'ACTIVE' | 'INACTIVE' | 'SUSPENDED';
+  platformRole?: string;
+  avatarUrl?: string;
+}
+
+export interface ApplicationMetadata {
+  id: string;
+  slug: string;
+  name: string;
+}
+
+export interface VerificationResult {
+  valid: boolean;
+  user: AuthUser;
+  application: ApplicationMetadata;
+  roles: string[];
+  permissions: string[];
+}
+
+export interface ClientConfig {
+  identityBaseUrl?: string;     // Default: 'http://localhost:3000'
+  applicationSlug: string;      // e.g. 'projects'
+  applicationApiKey: string;    // 'cc_app_...'
+  redirectUri: string;          // e.g. 'http://localhost:3001/api/auth/callback'
+  sessionSecret?: string;       // Mandatory for cookie signing/verifying
+}
+```
+
+---
+
+## 8. Critical Checklist for AI Agents
+
+When writing or refactoring code that uses `@cleverclouds/auth-client`, verify that:
+- [ ] `cookie-parser` is registered before `createAuthMiddleware` in Express apps.
+- [ ] `SESSION_SECRET` is passed in `ClientConfig` whenever cookies are used.
+- [ ] All redirect destinations in callbacks are checked for open redirects (`safePath.startsWith('/') && !safePath.startsWith('//')`).
+- [ ] `ticket` is validated and rejected with HTTP 400 if missing from callback queries.
+- [ ] Cookies are configured with `httpOnly: true`, `secure: true` (in production), and `sameSite: 'lax'`.
+- [ ] Domain authorization checks (e.g. database entity ownership) remain enforced downstream; do not assume identity permissions imply row-level database ownership.