feat: introduce Riligar Auth skills for React and Elysia, including documentation, code snippets, and setup guides.

Author: ciro-maciel

.agent/skills/riligar-dev-auth-elysia/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: riligar-dev-auth-elysia
+description: 'Comprehensive guide for integrating the Riligar Auth Elysia SDK into backend servers. Use when a user needs to: (1) Set up a backend auth plugin, (2) Configure Elysia with Riligar Secret Key, (3) Protect API routes or groups, (4) Access authenticated user data in handlers, (5) Perform manual JWT verification.'
+---
+
+# Riligar Auth Elysia Skill
+
+This skill provides a backend workflow for integrating authentication and permissions using the `@riligar/auth-elysia` SDK.
+
+## Core Integration Workflow
+
+### 1. Installation
+
+Install the backend SDK:
+
+```bash
+npm install @riligar/auth-elysia
+```
+
+### 2. Environment Variables
+
+Set up your Secret Key and URLs in your `.env` file.
+
+> [!CAUTION]
+> Backend integration requires the **Secret Key** (`sk_...`). Never share this key or include it in client-side code.
+
+```bash
+# .env
+AUTH_API_URL=https://manager.myauth.click
+AUTH_API_SECRET=sk_live_your_secret_key
+AUTH_JWKS_URL=https://manager.myauth.click/.well-known/jwks.json
+```
+
+### 3. Plugin Registration
+
+Add the `authPlugin` to your Elysia instance.
+
+```typescript
+import { Elysia } from 'elysia'
+import { authPlugin } from '@riligar/auth-elysia'
+
+const app = new Elysia()
+    .use(
+        authPlugin({
+            apiUrl: process.env.AUTH_API_URL,
+            apiKey: process.env.AUTH_API_SECRET,
+            jwksUrl: process.env.AUTH_JWKS_URL,
+        })
+    )
+    .listen(3000)
+```
+
+For more patterns, see [server-snippets.ts](assets/server-snippets.ts).
+
+## Specialized Guides
+
+- **Context & User Data**: Documentation for `ctx.auth` and `ctx.user`. See [context-and-user.md](references/context-and-user.md).
+- **Route Protection**: How to implement `requireAuth` middleware and guard route groups. See [route-protection.md](references/route-protection.md).
+- **Manual Verification**: Using `verifyToken` for custom JWT handling. See [manual-verification.md](references/manual-verification.md).
+
+## Common Tasks
+
+### Protecting a Route Group
+
+Use `onBeforeHandle` to secure multiple endpoints efficiently.
+
+```typescript
+app.group('/api/v1', app => app.onBeforeHandle(requireAuth).get('/data', () => ({ ok: true })))
+```
+
+### Accessing User Profile
+
+Access the decoded user data directly from the context.
+
+```typescript
+app.get('/profile', ({ user }) => {
+    return { id: user.id, email: user.email }
+})
+```

.agent/skills/riligar-dev-auth-elysia/assets/server-snippets.ts

@@ -0,0 +1,45 @@
+// Server Snippets for Elysia
+
+// 1. Core Server with Auth Plugin
+export const fullServerSetup = `
+import { Elysia } from 'elysia'
+import { authPlugin } from '@riligar/auth-elysia'
+
+const app = new Elysia()
+    .use(authPlugin({
+        apiUrl: process.env.AUTH_API_URL,   // https://manager.myauth.click
+        apiKey: process.env.AUTH_API_SECRET, // sk_live_...
+        jwksUrl: process.env.AUTH_JWKS_URL, // .well-known/jwks.json
+    }))
+    .get('/public', () => 'Hello World')
+    .get('/private', ({ auth, user }) => {
+        if (!auth.isAuthenticated) return 'Unauthorized'
+        return \`Hello \${user.name}\`
+    })
+    .listen(3000)
+`
+
+// 2. Auth Middleware
+export const middlewareSnippet = `
+export const requireAuth = ({ auth, set }) => {
+    if (!auth.isAuthenticated) {
+        set.status = 401
+        return { error: 'Unauthorized' }
+    }
+}
+
+// Usage: app.get('/protected', requireAuth, () => 'Secret Area')
+`
+
+// 3. User Data access
+export const userAccessSnippet = `
+app.get('/me', ({ auth, user }) => {
+    if (!auth.isAuthenticated) return { error: 'Not logged in' }
+    
+    return {
+        id: user.id,
+        email: user.email,
+        verified: user.emailVerified
+    }
+})
+`

