howone 0.1.23 → 0.1.26

package/templates/vite/.howone/skills/howone-sdk/03-sdk/03-auth.md

@@ -1,616 +0,0 @@
-# Auth
-
-## Two Auth Layers
-
-HowOne has two distinct auth layers:
-
-1. **Client-level auth** (`client.auth.*`) — low-level token management, login/logout redirects.  
-2. **HowOne Auth service** (`unifiedAuth`, standalone functions) — headless OTP and OAuth flows for building custom login UIs.
-
-For React auth UI, see `03-sdk/04-react-integration.md` (`HowOneProvider`, `useHowoneContext`).
-
----
-
-## client.auth — Token Management
-
-```ts
-import howone from '@/lib/sdk'
-
-// Check if the current user is authenticated
-howone.auth.isAuthenticated() // boolean
-
-// Get the current JWT token (null if not logged in)
-const token = howone.auth.getToken()
-
-// Manually set a token (after a custom login flow)
-howone.auth.setToken(jwtToken)
-
-// Clear the token
-howone.auth.setToken(null)
-
-// Redirect to the HowOne login page
-howone.auth.login()
-howone.auth.login('/dashboard') // optional return path after login
-
-// Log out and clear session
-howone.auth.logout()
-```
-
----
-
-## User Profile
-
-```ts
-import { HowOneAuthError } from '@howone/sdk'
-import howone from '@/lib/sdk'
-
-type UserProfile = {
-  id: string       // backend owner id; same as userId when JWT has userId
-  userId?: string  // authenticated backend user id when present in JWT
-  puid?: string    // public UUID; do not use as public ownerId scope
-  email?: string
-  name?: string
-  avatarUrl?: string
-  appId?: string
-  roles?: string[]
-  metadata?: Record<string, unknown>
-}
-
-// Returns null if not authenticated
-const user = await howone.me()
-
-// Returns the profile or throws HowOneAuthError if not authenticated
-const user = await howone.requireMe()
-
-// Alias for me()
-const user = await howone.session.user()
-
-// Force refresh from server (skip cache)
-const user = await howone.me({ refresh: true })
-```
-
-### Identity fields
-
-HowOne JWTs may contain both `userId` and `puid`. The SDK preserves both:
-
-- `user.id` / `user.userId` identifies the authenticated backend user.
-- `user.puid` is the public UUID and should not be used for entity owner filters.
-- `query.mine()` requires auth and lets the backend derive ownership from the JWT.
-
-For public share URLs that need scoped owner data, use `howone.public.entities.*`
-and pass the schema-required public scope, usually the shared owner id stored on a record.
-Do not pass `puid` as `ownerId`.
-
-### Pattern: guard a page
-
-```tsx
-import { useEffect, useState } from 'react'
-import { HowOneAuthError } from '@howone/sdk'
-import howone, { type UserProfile } from '@/lib/sdk'
-
-function useCurrentUser() {
-  const [user, setUser] = useState<UserProfile | null>(null)
-  const [loading, setLoading] = useState(true)
-
-  useEffect(() => {
-    howone.me()
-      .then(setUser)
-      .catch(err => {
-        if (err instanceof HowOneAuthError) {
-          howone.auth.login()
-        }
-      })
-      .finally(() => setLoading(false))
-  }, [])
-
-  return { user, loading }
-}
-```
-
----
-
-## Email OTP Login
-
-Use `sendEmailVerificationCode` → `loginWithEmailCode` to build a custom email login form.
-
-The SDK normalizes HowOne auth envelopes. Both of these backend response shapes are valid:
-
-```ts
-{ success: true, token: 'jwt...' }
-{ code: 0, data: { success: true, token: 'jwt...' } }
-```
-
-After normalization, read `result.success`, `result.token`, and `result.message` from the top level.
-
-### Standalone functions (imported directly)
-
-```ts
-import {
-  sendEmailVerificationCode,
-  loginWithEmailCode,
-} from '@howone/sdk'
-
-// Step 1 — send OTP
-const sendResult = await sendEmailVerificationCode(
-  'user@example.com',
-  'MyAppName', // optional, shown in the email
-)
-// sendResult.success: boolean
-// sendResult.expiresIn: number (seconds until expiry)
-// sendResult.message: string (error message if !success)
-// sendResult.code: number (business error code if any)
-
-// Step 2 — verify OTP and get token
-const loginResult = await loginWithEmailCode(
-  'user@example.com',
-  '123456', // 6-digit OTP from email
-)
-// loginResult.success: boolean
-// loginResult.token: string (JWT, present on success)
-// loginResult.user: { email, name? }
-// loginResult.redirect_url: string (if configured)
-// loginResult.message: string
-// loginResult.code: number
-
-if (loginResult.success && loginResult.token) {
-  howone.auth.setToken(loginResult.token)
-  // Persists the token and updates the active SDK client.
-}
-```
-
-### Using the unifiedAuth service
-
-```ts
-import { unifiedAuth } from '@howone/sdk'
-
-// Same API as standalone functions
-const sendResult = await unifiedAuth.sendEmailVerificationCode(email, appName)
-const loginResult = await unifiedAuth.loginWithEmailCode(email, code)
-
-// Verify an existing token
-const { valid, user } = await unifiedAuth.verifyToken(token)
-
-// Logout (server-side invalidation)
-await unifiedAuth.logout(token)
-```
-
-### React component — email OTP form
-
-```tsx
-import { useState } from 'react'
-import { sendEmailVerificationCode, loginWithEmailCode } from '@howone/sdk'
-import howone from '@/lib/sdk'
-
-type Step = 'email' | 'code' | 'done'
-
-export function EmailLoginForm({ onSuccess }: { onSuccess: () => void }) {
-  const [step, setStep] = useState<Step>('email')
-  const [email, setEmail] = useState('')
-  const [code, setCode] = useState('')
-  const [loading, setLoading] = useState(false)
-  const [error, setError] = useState<string | null>(null)
-
-  async function handleSendCode(e: React.FormEvent) {
-    e.preventDefault()
-    setLoading(true)
-    setError(null)
-    try {
-      const result = await sendEmailVerificationCode(email)
-      if (!result.success) {
-        setError(result.message ?? 'Failed to send code')
-        return
-      }
-      setStep('code')
-    } finally {
-      setLoading(false)
-    }
-  }
-
-  async function handleVerifyCode(e: React.FormEvent) {
-    e.preventDefault()
-    setLoading(true)
-    setError(null)
-    try {
-      const result = await loginWithEmailCode(email, code)
-      if (!result.success || !result.token) {
-        setError(result.message ?? 'Invalid code')
-        return
-      }
-      howone.auth.setToken(result.token)
-      setStep('done')
-      onSuccess()
-    } finally {
-      setLoading(false)
-    }
-  }
-
-  if (step === 'email') {
-    return (
-      <form onSubmit={handleSendCode}>
-        <input
-          type="email"
-          value={email}
-          onChange={e => setEmail(e.target.value)}
-          placeholder="Enter your email"
-          required
-        />
-        {error && <p className="error">{error}</p>}
-        <button type="submit" disabled={loading}>
-          {loading ? 'Sending...' : 'Send Code'}
-        </button>
-      </form>
-    )
-  }
-
-  if (step === 'code') {
-    return (
-      <form onSubmit={handleVerifyCode}>
-        <p>Enter the code sent to {email}</p>
-        <input
-          type="text"
-          value={code}
-          onChange={e => setCode(e.target.value)}
-          placeholder="6-digit code"
-          maxLength={6}
-          required
-        />
-        {error && <p className="error">{error}</p>}
-        <button type="submit" disabled={loading}>
-          {loading ? 'Verifying...' : 'Login'}
-        </button>
-        <button type="button" onClick={() => setStep('email')}>
-          Back
-        </button>
-      </form>
-    )
-  }
-
-  return <p>Login successful!</p>
-}
-```
-
----
-
-## Phone OTP Login
-
-Same flow as email, using E.164 phone number format (e.g. `+14155552671`).
-
-```ts
-import {
-  sendPhoneVerificationCode,
-  loginWithPhoneCode,
-} from '@howone/sdk'
-
-// Step 1 — send SMS OTP
-const sendResult = await sendPhoneVerificationCode(
-  '+14155552671', // must be E.164 format
-  'MyAppName',    // optional
-)
-// sendResult.success: boolean
-// sendResult.expires_in: number (seconds)
-
-// Step 2 — verify OTP
-const loginResult = await loginWithPhoneCode(
-  '+14155552671',
-  '123456',
-)
-// loginResult.success: boolean
-// loginResult.token: string (JWT on success)
-// loginResult.user: { phone_e164?, email?, name? }
-
-if (loginResult.success && loginResult.token) {
-  howone.auth.setToken(loginResult.token)
-}
-```
-
-### Phone number validation note
-
-The SDK validates that phone numbers are in E.164 format internally. Always pass the number with country code (e.g. `+1`, `+44`, `+86`).
-
----
-
-## OAuth — Google and GitHub
-
-### Google Login
-
-```ts
-import { unifiedAuth } from '@howone/sdk'
-import howone from '@/lib/sdk'
-
-async function loginWithGoogle() {
-  // Opens a popup window for Google OAuth
-  const result = await unifiedAuth.initiateGoogleLogin()
-  // result.token: string (JWT)
-  // result.user: any
-
-  howone.auth.setToken(result.token)
-}
-```
-
-### GitHub Login
-
-```ts
-import { unifiedAuth } from '@howone/sdk'
-
-async function loginWithGitHub() {
-  const result = await unifiedAuth.initiateGitHubLogin()
-  howone.auth.setToken(result.token)
-}
-```
-
-### Handle OAuth redirect callback
-
-If you redirect instead of using a popup, call `checkOAuthCallback()` on the return page:
-
-```ts
-import { unifiedOAuth } from '@howone/sdk'
-import howone from '@/lib/sdk'
-
-// Call on the OAuth callback page (e.g. /auth/callback)
-function handleOAuthReturn() {
-  const result = unifiedOAuth.checkOAuthCallback()
-  // result.success: boolean
-  // result.token: string (if success)
-  // result.error: string (if failure)
-  // result.user: any
-
-  if (result.success && result.token) {
-    howone.auth.setToken(result.token)
-    window.location.href = '/dashboard'
-  } else {
-    console.error('OAuth failed:', result.error)
-  }
-}
-```
-
-### React — OAuth buttons
-
-```tsx
-import { unifiedAuth } from '@howone/sdk'
-import howone from '@/lib/sdk'
-
-export function OAuthButtons({ onSuccess }: { onSuccess: () => void }) {
-  const [loading, setLoading] = useState<'google' | 'github' | null>(null)
-  const [error, setError] = useState<string | null>(null)
-
-  async function handleGoogle() {
-    setLoading('google')
-    setError(null)
-    try {
-      const { token } = await unifiedAuth.initiateGoogleLogin()
-      howone.auth.setToken(token)
-      onSuccess()
-    } catch (err) {
-      setError(err instanceof Error ? err.message : 'Google login failed')
-    } finally {
-      setLoading(null)
-    }
-  }
-
-  async function handleGitHub() {
-    setLoading('github')
-    setError(null)
-    try {
-      const { token } = await unifiedAuth.initiateGitHubLogin()
-      howone.auth.setToken(token)
-      onSuccess()
-    } catch (err) {
-      setError(err instanceof Error ? err.message : 'GitHub login failed')
-    } finally {
-      setLoading(null)
-    }
-  }
-
-  return (
-    <div>
-      <button onClick={handleGoogle} disabled={loading !== null}>
-        {loading === 'google' ? 'Connecting...' : 'Continue with Google'}
-      </button>
-      <button onClick={handleGitHub} disabled={loading !== null}>
-        {loading === 'github' ? 'Connecting...' : 'Continue with GitHub'}
-      </button>
-      {error && <p className="error">{error}</p>}
-    </div>
-  )
-}
-```
-
----
-
-## Token Verification
-
-```ts
-import { unifiedAuth } from '@howone/sdk'
-
-async function checkToken(token: string) {
-  const { valid, user } = await unifiedAuth.verifyToken(token)
-  if (valid) {
-    console.log('User:', user)
-  } else {
-    console.log('Token is invalid or expired')
-  }
-}
-```
-
-## Custom Login UI Pattern
-
-Use this when the app should show its own login page instead of redirecting to `/howone/auth`.
-
-### SDK setup
-
-```ts
-// src/lib/sdk.ts
-import { createClient } from '@howone/sdk'
-
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
-  env: import.meta.env.VITE_HOWONE_ENV,
-  auth: { mode: 'managed' },
-})
-
-export default client
-```
-
-`managed` is still correct for most custom login pages because `howone.auth.setToken(token)`
-persists the token through the SDK auth store. Use `headless` only when an external auth
-provider owns token storage.
-
-### Provider setup
-
-```tsx
-<HowOneProvider auth="none" brand="hidden">
-  <App />
-</HowOneProvider>
-```
-
-`auth="none"` disables the provider redirect so the app can render its own login form.
-
-### App startup
-
-```tsx
-useEffect(() => {
-  let cancelled = false
-
-  howone.me()
-    .then((user) => {
-      if (!cancelled) setUser(user)
-    })
-    .catch(() => {
-      if (!cancelled) setUser(null)
-    })
-    .finally(() => {
-      if (!cancelled) setLoading(false)
-    })
-
-  return () => {
-    cancelled = true
-  }
-}, [])
-```
-
-Do not use `howone.auth.isAuthenticated()` as the first-load gate for protected UI. It is a
-synchronous token presence check. `howone.me()` verifies/restores the current session and is the
-right source of truth for initial render.
-
-### Login success
-
-```ts
-const result = await loginWithEmailCode(email, code)
-if (!result.success || !result.token) {
-  setError(result.message ?? 'Invalid code')
-  return
-}
-
-howone.auth.setToken(result.token)
-const user = await howone.me({ refresh: true })
-setUser(user)
-```
-
-Use the same pattern for phone OTP and OAuth popup results.
-
-### Logout
-
-```ts
-const token = howone.auth.getToken()
-if (token) await unifiedAuth.logout(token)
-howone.auth.logout()
-setUser(null)
-```
-
-`howone.auth.logout()` clears the SDK token store and active client token.
-
-## Headless External Auth Pattern
-
-Use `auth.mode = "headless"` only when another auth system owns the token lifecycle.
-
-```ts
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
-  env: import.meta.env.VITE_HOWONE_ENV,
-  auth: {
-    mode: 'headless',
-    getToken: async () => externalAuth.getJwt(),
-    tokenCacheMs: 30_000,
-  },
-})
-```
-
-Do not invent a second localStorage key for HowOne OTP/OAuth login. Use `howone.auth.setToken`
-unless the user explicitly asks to integrate an external auth provider.
-
----
-
-## Logout
-
-```ts
-// Client-side logout (clears local token storage)
-howone.auth.logout()
-
-// Server-side invalidation via unifiedAuth
-await unifiedAuth.logout(token)
-```
-
----
-
-## HowOneAuthError
-
-```ts
-import { HowOneAuthError } from '@howone/sdk'
-
-try {
-  const user = await howone.requireMe()
-} catch (err) {
-  if (err instanceof HowOneAuthError) {
-    // err.code === 'UNAUTHENTICATED'
-    howone.auth.login('/current-page')
-  }
-}
-```
-
----
-
-## Auth Mode in createClient
-
-Choose the auth mode that matches your login strategy:
-
-```ts
-// Managed (default) — SDK owns the token lifecycle
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
-  env: import.meta.env.VITE_HOWONE_ENV,
-  auth: { mode: 'managed' },
-})
-
-// Headless — you own the token (for Clerk, Supabase, custom JWTs, etc.)
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
-  env: import.meta.env.VITE_HOWONE_ENV,
-  auth: {
-    mode: 'headless',
-    getToken: async () => {
-      return localStorage.getItem('auth_token')
-    },
-    tokenCacheMs: 30_000,
-  },
-})
-
-// None — unauthenticated, public API access only
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
-  env: import.meta.env.VITE_HOWONE_ENV,
-  auth: { mode: 'none' },
-})
-```
-
----
-
-## Common Mistakes
-
-| Mistake | Correct Pattern |
-|---|---|
-| Phone number without country code: `'13800138000'` | Use E.164: `'+8613800138000'` |
-| Using `loginWithEmailCode` without first calling `sendEmailVerificationCode` | Always send the code first |
-| Hand-writing a separate localStorage token key for HowOne OTP/OAuth | Use `howone.auth.setToken(token)` |
-| Using `auth.isAuthenticated()` to decide first render after refresh | Use `await howone.me()` |
-| Setting `HowOneProvider auth="required"` with a custom in-app login form | Use `auth="none"` so the provider does not redirect |
-| Calling `unifiedAuth.logout()` without the token argument | Pass `token`: `await unifiedAuth.logout(howone.auth.getToken()!)` |