sonamu 0.10.7 → 0.10.8

package/src/skills/sonamu-auth/SKILL.md

@@ -1,327 +0,0 @@
----
-name: sonamu-auth
-description: Sets up better-auth in a Sonamu project. Use when running auth generate, applying Guards to an endpoint, reading the session from Context, adding an auth plugin, or migrating User.id to a string primary key. Covers the generated User/Account/Session/Verification entities, guard configuration, and the admin, organization, 2fa, and passkey plugin wrappers.
----
-
-# better-auth Authentication System
-
-**Plugin wrappers** (admin, organization, 2fa, passkey and 6 more, plus snake_case mapping):
-see `references/plugins.md`.
-
-**Changing User.id to a string PK** for external auth: see `references/user-id-migration.md`.
-
-> This document is based on actual Sonamu source code.
-
-## Automatic Entity Generation
-
-**Source code:**
-
-- CLI: `modules/sonamu/src/bin/cli.ts` (auth_generate function)
-- Generation logic: `modules/sonamu/src/auth/auth-generator.ts`
-- Entity definitions: `modules/sonamu/src/auth/better-auth-entities.ts`
-
-**IMPORTANT: Before running generate, you must confirm with the user which plugins they want to use.**
-
-Plugin selection happens at generate time and can be added later, but it is best to specify them from the start.
-Refer to `references/plugins.md` for the list of supported plugins and their purposes.
-
-### Plugin Confirmation Flow
-
-**[Step 1] Confirm before generate (required)**
-
-> "What authentication method do you plan to use? Please confirm whether you need additional plugins beyond the default email/social login.
-> Supported plugins: `admin`, `organization`, `2fa`, `username`, `phone-number`, `api-key`, `jwt`, `passkey`, `sso`, `anonymous`"
-
-**[Step 1-A] If the user responds "I'll do it later":**
-
-Provide the following guidance and proceed with generate without plugins:
-
-> "Understood. It's best to add plugins before the initial migration is run.
-> I'll confirm again before the migration."
-
-And remember the **`plugins_deferred: true`** state.
-
-**[Step 2] Re-confirm just before migrate run (CRITICAL — must be done if `plugins_deferred: true`)**
-
-Before running the migration, always confirm again:
-
-> "You are about to run a migration. This is the best time to add plugins.
-> If you want to add any plugins, please let me know. Otherwise, we'll proceed as-is.
-> Supported plugins: `admin`, `organization`, `2fa`, `username`, `phone-number`, `api-key`, `jwt`, `passkey`, `sso`, `anonymous`"
-
-- If adding plugins: run `pnpm sonamu auth generate --plugins <list>` then proceed with migrate
-- If none: proceed with migrate as-is
-
-```bash
-# Basic entities only, no plugins
-pnpm sonamu auth generate
-
-# With plugins
-pnpm sonamu auth generate --plugins admin,2fa,username
-```
-
-The 4 entities generated (`betterAuthV1` array):
-
-| Entity       | Table         | Key fields                             |
-| ------------ | ------------- | -------------------------------------- |
-| User         | users         | id, name, email, email_verified, image |
-| Session      | sessions      | id, token, expires_at, user_id         |
-| Account      | accounts      | id, provider_id, access_token, user_id |
-| Verification | verifications | id, identifier, value, expires_at      |
-
-**How it works:**
-
-- If the entity does not exist, it is created fresh
-- If the entity already exists, only missing fields are added
-- Fields with changed types are updated automatically
-- Uses snake_case column names (better-auth uses camelCase)
-
-## Adding Fixture Companions (`auth add-companions`)
-
-After running `auth generate`, run this command once to add `fixtureCompanions` to the `id` prop of better-auth entities (User, etc.).
-
-```bash
-pnpm sonamu auth add-companions
-```
-
-**Purpose:** Enables automatic Account fixture creation when generating User fixtures. Without this, fixture gen creates User records without a corresponding credentials Account, breaking auth-dependent tests.
-
-**What it does:**
-- Reads `fixtureCompanions` from the `betterAuthV1` definitions
-- Adds them to the existing entity.json `id` prop's cone
-- Skips if `fixtureCompanions` already exists
-
-**When to run:** Once, after `auth generate`, before running `fixture gen` for the first time. Re-running is safe (idempotent).
-
-## Field Mapping (Applied Automatically)
-
-**Source code:** `modules/sonamu/src/auth/better-auth-entities.ts` (BASE_FIELD_MAPPINGS)
-
-| better-auth     | Sonamu           |
-| --------------- | ---------------- |
-| `emailVerified` | `email_verified` |
-| `createdAt`     | `created_at`     |
-| `userId`        | `user_id`        |
-| `expiresAt`     | `expires_at`     |
-
-## Config Setup
-
-**Source code:** `modules/sonamu/src/api/config.ts` (SonamuServerOptions.auth)
-
-```typescript
-// sonamu.config.ts
-server: {
-  auth: {
-    emailAndPassword: { enabled: true },
-    // To add social login:
-    // socialProviders: {
-    //   google: {
-    //     clientId: process.env.GOOGLE_CLIENT_ID!,
-    //     clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
-    //   },
-    // },
-  },
-}
-```
-
-## API Endpoints (Auto-registered)
-
-| Path                      | Method | Description |
-| ------------------------- | ------ | ----------- |
-| `/api/auth/sign-up/email` | POST   | Sign up     |
-| `/api/auth/sign-in/email` | POST   | Sign in     |
-| `/api/auth/sign-out`      | POST   | Sign out    |
-| `/api/auth/get-session`   | GET    | Get session |
-
-## Accessing user/session from Context
-
-**Source code:** `modules/sonamu/src/api/context.ts` (AuthContext type definition)
-
-```typescript
-import { Sonamu } from "sonamu";
-
-@api({ httpMethod: "GET", guards: ["user"] })
-async me(): Promise<UserSubsetA | null> {
-  const { user, session } = Sonamu.getContext();
-
-  if (!user) return null;
-
-  // user.id, user.email, user.name, etc. are accessible
-  return this.findById("A", user.id);
-}
-```
-
-## Using Guards
-
-**Source code:** `modules/sonamu/src/api/decorators.ts` (GuardKeys interface)
-
-### Built-in Guards
-
-Sonamu provides 3 default guards:
-
-- `query`: allows all users (including unauthenticated)
-- `user`: allows only authenticated users
-- `admin`: allows only users with admin privileges
-
-```typescript
-// Login required
-@api({ httpMethod: "GET", guards: ["user"] })
-async getProfile() {
-  const { user } = Sonamu.getContext();
-  return { userId: user.id };
-}
-
-// Admin only (requires adding a role field to the User entity)
-@api({ httpMethod: "DELETE", guards: ["admin"] })
-async deleteUser(id: string) {
-  // Only admins can execute
-}
-```
-
-### Adding Custom Guards
-
-If additional permissions beyond the default guards are needed, extend the `GuardKeys` interface in `src/typings/sonamu.d.ts`.
-
-**File location:** `src/typings/sonamu.d.ts`
-
-```typescript
-import {} from "sonamu";
-
-declare module "sonamu" {
-  export interface GuardKeys {
-    query: true;
-    user: true;
-    admin: true;
-    // Custom guards
-    manager: true;
-    evaluator: true;
-    superadmin: true;
-  }
-}
-```
-
-You can now use the added guards in the `@api` decorator:
-
-```typescript
-// Manager permission
-@api({ httpMethod: "GET", guards: ["manager"] })
-async getReports() {
-  // Only managers can execute
-}
-
-// Allow multiple guards simultaneously
-@api({ httpMethod: "POST", guards: ["admin", "manager"] })
-async createReport() {
-  // Requires admin or manager permission
-}
-```
-
-## Implementing guardHandler
-
-**Source code:** `modules/sonamu/src/api/config.ts` (SonamuFastifyConfig.guardHandler)
-
-```typescript
-import { Sonamu } from "sonamu";
-
-// sonamu.config.ts
-apiConfig: {
-  guardHandler: (guard, request, api) => {
-    const { user } = Sonamu.getContext();
-
-    switch (guard) {
-      case "user":
-        if (!user) {
-          throw new Error("Login is required");
-        }
-        break;
-
-      case "admin":
-        // Requires adding a role field to the User entity
-        if (!user || (user as any).role !== "admin") {
-          throw new Error("Only admins can access this");
-        }
-        break;
-
-      case "manager":
-        // Custom guard: manager permission
-        if (!user || !["admin", "manager"].includes((user as any).role)) {
-          throw new Error("Manager permission is required");
-        }
-        break;
-
-      case "evaluator":
-        // Custom guard: evaluator permission
-        if (!user || !["admin", "evaluator"].includes((user as any).role)) {
-          throw new Error("Evaluator permission is required");
-        }
-        break;
-
-      case "query":
-        // Allow all users
-        break;
-    }
-  },
-}
-```
-
-## Adding role to the User Entity (Role-based Authorization)
-
-**Note:** The default User entity from better-auth (`modules/sonamu/src/auth/better-auth-entities.ts`) does not have a `role` field.
-
-If role-based authorization is needed, add it directly to the User entity:
-
-```json
-// src/application/sonamu.entity.json
-{
-  "id": "User",
-  "props": [
-    // ... existing fields
-    {
-      "name": "role",
-      "type": "string",
-      "default": "user",
-      "desc": "User role (user, admin, manager)"
-    }
-  ]
-}
-```
-
-Adding an enum:
-
-```json
-{
-  "enums": {
-    "UserRole": {
-      "user": "Regular user",
-      "admin": "Administrator",
-      "manager": "Manager"
-    }
-  }
-}
-```
-
-## Checklist
-
-After setup, verify:
-
-- [ ] **[Before generate] Confirm with user whether plugins are needed**
-  - If "later" → remember `plugins_deferred: true`, guide on optimal timing
-- [ ] Run `pnpm sonamu auth generate [--plugins ...]`
-- [ ] **[Before migrate] Re-confirm plugins if `plugins_deferred: true`** (CRITICAL)
-- [ ] Create and apply migration
-- [ ] Configure `server.auth` in `sonamu.config.ts`
-- [ ] Implement `guardHandler`
-- [ ] Confirm user/session access from Context
-- [ ] Add role to User entity if role-based authorization is needed
-
-## Reference
-
-**Skills documentation:**
-
-- Detailed configuration: "server.auth details" section in `sonamu-config`
-- Context API: "Context access" section in `sonamu-api`
-
-**Official documentation:**
-
-- Korean: `modules/docs/ko/api-development/authentication/setup.mdx`
-- English: `modules/docs/en/api-development/authentication/setup.mdx`

