@ivannxbt/ai-config 0.1.0

package/.agents/skills/entra-app-registration/references/troubleshooting.md

@@ -0,0 +1,269 @@
+# Troubleshooting Microsoft Entra App Registration
+
+This guide helps you diagnose and fix common issues with app registrations and authentication.
+
+## Table of Contents
+
+- [Authentication Errors](#authentication-errors)
+- [Token Issues](#token-issues)
+- [Permission Problems](#permission-problems)
+- [Redirect URI Issues](#redirect-uri-issues)
+- [Application Configuration](#application-configuration)
+- [Debugging Tools](#debugging-tools)
+
+## Authentication Errors
+
+### Redirect URI Mismatch
+
+**Error message:**
+```
+AADSTS50011: The redirect URI 'http://localhost:3000' specified in the request 
+does not match the redirect URIs configured for the application.
+```
+
+**Cause:** The redirect URI in your authentication request doesn't exactly match what's registered.
+
+**Solutions:**
+
+1. **Check exact match** (case-sensitive, trailing slash matters):
+   ```
+   Registered: https://myapp.com/callback
+   Request:    https://myapp.com/callback/  ❌ (trailing slash)
+   Request:    https://MyApp.com/callback   ❌ (case difference)
+   Request:    https://myapp.com/callback   ✅
+   ```
+
+2. **Add URI to app registration:**
+   ```bash
+   # Portal: Authentication → Add redirect URI
+   # CLI:
+   az ad app update --id $APP_ID \
+     --web-redirect-uris "http://localhost:3000" "https://myapp.com/callback"
+   ```
+
+3. **Check platform type:**
+   - Web URIs go in "Web" platform
+   - SPA URIs go in "Single-page application"
+   - Desktop/mobile URIs go in "Public client/native"
+
+### Invalid Client Secret
+
+**Error message:**
+```
+AADSTS7000215: Invalid client secret provided. 
+Ensure the secret being sent in the request is the client secret value, not the client secret ID.
+```
+
+**Causes:**
+- Client secret expired
+- Wrong secret value (copied secret ID instead of value)
+- Secret doesn't match app registration
+
+**Solutions:**
+
+1. **Check expiration:**
+   ```bash
+   az ad app credential list --id $APP_ID
+   ```
+2. **Create new secret:**
+   ```bash
+   az ad app credential reset --id $APP_ID --years 1
+   ```
+   Copy the `password` value (not the `keyId`)
+
+### User Consent Required
+
+**Error message:**
+```
+AADSTS65001: The user or administrator has not consented to use the application
+```
+
+**Causes:**
+- Application permissions require admin consent
+- User hasn't consented to delegated permissions
+- Consent was revoked
+
+**Solutions:**
+
+1. **Grant admin consent (if admin):**
+   ```bash
+   az ad app permission admin-consent --id $APP_ID
+   ```
+
+2. **Request user consent (interactive flow):**
+   This requires the client app to have access to UI such as browser, terminal window, etc. Follow the best practices of your client app to implement the interactive flow.
+
+3. **Check API permissions in portal:**
+   - Ensure permissions are added
+   - Look for green checkmarks (granted)
+   - Yellow warning means not granted
+
+### Grant Declined
+
+**Error message:**
+```
+AADSTS70000: The request was denied because one or more permissions have been declined
+```
+
+**Cause:** User or admin explicitly denied consent.
+
+**Solutions:**
+
+1. **Re-request with explanation:**
+   - Explain why permissions are needed
+   - Request only necessary permissions
+
+2. **Check if admin consent is required:**
+   - Some organizations disable user consent
+   - Contact your admin to grant consent
+
+3. **Reduce permission scope:**
+   - Request minimal permissions initially
+   - Use incremental consent for additional features
+
+### Application Not Found
+
+**Error message:**
+```
+AADSTS700016: Application with identifier '{app-id}' was not found in the directory
+```
+
+**Causes:**
+- Wrong application ID
+- Wrong tenant ID
+- Service principal not created
+- App in different tenant
+
+**Solutions:**
+
+1. **Verify application ID:**
+   ```bash
+   az ad app list --display-name "MyApp" --query "[].{Name:displayName, AppId:appId}"
+   ```
+
+2. **Verify tenant ID:**
+   ```bash
+   az account show --query tenantId -o tsv
+   ```
+
+### Application Doesn't have a Service Principal
+
+**Error message:**
+```
+The app is trying to access a service 'your_app_id'(your_app_name) that your organization 'your_tenant_id' lacks a service principal for
+```
+
+**Causes:**
+- Your tenant is not configured to automatically provision the service principal for app registrations in it.
+
+**Solutions:**
+
+1. **Create service principal:**
+   ```bash
+   az ad sp create --id $APP_ID
+   ```
+
+### Missing Required Field
+
+**Error message:**
+```
+AADSTS90014: The required field 'client_id' is missing from the request
+```
+
+This can happen if the client you are using isn't compatible with Entra. Consult the owner of your client app to see if it supports Entra.
+
+## Token Issues
+
+Unless the the access token is encrypted, you can decode and view its claims securely at https://jwt.ms. **Don't** use any other website to decode an access token. Compare the claims in the token with the app registration's configuration to identify issues.
+
+## Debugging Tools
+
+### JWT Token Decoder
+
+**Tool:** https://jwt.ms
+
+**How to use:**
+1. Copy your access token
+2. Paste into jwt.ms
+3. Review claims:
+   - `aud` - Audience (should match your API)
+   - `iss` - Issuer (should be login.microsoftonline.com)
+   - `scp` - Delegated permissions
+   - `roles` - Application permissions
+   - `exp` - Expiration timestamp
+   - `oid` - User object ID
+
+---
+
+### Fiddler
+
+**Use for:** Inspecting HTTP requests/responses
+
+**What to check:**
+- Authorization header format: `Bearer {token}`
+- Token is being sent
+- Response status codes and error messages
+
+### Entra Sign-in Logs
+
+**Access:** Azure Portal → Microsoft Entra ID → Sign-in logs
+
+**What to check:**
+- Failed sign-in attempts
+- Error codes and messages
+- User consent status
+- Conditional Access policy failures
+
+## Common Error Codes Reference
+
+| Error Code | Meaning | Common Cause |
+|------------|---------|--------------|
+| AADSTS50011 | Redirect URI mismatch | URI not registered or doesn't match |
+| AADSTS50020 | Invalid tenant | Wrong tenant in authority URL |
+| AADSTS50034 | User not found | User doesn't exist in tenant |
+| AADSTS50053 | Account locked | Too many failed attempts |
+| AADSTS50055 | Password expired | User needs to reset password |
+| AADSTS50057 | Account disabled | User account disabled |
+| AADSTS50058 | Silent sign-in failed | Interactive auth required |
+| AADSTS50059 | Tenant not found | Invalid tenant ID |
+| AADSTS65001 | Consent required | User/admin hasn't consented |
+| AADSTS70000 | Grant declined | User denied consent |
+| AADSTS70001 | App disabled | App registration disabled |
+| AADSTS700016 | App not found | Invalid app ID or wrong tenant |
+| AADSTS7000215 | Invalid client secret | Wrong/expired secret |
+| AADSTS90014 | Missing field | Required parameter not sent |
+| AADSTS90072 | Consent needed | Admin consent required |
+
+## Best Practices for Troubleshooting
+
+### Systematic Approach
+
+1. **Collect information:**
+   - Exact error message and code
+   - When it started happening
+   - What changed recently
+   - Environment (dev/test/prod)
+
+2. **Check basics first:**
+   - App ID and tenant ID correct
+   - Permissions added and consented
+   - Redirect URIs configured
+   - Secrets/certificates valid
+
+3. **Use debugging tools:**
+   - Decode tokens (jwt.ms)
+   - Check sign-in logs
+   - Enable MSAL logging
+   - Use network inspector
+
+4. **Test incrementally:**
+   - Test with minimal permissions
+   - Add permissions one at a time
+   - Test different flows separately
+
+## Getting Help
+
+### Microsoft Resources
+
+- [Microsoft Q&A](https://learn.microsoft.com/answers/)
+- [Microsoft Identity Platform Documentation](https://learn.microsoft.com/entra/identity-platform/)

package/.agents/skills/expo-api-routes/SKILL.md

@@ -0,0 +1,368 @@
+---
+name: expo-api-routes
+description: Guidelines for creating API routes in Expo Router with EAS Hosting
+version: 1.0.0
+license: MIT
+---
+
+## When to Use API Routes
+
+Use API routes when you need:
+
+- **Server-side secrets** — API keys, database credentials, or tokens that must never reach the client
+- **Database operations** — Direct database queries that shouldn't be exposed
+- **Third-party API proxies** — Hide API keys when calling external services (OpenAI, Stripe, etc.)
+- **Server-side validation** — Validate data before database writes
+- **Webhook endpoints** — Receive callbacks from services like Stripe or GitHub
+- **Rate limiting** — Control access at the server level
+- **Heavy computation** — Offload processing that would be slow on mobile
+
+## When NOT to Use API Routes
+
+Avoid API routes when:
+
+- **Data is already public** — Use direct fetch to public APIs instead
+- **No secrets required** — Static data or client-safe operations
+- **Real-time updates needed** — Use WebSockets or services like Supabase Realtime
+- **Simple CRUD** — Consider Firebase, Supabase, or Convex for managed backends
+- **File uploads** — Use direct-to-storage uploads (S3 presigned URLs, Cloudflare R2)
+- **Authentication only** — Use Clerk, Auth0, or Firebase Auth instead
+
+## File Structure
+
+API routes live in the `app` directory with `+api.ts` suffix:
+
+```
+app/
+  api/
+    hello+api.ts          → GET /api/hello
+    users+api.ts          → /api/users
+    users/[id]+api.ts     → /api/users/:id
+  (tabs)/
+    index.tsx
+```
+
+## Basic API Route
+
+```ts
+// app/api/hello+api.ts
+export function GET(request: Request) {
+  return Response.json({ message: "Hello from Expo!" });
+}
+```
+
+## HTTP Methods
+
+Export named functions for each HTTP method:
+
+```ts
+// app/api/items+api.ts
+export function GET(request: Request) {
+  return Response.json({ items: [] });
+}
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  return Response.json({ created: body }, { status: 201 });
+}
+
+export async function PUT(request: Request) {
+  const body = await request.json();
+  return Response.json({ updated: body });
+}
+
+export async function DELETE(request: Request) {
+  return new Response(null, { status: 204 });
+}
+```
+
+## Dynamic Routes
+
+```ts
+// app/api/users/[id]+api.ts
+export function GET(request: Request, { id }: { id: string }) {
+  return Response.json({ userId: id });
+}
+```
+
+## Request Handling
+
+### Query Parameters
+
+```ts
+export function GET(request: Request) {
+  const url = new URL(request.url);
+  const page = url.searchParams.get("page") ?? "1";
+  const limit = url.searchParams.get("limit") ?? "10";
+
+  return Response.json({ page, limit });
+}
+```
+
+### Headers
+
+```ts
+export function GET(request: Request) {
+  const auth = request.headers.get("Authorization");
+
+  if (!auth) {
+    return Response.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  return Response.json({ authenticated: true });
+}
+```
+
+### JSON Body
+
+```ts
+export async function POST(request: Request) {
+  const { email, password } = await request.json();
+
+  if (!email || !password) {
+    return Response.json({ error: "Missing fields" }, { status: 400 });
+  }
+
+  return Response.json({ success: true });
+}
+```
+
+## Environment Variables
+
+Use `process.env` for server-side secrets:
+
+```ts
+// app/api/ai+api.ts
+export async function POST(request: Request) {
+  const { prompt } = await request.json();
+
+  const response = await fetch("https://api.openai.com/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+    },
+    body: JSON.stringify({
+      model: "gpt-4",
+      messages: [{ role: "user", content: prompt }],
+    }),
+  });
+
+  const data = await response.json();
+  return Response.json(data);
+}
+```
+
+Set environment variables:
+
+- **Local**: Create `.env` file (never commit)
+- **EAS Hosting**: Use `eas env:create` or Expo dashboard
+
+## CORS Headers
+
+Add CORS for web clients:
+
+```ts
+const corsHeaders = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type, Authorization",
+};
+
+export function OPTIONS() {
+  return new Response(null, { headers: corsHeaders });
+}
+
+export function GET() {
+  return Response.json({ data: "value" }, { headers: corsHeaders });
+}
+```
+
+## Error Handling
+
+```ts
+export async function POST(request: Request) {
+  try {
+    const body = await request.json();
+    // Process...
+    return Response.json({ success: true });
+  } catch (error) {
+    console.error("API error:", error);
+    return Response.json({ error: "Internal server error" }, { status: 500 });
+  }
+}
+```
+
+## Testing Locally
+
+Start the development server with API routes:
+
+```bash
+npx expo serve
+```
+
+This starts a local server at `http://localhost:8081` with full API route support.
+
+Test with curl:
+
+```bash
+curl http://localhost:8081/api/hello
+curl -X POST http://localhost:8081/api/users -H "Content-Type: application/json" -d '{"name":"Test"}'
+```
+
+## Deployment to EAS Hosting
+
+### Prerequisites
+
+```bash
+npm install -g eas-cli
+eas login
+```
+
+### Deploy
+
+```bash
+eas deploy
+```
+
+This builds and deploys your API routes to EAS Hosting (Cloudflare Workers).
+
+### Environment Variables for Production
+
+```bash
+# Create a secret
+eas env:create --name OPENAI_API_KEY --value sk-xxx --environment production
+
+# Or use the Expo dashboard
+```
+
+### Custom Domain
+
+Configure in `eas.json` or Expo dashboard.
+
+## EAS Hosting Runtime (Cloudflare Workers)
+
+API routes run on Cloudflare Workers. Key limitations:
+
+### Missing/Limited APIs
+
+- **No Node.js filesystem** — `fs` module unavailable
+- **No native Node modules** — Use Web APIs or polyfills
+- **Limited execution time** — 30 second timeout for CPU-intensive tasks
+- **No persistent connections** — WebSockets require Durable Objects
+- **fetch is available** — Use standard fetch for HTTP requests
+
+### Use Web APIs Instead
+
+```ts
+// Use Web Crypto instead of Node crypto
+const hash = await crypto.subtle.digest(
+  "SHA-256",
+  new TextEncoder().encode("data")
+);
+
+// Use fetch instead of node-fetch
+const response = await fetch("https://api.example.com");
+
+// Use Response/Request (already available)
+return new Response(JSON.stringify(data), {
+  headers: { "Content-Type": "application/json" },
+});
+```
+
+### Database Options
+
+Since filesystem is unavailable, use cloud databases:
+
+- **Cloudflare D1** — SQLite at the edge
+- **Turso** — Distributed SQLite
+- **PlanetScale** — Serverless MySQL
+- **Supabase** — Postgres with REST API
+- **Neon** — Serverless Postgres
+
+Example with Turso:
+
+```ts
+// app/api/users+api.ts
+import { createClient } from "@libsql/client/web";
+
+const db = createClient({
+  url: process.env.TURSO_URL!,
+  authToken: process.env.TURSO_AUTH_TOKEN!,
+});
+
+export async function GET() {
+  const result = await db.execute("SELECT * FROM users");
+  return Response.json(result.rows);
+}
+```
+
+## Calling API Routes from Client
+
+```ts
+// From React Native components
+const response = await fetch("/api/hello");
+const data = await response.json();
+
+// With body
+const response = await fetch("/api/users", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ name: "John" }),
+});
+```
+
+## Common Patterns
+
+### Authentication Middleware
+
+```ts
+// utils/auth.ts
+export async function requireAuth(request: Request) {
+  const token = request.headers.get("Authorization")?.replace("Bearer ", "");
+
+  if (!token) {
+    throw new Response(JSON.stringify({ error: "Unauthorized" }), {
+      status: 401,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  // Verify token...
+  return { userId: "123" };
+}
+
+// app/api/protected+api.ts
+import { requireAuth } from "../../utils/auth";
+
+export async function GET(request: Request) {
+  const { userId } = await requireAuth(request);
+  return Response.json({ userId });
+}
+```
+
+### Proxy External API
+
+```ts
+// app/api/weather+api.ts
+export async function GET(request: Request) {
+  const url = new URL(request.url);
+  const city = url.searchParams.get("city");
+
+  const response = await fetch(
+    `https://api.weather.com/v1/current?city=${city}&key=${process.env.WEATHER_API_KEY}`
+  );
+
+  return Response.json(await response.json());
+}
+```
+
+## Rules
+
+- NEVER expose API keys or secrets in client code
+- ALWAYS validate and sanitize user input
+- Use proper HTTP status codes (200, 201, 400, 401, 404, 500)
+- Handle errors gracefully with try/catch
+- Keep API routes focused — one responsibility per endpoint
+- Use TypeScript for type safety
+- Log errors server-side for debugging