@cleverclouds/auth-client 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,451 @@
-# Temporary Holding Version
+# @cleverclouds/auth-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@cleverclouds/auth-client.svg?style=flat-square)](https://www.npmjs.com/package/@cleverclouds/auth-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
+[![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero%20Runtime-green.svg?style=flat-square)](#)
+
+> Lightweight, framework-agnostic client SDK for **CleverClouds Identity (OneAuth)** with native Express and Next.js App Router adapters, tamper-proof HMAC-SHA256 session cookies, and fine-grained RBAC evaluation.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Architecture & Mental Model](#architecture--mental-model)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Subpath Exports](#subpath-exports)
+- [Express.js Integration](#expressjs-integration)
+- [Next.js App Router Integration](#nextjs-app-router-integration)
+- [Fastify / Raw Node.js Integration](#fastify--raw-nodejs-integration)
+- [Frontend (SPA) Integration Pattern](#frontend-spa-integration-pattern)
+- [Role-Based Access Control (RBAC)](#role-based-access-control-rbac)
+- [Cryptographic Cookie Security](#cryptographic-cookie-security)
+- [Error Handling](#error-handling)
+- [AI Agents & LLMs Guide](#ai-agents--llms-guide)
+- [License](#license)
+
+---
+
+## Features
+
+- 🚀 **Zero external runtime dependencies** for core client (uses Node.js standard `fetch` & `crypto`).
+- 🛡️ **Tamper-Proof Session Security**: Built-in HMAC-SHA256 cookie signing and constant-time verification (`crypto.timingSafeEqual`).
+- ⚡ **Express Middleware Adapter**: Drop-in `requireAuth()`, `requirePermission()`, `requireRole()`, `handleCallback()`, and `handleLogout()`.
+- 🌐 **Next.js App Router Adapter**: Server Component, Server Action, and Route Handler session extractors (`getServerSession()`, `protectRoute()`).
+- 🎯 **Fine-Grained RBAC**: Exact permission matching, resource wildcards (`projects.*`), platform wildcards (`*.*`), and case-insensitive role checks.
+- 🔒 **Defense-in-Depth Open Redirect Protection**: Built-in hostname validation and relative-path enforcement on callback redirections.
+- 🤖 **Agent-Ready**: Includes a dedicated [AGENTS.md](AGENTS.md) specification packed directly in the distribution for AI coding assistants.
+
+---
+
+## Architecture & Mental Model
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as Employee Browser
+    participant App as Downstream App (Express / Next.js)
+    participant Identity as CleverClouds Identity (OneAuth)
+
+    User->>App: GET /dashboard (unauthenticated)
+    App-->>User: 302 Redirect to Identity /login?app=projects&returnTo=...
+    User->>Identity: Authenticate (SSO / Credentials / MFA)
+    Identity->>Identity: Validate registered redirect URL & generate 60s ticket
+    Identity-->>User: 302 Redirect to /api/auth/callback?ticket=cc_ticket_...
+    User->>App: GET /api/auth/callback?ticket=cc_ticket_...
+    App->>Identity: POST /api/integration/token-exchange (X-Application-Key)
+    Identity-->>App: 200 OK { user, roles, permissions }
+    App->>App: Sign session payload (HMAC-SHA256) via sessionSecret
+    App-->>User: 302 Redirect to /dashboard + Set Signed Session Cookie
+    User->>App: GET /dashboard (with signed cookie)
+    App->>App: Constant-time HMAC verify & grant access
+```
+
+---
+
+## Installation
+
+```bash
+# Using npm:
+npm install @cleverclouds/auth-client
+
+# Using yarn:
+yarn add @cleverclouds/auth-client
+
+# Using pnpm:
+pnpm add @cleverclouds/auth-client
+```
+
+### Peer Dependencies
+If using the framework adapters:
+- **Express**: `npm install express cookie-parser`
+- **Next.js**: `npm install next` (v14 or v15)
+
+---
+
+## Configuration
+
+Set the following environment variables in your downstream application:
+
+```env
+# URL of your CleverClouds Identity instance
+CC_IDENTITY_URL=https://auth.cleverclouds.in
+
+# Application slug registered in CleverClouds Identity
+CC_APP_SLUG=projects
+
+# Application API key issued from the Identity Admin Console
+CC_APP_KEY=cc_app_projects_xxxxxxxxxxxxxxxx
+
+# Registered callback URI
+CC_REDIRECT_URI=https://projects.cleverclouds.in/api/auth/callback
+
+# Strong secret for signing downstream session cookies (minimum 32 characters)
+SESSION_SECRET=a_very_strong_random_secret_at_least_32_characters_long
+```
+
+### Initializing the Client Singleton
+
+```typescript
+// src/lib/auth.ts
+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 when using cookie sessions
+});
+```
+
+---
+
+## Subpath Exports
+
+| Import Path | Description | Key Exports |
+| :--- | :--- | :--- |
+| `@cleverclouds/auth-client` | Core client, errors, and pure RBAC evaluators | `CleverCloudsAuthClient`, `hasPermission`, `hasRole`, `hasAnyPermission` |
+| `@cleverclouds/auth-client/express` | Express.js middleware and route handlers | `createAuthMiddleware` |
+| `@cleverclouds/auth-client/nextjs` | Next.js App Router helpers | `getServerSession`, `protectRoute` |
+| `@cleverclouds/auth-client/cookies` | Low-level HMAC signer and verifier | `signCookie`, `verifyCookie` |
+
+---
+
+## Express.js Integration
+
+### Full Server Setup
+
+```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 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 Endpoint
+// Redeems single-use ticket, signs session cookie, and safely redirects to returnTo
+app.get('/api/auth/callback', handleCallback({
+  defaultReturnTo: '/dashboard',
+  allowedRedirectHosts: ['projects.cleverclouds.in', 'localhost:3001'],
+}));
+
+// 2. Logout Endpoint
+// Clears session cookie and redirects user
+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 exact match or wildcards ('projects.*')
+app.post('/api/projects', requirePermission('projects.create'), (req, res) => {
+  res.json({ message: 'Project created by ' + req.auth.user.email });
+});
+
+// 5. Role-Gated Route
+// Evaluates application roles case-insensitively
+app.delete('/api/projects/:id', requireRole('project_admin'), (req, res) => {
+  res.json({ message: 'Project deleted' });
+});
+
+app.listen(3001, () => {
+  console.log('Downstream service listening on http://localhost:3001');
+});
+```
+
+---
+
+## Next.js App Router Integration
+
+### 1. Server Components & Pages
+
+```typescript
+// app/dashboard/page.tsx
+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 (
+    <div className="p-8">
+      <h1 className="text-2xl font-bold">Welcome, {session.user.name}</h1>
+      <p className="text-gray-600">Email: {session.user.email}</p>
+      <div className="mt-4">
+        <span className="font-semibold">Assigned Roles:</span>
+        <span className="ml-2 bg-blue-100 text-blue-800 px-2 py-1 rounded">
+          {session.roles.join(', ')}
+        </span>
+      </div>
+    </div>
+  );
+}
+```
+
+### 2. Route Handlers (`protectRoute`)
+
+```typescript
+// app/api/projects/route.ts
+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 JSON
+  }
+
+  const payload = await req.json();
+  return NextResponse.json({
+    success: true,
+    createdItem: payload,
+    createdBy: session!.user.email,
+  });
+}
+```
+
+### 3. Next.js SSO Callback Route
+
+```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 authorization ticket' }, { status: 400 });
+  }
+
+  const exchange = await auth.exchangeTicket(ticket);
+  if (!exchange.success) {
+    return NextResponse.json({ error: exchange.error.message }, { status: 401 });
+  }
+
+  const signedCookie = auth.signSessionCookie(exchange.data, {
+    expiresInSeconds: 7 * 24 * 60 * 60,
+  });
+
+  // Strict relative redirect enforcement
+  const safeRedirect = returnTo.startsWith('/') && !returnTo.startsWith('//')
+    ? returnTo
+    : '/dashboard';
+
+  const res = NextResponse.redirect(new URL(safeRedirect, req.url));
+  res.cookies.set('projects_session', signedCookie, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax',
+    path: '/',
+    maxAge: 7 * 24 * 60 * 60,
+  });
+
+  return res;
+}
+```
+
+---
+
+## Fastify / Raw Node.js Integration
+
+```typescript
+import Fastify from 'fastify';
+import fastifyCookie from '@fastify/cookie';
+import { auth } from './lib/auth.js';
+
+const app = Fastify();
+app.register(fastifyCookie);
+
+// Authentication Hook
+app.addHook('preHandler', async (req, reply) => {
+  const cookie = req.cookies.projects_session;
+  if (!cookie) return;
+
+  const session = auth.verifySessionCookie(cookie);
+  if (session) {
+    (req as any).auth = session;
+  }
+});
+
+app.get('/api/projects', async (req, reply) => {
+  const authUser = (req as any).auth;
+  if (!authUser) {
+    return reply.status(401).send({ error: 'Unauthorized' });
+  }
+
+  if (!auth.hasPermission(authUser.permissions, 'projects.read')) {
+    return reply.status(403).send({ error: 'Forbidden' });
+  }
+
+  return { projects: [] };
+});
+```
+
+---
+
+## Frontend (SPA) Integration Pattern
+
+For Single-Page Applications (Vite / React / Vue / Angular):
+1. **Login Trigger**: When the user clicks "Log In", navigate the browser to:
+   ```javascript
+   window.location.href = `https://auth.cleverclouds.in/login?app=projects&returnTo=${encodeURIComponent('https://projects.cleverclouds.in/api/auth/callback')}`;
+   ```
+2. **Callback Handling**: Your backend API (Express or Next.js) handles `/api/auth/callback`, redeems the ticket, sets the `HttpOnly` signed cookie, and redirects the browser back to `https://projects.cleverclouds.in/dashboard`.
+3. **Session Check**: The SPA calls `GET /api/me` on startup. The browser includes the `HttpOnly` cookie automatically. The backend returns the current user profile, roles, and permissions.
+
+---
+
+## Role-Based Access Control (RBAC)
+
+The SDK provides both standalone evaluator functions and client instance methods.
+
+```typescript
+import {
+  hasPermission,
+  hasAnyPermission,
+  hasAllPermissions,
+  hasRole,
+  hasAnyRole,
+} from '@cleverclouds/auth-client';
+
+const userPermissions = ['projects.read', 'projects.create'];
+
+// 1. Exact Match
+hasPermission(userPermissions, 'projects.read');   // true
+hasPermission(userPermissions, 'projects.delete'); // false
+
+// 2. Resource Wildcard Matching
+const managerPermissions = ['projects.*'];
+hasPermission(managerPermissions, 'projects.create'); // true
+hasPermission(managerPermissions, 'projects.delete'); // true
+hasPermission(managerPermissions, 'billing.read');    // false
+
+// 3. Platform Wildcard Matching
+hasPermission(['*.*'], 'any.permission'); // true
+hasPermission(['*'], 'any.permission');   // true
+
+// 4. Role Evaluation (Case-Insensitive)
+hasRole(['PROJECT_MANAGER'], 'project_manager'); // true
+hasAnyRole(['DEVELOPER'], ['ADMIN', 'DEVELOPER']); // true
+```
+
+---
+
+## Cryptographic Cookie Security
+
+Session tokens stored in cookies are formatted as:
+```
+<base64url-encoded-payload>.<hex-hmac-sha256-signature>
+```
+
+- **HMAC-SHA256**: Keyed with `sessionSecret`.
+- **Constant-Time Verification**: Verification uses Node.js `crypto.timingSafeEqual` to eliminate timing side-channel attacks.
+- **Expiration Protection**: Every signed payload embeds an `exp` timestamp validated during verification.
+- **Tamper Rejection**: Any modification of payload bytes or signature yields `null` without throwing.
+
+---
+
+## Error Handling
+
+The client throws strongly-typed errors inheriting from `CleverCloudsAuthError`:
+
+```typescript
+import {
+  CleverCloudsAuthError,
+  AppAccessDeniedError,
+  InvalidTicketError,
+  InvalidCredentialsError,
+} from '@cleverclouds/auth-client';
+
+try {
+  const result = await auth.exchangeTicket(ticket);
+} catch (err) {
+  if (err instanceof AppAccessDeniedError) {
+    console.error('User does not have permission to access this application');
+  } else if (err instanceof InvalidTicketError) {
+    console.error('Ticket has expired or was already consumed');
+  } else if (err instanceof InvalidCredentialsError) {
+    console.error('Invalid application API key');
+  }
+}
+```
+
+---
+
+## AI Agents & LLMs Guide
+
+If you are developing with or configuring AI coding assistants (Claude Code, Cursor, GitHub Copilot, Antigravity, Devin):
+- Consult [AGENTS.md](AGENTS.md) for concise, prompt-ready rules, schema definitions, and implementation checklists.
+- Downstream repositories installing `@cleverclouds/auth-client` automatically receive `node_modules/@cleverclouds/auth-client/AGENTS.md`.
+
+---
+
+## License
+
+MIT © CleverClouds

package/dist/client.d.ts

@@ -0,0 +1,61 @@
+import type { ClientConfig, VerificationResult, AuthorizationUrlOptions, CookieSignOptions } from './types.js';
+import { hasPermission, hasAnyPermission, hasAllPermissions, hasRole, hasAnyRole } from './permissions.js';
+import { CleverCloudsAuthError } from './errors.js';
+export declare class CleverCloudsAuthClient {
+    readonly identityBaseUrl: string;
+    readonly applicationSlug: string;
+    readonly applicationApiKey: string;
+    readonly redirectUri: string;
+    readonly sessionSecret?: string;
+    constructor(config: ClientConfig);
+    /**
+     * Generates the SSO authorization redirect URL pointing to CleverClouds Identity.
+     */
+    getAuthorizationUrl(options?: AuthorizationUrlOptions): string;
+    /**
+     * Generates the direct login initiation URL pointing to CleverClouds Identity.
+     */
+    getLoginUrl(options?: AuthorizationUrlOptions): string;
+    /**
+     * Generates the Identity logout URL.
+     */
+    getLogoutUrl(returnTo?: string): string;
+    /**
+     * Exchanges an authorization ticket with detailed success/error response.
+     */
+    exchangeTicketDetailed(ticket: string): Promise<{
+        success: true;
+        data: VerificationResult;
+    } | {
+        success: false;
+        error: CleverCloudsAuthError;
+    }>;
+    /**
+     * Exchanges a single-use authorization ticket with CleverClouds Identity for
+     * the verified user profile, assigned roles, and application-scoped permissions.
+     */
+    exchangeTicket(ticket: string): Promise<VerificationResult | null>;
+    /**
+     * Verifies an active session token directly against CleverClouds Identity.
+     */
+    verifySession(sessionToken: string): Promise<VerificationResult | null>;
+    /**
+     * Encodes and cryptographically signs a session payload for storage in downstream cookies.
+     */
+    signSessionCookie(result: VerificationResult, options?: CookieSignOptions): string;
+    /**
+     * Verifies an incoming session cookie value, enforcing HMAC integrity via sessionSecret.
+     */
+    verifySessionCookie(cookieValue: string): VerificationResult | null;
+    hasPermission(permissions: string[], required: string): boolean;
+    hasAnyPermission(permissions: string[], requiredList: string[]): boolean;
+    hasAllPermissions(permissions: string[], requiredList: string[]): boolean;
+    hasRole(roles: string[], roleSlug: string): boolean;
+    hasAnyRole(roles: string[], roleSlugs: string[]): boolean;
+    static hasPermission: typeof hasPermission;
+    static hasAnyPermission: typeof hasAnyPermission;
+    static hasAllPermissions: typeof hasAllPermissions;
+    static hasRole: typeof hasRole;
+    static hasAnyRole: typeof hasAnyRole;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,OAAO,EACP,UAAU,EACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,qBAAqB,EAItB,MAAM,aAAa,CAAC;AAErB,qBAAa,sBAAsB;IACjC,SAAgB,eAAe,EAAE,MAAM,CAAC;IACxC,SAAgB,eAAe,EAAE,MAAM,CAAC;IACxC,SAAgB,iBAAiB,EAAE,MAAM,CAAC;IAC1C,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,SAAgB,aAAa,CAAC,EAAE,MAAM,CAAC;gBAE3B,MAAM,EAAE,YAAY;IAkBhC;;OAEG;IACI,mBAAmB,CAAC,OAAO,GAAE,uBAA4B,GAAG,MAAM;IAUzE;;OAEG;IACI,WAAW,CAAC,OAAO,GAAE,uBAA4B,GAAG,MAAM;IAUjE;;OAEG;IACI,YAAY,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;IAQ9C;;OAEG;IACU,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CACxD;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,kBAAkB,CAAA;KAAE,GAC3C;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,qBAAqB,CAAA;KAAE,CACnD;IAgFD;;;OAGG;IACU,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAK/E;;OAEG;IACU,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAiCpF;;OAEG;IACI,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM;IAO7F;;OAEG;IACI,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAYnE,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI/D,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO;IAIxE,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO;IAIzE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAInD,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO;IAMhE,OAAc,aAAa,uBAAiB;IAC5C,OAAc,gBAAgB,0BAAoB;IAClD,OAAc,iBAAiB,2BAAqB;IACpD,OAAc,OAAO,iBAAW;IAChC,OAAc,UAAU,oBAAc;CACvC"}