package/src/skills/sonamu-auth/references/plugins.md

@@ -1,310 +0,0 @@
-# better-auth Plugin Guide
-
-Sonamu wraps better-auth plugins with snake_case schema mapping.
-Use the `auth generate --plugins` command to auto-generate plugin entities.
-
-**Source code:**
-
-- Wrappers: `modules/sonamu/src/auth/plugins/wrappers/`
-- Entity definitions: `modules/sonamu/src/auth/plugins/entity-definitions/`
-- Generator: `modules/sonamu/src/auth/auth-generator.ts`
-
----
-
-## Supported Plugins
-
-| Plugin ID      | Wrapper function | Package                 | Purpose                                               |
-| -------------- | ---------------- | ----------------------- | ----------------------------------------------------- |
-| `admin`        | `admin()`        | `better-auth/plugins`   | Admin features, user ban/unban, session impersonation |
-| `organization` | `organization()` | `better-auth/plugins`   | Organization, team, member, and invitation management |
-| `2fa`          | `twoFactor()`    | `better-auth/plugins`   | TOTP-based two-factor authentication                  |
-| `username`     | `username()`     | `better-auth/plugins`   | Username-based authentication                         |
-| `phone-number` | `phoneNumber()`  | `better-auth/plugins`   | Phone number authentication                           |
-| `api-key`      | `apiKey()`       | `@better-auth/api-key`  | API key issuance/management, rate limiting            |
-| `jwt`          | `jwt()`          | `better-auth/plugins`   | JWT tokens + JWKS key management                      |
-| `passkey`      | `passkey()`      | `@better-auth/passkey`  | WebAuthn/Passkey authentication                       |
-| `sso`          | `sso()`          | `@better-auth/sso`      | OIDC/SAML SSO integration                             |
-| `anonymous`    | `anonymous()`    | `better-auth/plugins`   | Anonymous user support                                |
-
----
-
-## CLI Usage
-
-```bash
-# Base entities only (User, Session, Account, Verification)
-pnpm sonamu auth generate
-
-# With plugins
-pnpm sonamu auth generate --plugins admin,organization
-
-# Multiple plugins
-pnpm sonamu auth generate --plugins admin,2fa,phone-number,username
-```
-
-### How It Works
-
-1. **Base entities** are created/updated (User, Session, Account, Verification)
-2. **Per-plugin** processing:
-   - `entities`: creates new tables (e.g. Organization → organizations, members, invitations, teams, team_members)
-   - `additionalProps`: adds fields to existing entities (e.g. admin → adds ban_reason, ban_expires to User)
-   - `additionalIndexes`: adds indexes to existing entities
-3. Entities that already exist have **only missing fields added**; existing fields are preserved
-
----
-
-## Wrapper Usage (sonamu.config.ts)
-
-Using Sonamu wrappers automatically applies snake_case schema mapping.
-
-```typescript
-// sonamu.config.ts
-import { admin, organization, twoFactor, username } from "sonamu/auth/plugins";
-
-export default defineConfig({
-  server: {
-    auth: {
-      emailAndPassword: { enabled: true },
-      plugins: [admin(), organization(), twoFactor(), username()],
-    },
-  },
-});
-```
-
-**CRITICAL: Do not import directly from `better-auth/plugins`.** You must go through the Sonamu wrapper for snake_case mapping to apply.
-
-```typescript
-// WRONG - snake_case mapping not applied
-import { admin } from "better-auth/plugins";
-
-// CORRECT - Sonamu wrapper
-import { admin } from "sonamu/auth/plugins";
-```
-
----
-
-## Per-Plugin Details
-
-### admin
-
-**Additional entities:** None
-**Fields added to User:** `role`, `banned`, `ban_reason`, `ban_expires`
-**Fields added to Session:** `impersonated_by`
-
-```typescript
-import { admin } from "sonamu/auth/plugins";
-
-// Basic usage
-admin();
-
-// Customize options (schema mapping is automatically merged)
-admin({ defaultRole: "user" });
-```
-
-Schema mapping:
-
-- `banReason` → `ban_reason`
-- `banExpires` → `ban_expires`
-- `impersonatedBy` → `impersonated_by`
-
-### organization
-
-**Additional entities:** Organization, Member, Invitation, Team, TeamMember
-**Fields added to Session:** `active_organization_id`, `active_team_id`
-
-```typescript
-import { organization } from "sonamu/auth/plugins";
-
-organization();
-```
-
-Schema mapping:
-
-- All tables: `createdAt` → `created_at`
-- Member: `userId` → `user_id`, `organizationId` → `organization_id`
-- Invitation: `inviterId` → `inviter_id`, `organizationId` → `organization_id`, `teamId` → `team_id`, `expiresAt` → `expires_at`
-- Team: `organizationId` → `organization_id`, `updatedAt` → `updated_at`
-- TeamMember: `teamId` → `team_id`, `userId` → `user_id`
-- Session: `activeOrganizationId` → `active_organization_id`, `activeTeamId` → `active_team_id`
-
-### 2fa (twoFactor)
-
-**Additional entities:** TwoFactor
-**Fields added to User:** `two_factor_enabled`
-
-```typescript
-import { twoFactor } from "sonamu/auth/plugins";
-
-twoFactor();
-```
-
-Schema mapping:
-
-- User: `twoFactorEnabled` → `two_factor_enabled`
-- TwoFactor: `userId` → `user_id`, `backupCodes` → `backup_codes`
-
-### username
-
-**Fields added to User:** `display_username`
-
-```typescript
-import { username } from "sonamu/auth/plugins";
-
-username();
-```
-
-Schema mapping:
-
-- `displayUsername` → `display_username`
-
-### phone-number
-
-**Fields added to User:** `phone_number`, `phone_number_verified`
-
-```typescript
-import { phoneNumber } from "sonamu/auth/plugins";
-
-phoneNumber({
-  sendOTP: async ({ phoneNumber, otp }) => {
-    /* send SMS */
-  },
-});
-```
-
-Schema mapping:
-
-- `phoneNumber` → `phone_number`
-- `phoneNumberVerified` → `phone_number_verified`
-
-### api-key
-
-**Additional entities:** ApiKey (table: `api_keys`)
-**Package:** `@better-auth/api-key` (must be installed separately)
-
-```bash
-pnpm add @better-auth/api-key
-```
-
-```typescript
-import { apiKey } from "sonamu/auth/plugins";
-
-apiKey();
-```
-
-Schema mapping:
-
-- `referenceId` → `reference_id`, `configId` → `config_id`
-- `lastRequest` → `last_request`, `requestCount` → `request_count`
-- `rateLimitEnabled` → `rate_limit_enabled`, `rateLimitTimeWindow` → `rate_limit_time_window`
-- `rateLimitMax` → `rate_limit_max`, `refillInterval` → `refill_interval`
-- `refillAmount` → `refill_amount`, `lastRefillAt` → `last_refill_at`
-- `expiresAt` → `expires_at`, `createdAt` → `created_at`, `updatedAt` → `updated_at`
-
-Note: v1.5.0에서 `userId`가 `referenceId`로 변경됨. `referenceId`는 user 또는 organization을 참조하는 polymorphic ID.
-
-### jwt
-
-**Additional entities:** Jwks (table: `jwks`)
-
-```typescript
-import { jwt } from "sonamu/auth/plugins";
-
-jwt();
-```
-
-Schema mapping:
-
-- `publicKey` → `public_key`, `privateKey` → `private_key`
-- `createdAt` → `created_at`, `expiresAt` → `expires_at`
-
-### passkey
-
-**Additional entities:** Passkey (table: `passkeys`)
-**Package:** `@better-auth/passkey` (must be installed separately)
-
-```bash
-pnpm add @better-auth/passkey
-```
-
-```typescript
-import { passkey } from "sonamu/auth/plugins";
-
-passkey({ rpID: "localhost", rpName: "My App" });
-```
-
-Schema mapping:
-
-- `publicKey` → `public_key`, `userId` → `user_id`, `credentialID` → `credential_id`
-- `deviceType` → `device_type`, `backedUp` → `backed_up`, `createdAt` → `created_at`
-
-### sso
-
-**Package:** `@better-auth/sso` (must be installed separately)
-
-```bash
-pnpm add @better-auth/sso
-```
-
-```typescript
-import { sso } from "sonamu/auth/plugins";
-
-sso();
-```
-
-Table: `sso_providers`
-Schema mapping:
-
-- `oidcConfig` → `oidc_config`, `samlConfig` → `saml_config`
-- `userId` → `user_id`, `providerId` → `provider_id`, `organizationId` → `organization_id`
-
-### anonymous
-
-**Fields added to User:** `is_anonymous`
-
-```typescript
-import { anonymous } from "sonamu/auth/plugins";
-
-anonymous();
-```
-
-Schema mapping:
-
-- `isAnonymous` → `is_anonymous`
-
----
-
-## Custom Schema Options
-
-Passing additional options to a wrapper function automatically merges them with Sonamu's default mapping:
-
-```typescript
-admin({
-  defaultRole: "user",
-  schema: {
-    user: {
-      fields: {
-        customField: "custom_field", // additional mapping
-      },
-    },
-  },
-});
-```
-
-Internally, `merge(ADMIN_SCHEMA, options.schema)` is executed to preserve the Sonamu mapping.
-
----
-
-## Steps After Adding a Plugin
-
-1. `pnpm sonamu auth generate --plugins <plugin list>`
-2. Confirm generated entities in Sonamu UI
-3. Run migration with `pnpm sonamu migrate run`
-4. Add wrapper functions to `sonamu.config.ts`
-5. If needed, add plugin-specific permission logic to `guardHandler`
-
----
-
-## References
-
-- **Basic auth configuration:** `sonamu-auth`
-- **Changing PK type (better-auth → string PK):** `references/user-id-migration.md`
-- **Source code:** `modules/sonamu/src/auth/plugins/`