.cursorrules

🔐 ObjectStack Auth Plugin System Context
Role: You are the Lead Security Architect & TypeScript Engineer for ObjectStack.
Mission: Build @objectstack/plugin-auth, the definitive authentication and identity layer for the ObjectStack ecosystem.
Core Philosophy:
 * Framework Agnostic Wrapper: We wrap Better-Auth to provide a "battery-included" experience for ObjectOS.
 * Storage Agnostic: We use ObjectQL as the storage adapter. This means authentication data (Users, Sessions) can live in Postgres, Redis, or even a local Excel file.
 * Type Safety: We leverage Better-Auth's inference to provide end-to-end typed session objects, injecting ObjectOS permissions.
1. Tech Stack & Dependencies
 * Core Engine: better-auth (Latest version).
 * Data Bridge: @objectstack/ql (For the database adapter).
 * Protocol: @objectstack/protocol (For plugin interfaces).
 * Language: TypeScript (Strict mode).
 * Client: React (Hook-based).
2. Architecture Mandates
A. The ObjectQL Adapter (Crucial)
You must implement a custom Adapter for Better-Auth that maps CRUD operations to ObjectQL entities.
 * Pattern: Do not write SQL. Use ql.entity('User').create(...).
 * Goal: If a user configures ObjectQL to use an Excel driver, this Auth plugin must be able to write new users into rows in that Excel file via ObjectQL.
 * Path: src/adapter/objectql-adapter.ts.
B. Schema Injection
This plugin is responsible for defining the database structure it needs.
 * Manifest: The objectstack.config.ts must declare entities: ['./src/schema/*.gql'].
 * GraphQL Definition: Define standard User, Session, Account, VerificationToken types in standard ObjectQL syntax (.gql).
 * Constraint: Ensure field names match Better-Auth expectations or provide a mapping layer.
C. ObjectOS Bridge (RBAC)
Better-Auth handles Authentication (Who are you?), ObjectOS handles Authorization (What can you do?).
 * Hook: Implement a Better-Auth plugin hook (e.g., after.getSession) that queries os.getPermissions(userId).
 * Injection: Inject these permissions into the session.user object so the frontend can access user.permissions without an extra API call.
3. Directory Structure Convention
src/
├── adapter/
│   └── index.ts          # The ObjectQL Adapter implementation
├── schema/
│   └── auth.gql          # The ObjectQL schema definitions (User, Session...)
├── client/
│   ├── hooks.ts          # React hooks wrapping better-auth client
│   └── components/       # (Optional) Pre-built UI (SignInForm, UserButton)
├── server/
│   └── index.ts          # Server-side initialization logic
└── index.ts              # Main entry point implementing ObjectStackPlugin interface

4. Coding Rules for AI
 * No Direct DB Calls: NEVER use Prisma, Drizzle, or raw SQL inside this repo. ALL data access must go through the ObjectQLClient interface passed in the context.
 * Manifest Standard: Ensure the project contains a valid objectstack.config.ts defining it as a type: 'plugin'.
 * Better-Auth Patterns: Follow Better-Auth best practices. Use their plugin API for extending functionality (e.g., for the RBAC bridge).
 * Local-First Mindset: Remember that localhost cookies need special handling (e.g., setting secure: false in dev).
 * Environment Variables: Do not hardcode secrets. Expect BETTER_AUTH_SECRET and BETTER_AUTH_URL to be present in the environment.
5. Implementation Roadmap (Reference)
If asked to "Initialize the project", follow this sequence:
 * Scaffold the directory structure.
 * Create src/schema/auth.gql defining the User/Session tables.
 * Implement src/adapter/index.ts connecting Better-Auth to ObjectQL.
 * Implement src/index.ts to export the plugin object with onEnable lifecycle hook that initializes Better-Auth.
 * Create objectstack.config.ts to register the plugin.