@vobs/auth 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vobs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @vobs/auth
+
+Reactive session state with role and permission checks, declarative access-control boundaries, and a typed error model.
+
+## Install
+
+```bash
+npm install @vobs/auth
+```
+
+## Quick start
+
+```ts
+import { createAuth } from '@vobs/auth'
+
+const auth = createAuth({
+  loginHandler: async credentials => ({
+    user: {
+      id: String(credentials.id),
+      roles: ['editor'],
+      permissions: ['article:read', 'article:edit']
+    }
+  })
+})
+
+await auth.login({ id: 7 })
+auth.status.value // 'authenticated'
+auth.hasPermission('article:edit') // true
+auth.requirePermission('article:delete') // throws AuthError with code 'PERMISSION_DENIED'
+auth.logout()
+auth.dispose()
+```
+
+## API
+
+| Signature | Description |
+| --- | --- |
+| `createAuth(options?: AuthOptions<C>): AuthContext<C>` | Creates an auth context; owns a session signal unless `options.session` is provided. |
+| `auth.session` | Reactive session signal, `null` when anonymous. |
+| `auth.status: Signal<AuthStatus>` | `'anonymous'` or `'authenticated'`, derived from the session. |
+| `auth.login(credentials: C): Promise<void>` | Calls `loginHandler`, validates the returned session, and stores it. |
+| `auth.logout(): void` | Clears the session. |
+| `auth.hasPermission(permission: Permission): boolean` | Checks the current user's permissions. |
+| `auth.hasRole(role: string): boolean` | Checks the current user's roles. |
+| `auth.requirePermission(permission: Permission): void` | Throws `AuthError('PERMISSION_DENIED')` when the permission is missing. |
+| `auth.requireRole(role: string): void` | Throws `AuthError('PERMISSION_DENIED')` when the role is missing. |
+| `auth.dispose(): void` | Disposes the session and status signals. |
+| `authPlugin(options?: AuthPluginOptions<C>): VobsPlugin` | Provides the context through `AUTH_KEY` and disposes it with the app. |
+| `useAuth(): AuthContext` | Injects the auth context inside components. |
+| `RequireAuth(props?: AuthBoundaryProps): VobsNode` | Renders `children` while a session exists, otherwise `fallback`. |
+| `RequirePermission(props: RequirePermissionProps): VobsNode` | Renders `children` when the permission is granted. |
+| `RequireRole(props: RequireRoleProps): VobsNode` | Renders `children` when the role is granted. |
+| `RequireAnyPermission(props: RequirePermissionsProps): VobsNode` | Renders `children` when at least one permission is granted. |
+| `RequireAllPermissions(props: RequirePermissionsProps): VobsNode` | Renders `children` when every permission is granted. |
+
+`login` validates that `loginHandler` returns a session with `user.id`, `user.roles`, and `user.permissions`, throwing `AuthError('INVALID_SESSION')` otherwise. All boundaries re-render reactively when the session signal changes.
+
+## Types
+
+`AuthContext`, `AuthOptions`, `AuthPluginOptions`, `AuthStatus`, `AuthErrorCode`, `Session`, `SessionUser`, `Role`, `Permission`, `Credentials`, `AuthBoundaryProps`, `RequirePermissionProps`, `RequireRoleProps`, `RequirePermissionsProps`

package/package.json