.agent/skills/riligar-dev-auth-elysia/references/context-and-user.md

@@ -0,0 +1,26 @@
+# Auth Context and User Object
+
+The `@riligar/auth-elysia` plugin decorates the Elysia context with `auth` and `user` objects.
+
+## Auth Object (`ctx.auth`)
+
+Provides metadata about the current request's authentication state.
+
+| Property               | Type               | Description                                      |
+| :--------------------- | :----------------- | :----------------------------------------------- |
+| `auth.isAuthenticated` | `boolean`          | `true` if a valid JWT was found and verified.    |
+| `auth.token`           | `string \| null`   | The raw JWT token from the Authorization header. |
+| `auth.error`           | `string \| null`   | Error message if verification failed.            |
+| `auth.verify()`        | `Promise<boolean>` | Manually triggers token verification.            |
+
+## User Object (`ctx.user`)
+
+Contains the decoded payload from the JWT. Only populated if `isAuthenticated` is `true`.
+
+| Property             | Type      | Description                                       |
+| :------------------- | :-------- | :------------------------------------------------ |
+| `user.id`            | `string`  | Unique identifier of the user (from `sub` claim). |
+| `user.email`         | `string`  | User's email address.                             |
+| `user.name`          | `string`  | User's display name.                              |
+| `user.emailVerified` | `boolean` | Whether the user's email has been verified.       |
+| `user.metadata`      | `object`  | Custom metadata associated with the user account. |

.agent/skills/riligar-dev-auth-elysia/references/manual-verification.md

@@ -0,0 +1,36 @@
+# Manual Token Verification
+
+In some cases, you may need to verify a JWT manually outside of the standard `authPlugin` context (e.g., in a background job, cron, or a custom WebSocket handler).
+
+## Using `verifyToken`
+
+The SDK exports a `verifyToken` function that handles the full JWKS verification flow.
+
+```typescript
+import { verifyToken } from '@riligar/auth-elysia'
+
+async function customHandler(token: string) {
+    try {
+        const payload = await verifyToken(token, {
+            jwksUrl: process.env.AUTH_JWKS_URL,
+            // optional: issuer, audience verification
+        })
+
+        console.log('Valid user:', payload.sub)
+        return payload
+    } catch (error) {
+        console.error('Verification failed:', error.message)
+        throw new Error('Unauthorized')
+    }
+}
+```
+
+## JWKS Caching
+
+The `verifyToken` function automatically caches the JWKS keys to avoid unnecessary network requests. If you need to force a refresh (e.g., after a key rotation), use `refreshJwks`:
+
+```typescript
+import { refreshJwks } from '@riligar/auth-elysia'
+
+await refreshJwks(process.env.AUTH_JWKS_URL)
+```

.agent/skills/riligar-dev-auth-elysia/references/route-protection.md

@@ -0,0 +1,52 @@
+# Route Protection and Middleware
+
+Effective patterns for securing your Elysia API routes.
+
+## Recommended Middleware Pattern
+
+Create a reusable `requireAuth` helper to enforce authentication on specific endpoints.
+
+```typescript
+const requireAuth = ({ auth, set }) => {
+    if (!auth.isAuthenticated) {
+        set.status = 401
+        return { error: 'Unauthorized: Missing or invalid token' }
+    }
+}
+```
+
+## Applying Protection
+
+### To a single route
+
+```typescript
+app.get('/me', requireAuth, ({ user }) => {
+    return { name: user.name }
+})
+```
+
+### To a group of routes
+
+Use `onBeforeHandle` to protect an entire API section.
+
+```typescript
+app.group('/api/admin', app =>
+    app
+        .onBeforeHandle(requireAuth)
+        .get('/dashboard', () => ({ stats: '...' }))
+        .post('/settings', () => ({ saved: true }))
+)
+```
+
+## Permission-Based access (RBAC)
+
+You can extend the middleware to check for specific roles or permissions.
+
+```typescript
+const requireAdmin = ({ auth, user, set }) => {
+    if (!auth.isAuthenticated || user.role !== 'admin') {
+        set.status = 403
+        return { error: 'Forbidden' }
+    }
+}
+```