@@ -0,0 +1,25 @@
+{
+  "license": "MIT",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "name": "@vobs/auth",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@vobs/vobs": "1.0.0",
+    "@vobs/reactivity": "1.0.0"
+  },
+  "devDependencies": {
+    "@vobs/resource": "1.0.0",
+    "@vobs/http": "1.0.0",
+    "@vobs/router": "1.0.0"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from 'vitest'
+import { createElement, createText, createVobs, insertBefore, setRenderer, createDOMRenderer } from '@vobs/vobs'
+import { createHTTPClient } from '@vobs/http'
+import { createResourceClient } from '@vobs/resource'
+import { createMemoryHistory, createRouter } from '@vobs/router'
+import {
+  AUTH_KEY,
+  AuthError,
+  RequireAnyPermission,
+  RequireAuth,
+  RequirePermission,
+  authPlugin,
+  createAuth,
+  useAuth
+} from './index'
+
+describe('@vobs/auth', () => {
+  it('登录、登出和权限判断保持响应式 session', async () => {
+    const auth = createAuth({
+      loginHandler: async credentials => ({
+        user: {
+          id: String(credentials.id),
+          roles: ['editor'],
+          permissions: ['article:read', 'article:edit']
+        }
+      })
+    })
+
+    expect(auth.status.value).toBe('anonymous')
+    expect(auth.hasPermission('article:read')).toBe(false)
+    await auth.login({ id: 7 })
+    expect(auth.status.value).toBe('authenticated')
+    expect(auth.hasRole('editor')).toBe(true)
+    expect(auth.hasPermission('article:edit')).toBe(true)
+    auth.requirePermission('article:read')
+    auth.logout()
+    expect(auth.status.value).toBe('anonymous')
+    expect(auth.hasRole('editor')).toBe(false)
+    auth.dispose()
+  })
+
+  it('未配置登录处理器、无权限和无效 session 都给出 AuthError', async () => {
+    const auth = createAuth()
+    await expect(auth.login({})).rejects.toMatchObject({ code: 'LOGIN_NOT_CONFIGURED' })
+    expect(() => auth.requirePermission('admin')).toThrowError(
+      expect.objectContaining({ code: 'PERMISSION_DENIED' })
+    )
+    const invalid = createAuth({ loginHandler: () => ({ user: { id: '1' } } as never) })
+    await expect(invalid.login({})).rejects.toMatchObject({ code: 'INVALID_SESSION' })
+    auth.dispose()
+    invalid.dispose()
+  })
+
+  it('authPlugin 注入上下文，并在应用销毁时清理自有上下文', () => {
+    let injected: unknown
+    const app = createVobs({
+      render: () => createText('app'),
+      plugins: [{
+        name: 'consumer',
+        requires: [authPlugin()],
+        install(context) { injected = context.inject(AUTH_KEY) }
+      }]
+    })
+    expect(injected).toBeDefined()
+    app.destroy()
+    expect(() => (injected as ReturnType<typeof createAuth>).logout()).toThrow('已销毁')
+  })
+
+  it('权限边界默认拒绝，并在 session 变化后更新子树', () => {
+    setRenderer(createDOMRenderer())
+    const auth = createAuth()
+    const container = document.createElement('div')
+    const app = createVobs({
+      render: () => {
+        const root = createElement('main')
+        insertBefore(root, RequireAuth({ children: () => createText('signed-in') }), null)
+        insertBefore(root, RequirePermission({
+          permission: 'article:edit',
+          children: () => createText('edit')
+        }), null)
+        insertBefore(root, RequireAnyPermission({
+          permissions: ['article:read', 'article:edit'],
+          children: () => createText('read-or-edit')
+        }), null)
+        return root
+      },
+      plugins: [authPlugin({ auth })]
+    })
+
+    app.mount(container)
+    expect(container.textContent).toBe('')
+    auth.session.value = { user: { id: '1', roles: [], permissions: ['article:edit'] } }
+    app.update()
+    expect(container.textContent).toBe('signed-ineditread-or-edit')
+    auth.logout()
+    app.update()
+    expect(container.textContent).toBe('')
+    app.destroy()
+    auth.dispose()
+  })
+
+  it('可配合 Router 守卫拒绝匿名访问并重定向登录页', async () => {
+    const auth = createAuth()
+    const router = createRouter({
+      history: createMemoryHistory('/'),
+      routes: [
+        { path: '/', component: () => createText('home') },
+        { path: '/login', component: () => createText('login') },
+        { path: '/private', component: () => createText('private'), meta: { requiresAuth: true } }
+      ]
+    })
+    router.beforeEach(to => to.meta.requiresAuth && !auth.session.value ? '/login' : undefined)
+
+    await expect(router.push('/private')).resolves.toMatchObject({ path: '/login' })
+    auth.session.value = { user: { id: '1', roles: [], permissions: [] } }
+    await expect(router.push('/private')).resolves.toMatchObject({ path: '/private' })
+    router.destroy()
+    auth.dispose()
+  })
+
+  it('可用 HTTP 请求拦截器读取当前 session 并在登出后停止携带凭证', async () => {
+    const auth = createAuth()
+    const seen: string[] = []
+    const client = createHTTPClient({
+      adapter: config => {
+        seen.push(config.headers.Authorization ?? '')
+        return new Response('{}', { status: 200, headers: { 'content-type': 'application/json' } })
+      }
+    })
+    client.interceptors.request.use(config => {
+      const user = auth.session.value?.user
+      if (user) config.headers.Authorization = `Session ${user.id}`
+      return config
+    })
+
+    await client.get('/me')
+    auth.session.value = { user: { id: '42', roles: [], permissions: [] } }
+    await client.get('/me')
+    auth.logout()
+    await client.get('/me')
+    expect(seen).toEqual(['', 'Session 42', ''])
+    auth.dispose()
+  })
+
+  it('Resource fetcher 复用带 Auth session 的 HTTP 请求拦截器', async () => {
+    const auth = createAuth()
+    const client = createHTTPClient({
+      adapter: config => new Response(JSON.stringify({
+        id: config.headers.Authorization?.replace('Session ', '') ?? 'anonymous'
+      }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' }
+      })
+    })
+    client.interceptors.request.use(config => {
+      const user = auth.session.value?.user
+      if (user) config.headers.Authorization = `Session ${user.id}`
+      return config
+    })
+    const resources = createResourceClient()
+    const profile = resources.resource({
+      key: ['profile'],
+      fetcher: signal => client.get<{ id: string }>('/me', { signal }).then(response => response.data)
+    })
+
+    await profile.refetch()
+    expect(profile.data.value).toEqual({ id: 'anonymous' })
+    auth.session.value = { user: { id: '42', roles: [], permissions: [] } }
+    resources.invalidate(['profile'])
+    await profile.refetch()
+    expect(profile.data.value).toEqual({ id: '42' })
+    resources.clear()
+    auth.dispose()
+  })
+
+  it('未安装插件时 useAuth 抛出明确错误', () => {
+    const app = createVobs({ render: () => {
+      useAuth()
+      return createText('')
+    } })
+    expect(() => app.mount(document.createElement('div'))).toThrowError(
+      expect.objectContaining({ code: 'AUTH_CONTEXT_MISSING' })
+    )
+    expect(AuthError).toBeDefined()
+  })
+})

package/src/index.ts

@@ -0,0 +1,227 @@
+import { getCurrentOwner, memo, onDispose, state, type Signal } from '@vobs/reactivity'
+import {
+  createFragment,
+  createInjectionKey,
+  inject,
+  insertDynamic,
+  type InjectionKey,
+  type VobsNode,
+  type VobsPlugin
+} from '@vobs/vobs'
+
+export type Permission = string
+
+export interface Role {
+  readonly name: string
+  readonly permissions: readonly Permission[]
+}
+
+export interface SessionUser {
+  readonly id: string
+  readonly roles: readonly string[]
+  readonly permissions: readonly Permission[]
+}
+
+export interface Session {
+  readonly user: SessionUser
+  readonly [key: string]: unknown
+}
+
+export type Credentials = Record<string, unknown>
+export type AuthStatus = 'anonymous' | 'authenticated'
+
+export type AuthErrorCode =
+  | 'AUTH_CONTEXT_MISSING'
+  | 'LOGIN_NOT_CONFIGURED'
+  | 'INVALID_SESSION'
+  | 'AUTH_REQUIRED'
+  | 'PERMISSION_DENIED'
+
+export class AuthError extends Error {
+  readonly code: AuthErrorCode
+
+  constructor(code: AuthErrorCode, message: string) {
+    super(message)
+    this.name = 'AuthError'
+    this.code = code
+  }
+}
+
+export interface AuthContext<C extends Credentials = Credentials> {
+  readonly session: Signal<Session | null>
+  readonly status: Signal<AuthStatus>
+  hasPermission(permission: Permission): boolean
+  hasRole(role: string): boolean
+  login(credentials: C): Promise<void>
+  logout(): void
+  requirePermission(permission: Permission): void
+  requireRole(role: string): void
+  dispose(): void
+}
+
+export interface AuthOptions<C extends Credentials = Credentials> {
+  readonly session?: Signal<Session | null>
+  readonly loginHandler?: (credentials: C) => Session | PromiseLike<Session>
+  readonly roles?: Readonly<Record<string, Role>>
+  readonly permissions?: Readonly<Record<string, Permission>>
+}
+
+export interface AuthPluginOptions<C extends Credentials = Credentials> extends AuthOptions<C> {
+  readonly auth?: AuthContext<C>
+}
+
+export const AUTH_KEY: InjectionKey<AuthContext> = createInjectionKey<AuthContext>('vobs.auth')
+
+export interface AuthBoundaryProps {
+  readonly fallback?: VobsNode | (() => VobsNode | null | undefined)
+  readonly children?: VobsNode | (() => VobsNode | null | undefined)
+}
+
+export interface RequirePermissionProps extends AuthBoundaryProps {
+  readonly permission: Permission
+}
+
+export interface RequireRoleProps extends AuthBoundaryProps {
+  readonly role: string
+}
+
+export interface RequirePermissionsProps extends AuthBoundaryProps {
+  readonly permissions: readonly Permission[]
+}
+
+export function createAuth<C extends Credentials = Credentials>(options: AuthOptions<C> = {}): AuthContext<C> {
+  const ownedSession = options.session ? undefined : state<Session | null>(null)
+  const session = options.session ?? ownedSession!
+  const status = memo<AuthStatus>(() => session.value ? 'authenticated' : 'anonymous')
+  let disposed = false
+
+  const context: AuthContext<C> = {
+    session,
+    status,
+
+    hasPermission(permission: Permission): boolean {
+      if (disposed || !permission) return false
+      return session.value?.user.permissions.includes(permission) ?? false
+    },
+
+    hasRole(role: string): boolean {
+      if (disposed || !role) return false
+      return session.value?.user.roles.includes(role) ?? false
+    },
+
+    async login(credentials: C): Promise<void> {
+      ensureActive()
+      if (!options.loginHandler) {
+        throw new AuthError('LOGIN_NOT_CONFIGURED', 'Vobs Auth: 未配置 loginHandler')
+      }
+      const nextSession = await options.loginHandler(credentials)
+      validateSession(nextSession)
+      session.value = nextSession
+    },
+
+    logout(): void {
+      ensureActive()
+      session.value = null
+    },
+
+    requirePermission(permission: Permission): void {
+      ensureActive()
+      if (!context.hasPermission(permission)) {
+        throw new AuthError('PERMISSION_DENIED', `Vobs Auth: 缺少权限 ${permission}`)
+      }
+    },
+
+    requireRole(role: string): void {
+      ensureActive()
+      if (!context.hasRole(role)) {
+        throw new AuthError('PERMISSION_DENIED', `Vobs Auth: 缺少角色 ${role}`)
+      }
+    },
+
+    dispose(): void {
+      if (disposed) return
+      disposed = true
+      status.dispose()
+      ownedSession?.dispose()
+    }
+  }
+
+  if (ownedSession && getCurrentOwner()) onDispose(context.dispose)
+  return context
+
+  function ensureActive(): void {
+    if (disposed) throw new AuthError('AUTH_CONTEXT_MISSING', 'Vobs Auth: 上下文已销毁')
+  }
+}
+
+export function authPlugin<C extends Credentials = Credentials>(options: AuthPluginOptions<C> = {}): VobsPlugin {
+  return {
+    name: '@vobs/auth',
+    version: '0.1.0',
+    install(context) {
+      const ownedAuth = options.auth ? undefined : createAuth(options)
+      context.provide(AUTH_KEY, options.auth ?? ownedAuth!)
+      return () => ownedAuth?.dispose()
+    }
+  }
+}
+
+export function useAuth(): AuthContext {
+  const auth = inject(AUTH_KEY)
+  if (!auth) {
+    throw new AuthError('AUTH_CONTEXT_MISSING', 'Vobs Auth: 找不到上下文，请安装 authPlugin')
+  }
+  return auth
+}
+
+export function RequireAuth(props: AuthBoundaryProps = {}): VobsNode {
+  return createAuthBoundary(useAuth, auth => Boolean(auth.session.value), props)
+}
+
+export function RequirePermission(props: RequirePermissionProps): VobsNode {
+  return createAuthBoundary(useAuth, auth => auth.hasPermission(props.permission), props)
+}
+
+export function RequireRole(props: RequireRoleProps): VobsNode {
+  return createAuthBoundary(useAuth, auth => auth.hasRole(props.role), props)
+}
+
+export function RequireAnyPermission(props: RequirePermissionsProps): VobsNode {
+  return createAuthBoundary(
+    useAuth,
+    auth => props.permissions.some(permission => auth.hasPermission(permission)),
+    props
+  )
+}
+
+export function RequireAllPermissions(props: RequirePermissionsProps): VobsNode {
+  return createAuthBoundary(
+    useAuth,
+    auth => props.permissions.every(permission => auth.hasPermission(permission)),
+    props
+  )
+}
+
+function createAuthBoundary(
+  getAuth: () => AuthContext,
+  allowed: (auth: AuthContext) => boolean,
+  props: AuthBoundaryProps
+): VobsNode {
+  const auth = getAuth()
+  return createFragment((parent, anchor) => {
+    insertDynamic(parent, anchor, () => {
+      const node = allowed(auth) ? props.children : props.fallback
+      return typeof node === 'function' ? node() : node
+    })
+  })
+}
+
+function validateSession(value: Session): void {
+  if (!value || typeof value !== 'object' || !value.user || typeof value.user !== 'object') {
+    throw new AuthError('INVALID_SESSION', 'Vobs Auth: loginHandler 返回了无效 session')
+  }
+  const user = value.user
+  if (typeof user.id !== 'string' || !Array.isArray(user.roles) || !Array.isArray(user.permissions)) {
+    throw new AuthError('INVALID_SESSION', 'Vobs Auth: session.user 必须包含 id、roles 和 permissions')
+  }
+}