.agent/skills/riligar-dev-auth-react/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: riligar-dev-auth-react
+description: 'Comprehensive guide for integrating the Riligar Auth React SDK into web applications. Use when a user needs to: (1) Set up authentication from scratch, (2) Configure AuthProvider, (3) Implement route protection, (4) Use auth hooks or pre-built UI components, (5) Handle login/signup/profile/magic links in React.'
+---
+
+# Riligar Auth React Skill
+
+This skill provides a complete workflow for integrating authentication and permissions using the `@riligar/auth-react` SDK.
+
+## Core Integration Workflow
+
+### 1. Installation
+
+Install the SDK using bun (preferred) or npm:
+
+```bash
+bun add @riligar/auth-react
+```
+
+### 2. Environment Variables
+
+Set up your Public Key in your `.env.local` file.
+
+> [!IMPORTANT]
+> Always use the **Public Key** (`pk_...`) in the frontend. Never expose your Secret Key.
+
+```bash
+# .env.local
+VITE_AUTH_API_KEY=pk_live_your_public_key
+```
+
+### 3. AuthProvider Setup
+
+Wrap your application (usually in `main.jsx` or `App.jsx`) with the `AuthProvider`.
+
+```jsx
+import { AuthProvider } from '@riligar/auth-react'
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+    <AuthProvider apiKey={import.meta.env.VITE_AUTH_API_KEY}>
+        <App />
+    </AuthProvider>
+)
+```
+
+For more setup patterns, see [setup-snippets.js](assets/setup-snippets.js).
+
+## Specialized Guides
+
+- **Hooks & UI Components**: Comprehensive list of `useAuth`, `useSignIn`, and pre-built Mantine components. See [hooks-and-components.md](references/hooks-and-components.md).
+- **Route Protection**: How to use `<Protect />`, `<SignedIn>`, and active route guards. See [route-protection.md](references/route-protection.md).
+- **Core Concepts**: Understanding B2C/B2B models and API key security. See [concepts.md](references/concepts.md).
+
+## Common Tasks
+
+### Checking Auth State
+
+Use `useAuth()` to access user data and authentication status.
+
+```jsx
+const { user, isAuthenticated, loading } = useAuth()
+```
+
+### Adding a Login Form
+
+Simply drop the `<SignIn />` component. Use `variant="modal"` if you want it in a popup.
+
+```jsx
+<SignIn />
+// or
+<SignIn variant="modal" opened={isOpen} onClose={() => setIsOpen(false)} />
+```
+
+### Protecting a Dashboard
+
+Wrap your sub-routes with `<Protect />`.
+
+```jsx
+<Route element={<Protect redirectTo="/login" />}>
+    <Route
+        path="/dashboard"
+        element={<Dashboard />}
+    />
+</Route>
+```

.agent/skills/riligar-dev-auth-react/assets/setup-snippets.js

@@ -0,0 +1,52 @@
+// Setup Snippets
+
+// 1. main.jsx / index.jsx setup
+export const authProviderSetup = `
+import { AuthProvider } from '@riligar/auth-react';
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <AuthProvider apiKey={import.meta.env.VITE_AUTH_API_KEY}>
+      <App />
+    </AuthProvider>
+  </React.StrictMode>
+);
+`
+
+// 2. Protected Routes setup
+export const protectedRoutesSnippet = `
+import { Protect, SignIn } from '@riligar/auth-react';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+function AppRoutes() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route path="/signin" element={<SignIn />} />
+        
+        <Route element={<Protect redirectTo="/signin" />}>
+          <Route path="/" element={<Dashboard />} />
+          <Route path="/profile" element={<Profile />} />
+        </Route>
+      </Routes>
+    </BrowserRouter>
+  );
+}
+`
+
+// 3. User State hook
+export const useAuthExample = `
+import { useAuth } from '@riligar/auth-react';
+
+function UserButton() {
+  const { user, isAuthenticated, signOut } = useAuth();
+  
+  if (!isAuthenticated) return null;
+  
+  return (
+    <button onClick={signOut}>
+      Log out {user.name}
+    </button>
+  );
+}
+`