@h-ai/cli 0.1.0-alpha.56 → 0.1.0-alpha.58

package/templates/apps/fullstack/packages/{{projectName}}-serv/tests/app-server.test.ts.hbs

@@ -1,52 +1,465 @@
-import { apiContract } from '@h-ai/api-contract'
-import { {{fullstack.contractExportName}} } from '{{fullstack.contractPackageName}}'
-import { describe, expect, it } from 'vitest'
+import type { CoreConfig, HaiResult } from '@h-ai/core'
+import type { TransportClient } from '@h-ai/crypto'
+import type { AdminUser } from '{{fullstack.contractPackageName}}'
+import { Buffer } from 'node:buffer'
+import { mkdtemp, rm } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { audit } from '@h-ai/audit'
+import { cache } from '@h-ai/cache'
+import { core, err, HaiCommonError } from '@h-ai/core'
+import { crypto } from '@h-ai/crypto'
+import { iam } from '@h-ai/iam'
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
 import { createServerApp } from '../src/app-server.js'
+import { closeModules, initializeModules } from '../src/server/runtime.js'
 
-const API_PREFIX = '/api/v1'
+const PREFIX = '/api/v1'
+const TEST_PASSWORD = 'TemplateTest123!'
+const PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aSxkAAAAASUVORK5CYII='
+let app: ReturnType<typeof createServerApp>
+let transport: TransportClient
+let storageRoot: string
+let cookie = ''
+let adminToken = ''
+let adminId = ''
+let userToken = ''
+let user: AdminUser
+let encryptedRequests = 0
+let encryptedResponses = 0
+interface LoginData { user: { id: string }, tokens: { accessToken: string, refreshToken?: string }, roles: string[] }
 
-describe('{{fullstack.servPackageName}}', () => {
-  it('returns health status', async () => {
-    const app = createServerApp()
-    const response = await app.request('/health')
-
-    expect(response.status).toBe(200)
-    await expect(response.json()).resolves.toEqual({ status: 'ok' })
+/** 使用真实加密协议与 HTTP 服务，同时保留浏览器 refresh cookie。 */
+async function call<T>(route: string, input?: object, token?: string, method = 'POST'): Promise<HaiResult<T>> {
+  const response = await transport.encryptedFetch(`http://localhost${PREFIX}${route}`, {
+    method,
+    headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
+    ...(input ? { body: JSON.stringify(input) } : {}),
   })
+  return response.json() as Promise<HaiResult<T>>
+}
 
-  it('returns app info as HaiResult', async () => {
-    const app = createServerApp()
-    const response = await app.request(`${API_PREFIX}${apiContract.pathOf({{fullstack.contractExportName}}.app.info)}`, { method: 'POST' })
-    const body = await response.json()
-
-    expect(response.status).toBe(200)
-    expect(body.success).toBe(true)
-    expect(body.data.name).toBe('{{fullstack.servPackageName}}')
+beforeAll(async () => {
+  storageRoot = await mkdtemp(path.join(os.tmpdir(), '{{projectName}}-avatars-'))
+  vi.stubEnv('HAI_DB_DATABASE', '":memory:"')
+  vi.stubEnv('HAI_STORAGE_ROOT', storageRoot)
+  vi.stubEnv('HAI_ADMIN_DEFAULT_PASSWORD', TEST_PASSWORD)
+  core.init({ configDir: './config' })
+  await initializeModules()
+  app = createServerApp()
+  transport = crypto.transport.createClient({
+    keyExchangeUrl: `http://localhost${PREFIX}/_hai/key-exchange`,
+    fetch: async (input, init) => {
+      const request = new Request(input, init)
+      if (cookie && request.url.endsWith('/auth/refresh'))
+        request.headers.set('cookie', cookie)
+      if (request.headers.get('x-encrypted') === 'true')
+        encryptedRequests++
+      const response = await app.fetch(request)
+      if (response.headers.get('x-encrypted') === 'true') {
+        encryptedResponses++
+        const wire = await response.clone().text()
+        expect(wire).not.toContain(TEST_PASSWORD)
+        expect(wire).not.toContain('"username"')
+      }
+      const nextCookie = response.headers.get('set-cookie')
+      if (nextCookie)
+        cookie = nextCookie.split(';')[0] ?? ''
+      return response
+    },
   })
+}, 30_000)
 
-  it('validates echo input', async () => {
-    const app = createServerApp()
-    const response = await app.request(`${API_PREFIX}${apiContract.pathOf({{fullstack.contractExportName}}.app.echo)}`, {
+afterAll(async () => {
+  transport?.destroy()
+  await closeModules()
+  vi.unstubAllEnvs()
+  await rm(storageRoot, { recursive: true, force: true })
+})
+
+describe('{{fullstack.servPackageName}} mini administration', () => {
+  it('keeps health public, requires encryption and reads runtime identity from core', async () => {
+    expect((await app.request('/health')).status).toBe(200)
+    expect((await app.request(`${PREFIX}/app/info`, { method: 'POST' })).status).toBe(400)
+    const result = await call<{ name: string, version: string, env: string, defaultLocale: string }>('/app/info')
+    expect(result.success).toBe(true)
+    if (!result.success)
+      return
+    const config = core.config.getOrThrow<CoreConfig>('core')
+    expect(result.data).toMatchObject({ name: config.name, version: config.version, env: config.env, defaultLocale: config.defaultLocale })
+    const invalid = await transport.encryptedFetch(`http://localhost${PREFIX}/app/echo`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ message: '' }),
     })
+    expect(invalid.status).toBe(400)
+  })
+
+  it('logs in and refreshes with a browser cookie without exposing its refresh token', async () => {
+    const result = await call<LoginData>('/auth/login', { identifier: 'admin', password: TEST_PASSWORD })
+    expect(result.success).toBe(true)
+    if (!result.success)
+      return
+    adminToken = result.data.tokens.accessToken
+    adminId = result.data.user.id
+    expect(result.data.roles).toEqual(['admin'])
+    expect(result.data.tokens.refreshToken).toBeUndefined()
+    expect(cookie).toContain('hai_refresh_token=')
+    const refreshed = await call<{ tokens: { accessToken: string, refreshToken?: string } }>('/auth/refresh', {})
+    expect(refreshed.success).toBe(true)
+    if (refreshed.success) {
+      expect(refreshed.data.tokens.refreshToken).toBeUndefined()
+      adminToken = refreshed.data.tokens.accessToken
+    }
+  })
+
+  it('does not mount unselected default IAM routes', async () => {
+    for (const [route, method] of [
+      ['/auth/register', 'POST'],
+      ['/auth/login/otp', 'POST'],
+      ['/auth/otp/send', 'POST'],
+      ['/iam/users', 'GET'],
+      ['/iam/roles', 'POST'],
+    ] as const) {
+      const response = await transport.encryptedFetch(`http://localhost${PREFIX}${route}`, {
+        method,
+        headers: { 'content-type': 'application/json', 'authorization': `Bearer ${adminToken}` },
+        ...(method === 'POST' ? { body: '{}' } : {}),
+      })
+      expect(response.status).toBe(404)
+    }
+  })
 
-    expect(response.status).toBe(400)
+  it('creates a normal user and enforces guards on every administration API', async () => {
+    const created = await call<AdminUser>('/admin/users/create', { username: 'normal-user', password: TEST_PASSWORD, role: 'user', enabled: true }, adminToken)
+    expect(created.success).toBe(true)
+    if (!created.success)
+      return
+    user = created.data
+    const loggedIn = await call<LoginData>('/auth/login', { identifier: user.username, password: TEST_PASSWORD })
+    expect(loggedIn.success).toBe(true)
+    if (!loggedIn.success)
+      return
+    userToken = loggedIn.data.tokens.accessToken
+    for (const [route, input] of [
+      ['/admin/users/list', { page: 1, pageSize: 20 }],
+      ['/admin/users/create', { username: 'forbidden', password: TEST_PASSWORD }],
+      ['/admin/users/update', { id: adminId, enabled: false }],
+      ['/admin/users/delete', { id: adminId }],
+      ['/admin/users/avatar', { id: adminId, contentType: 'image/png', base64: PNG }],
+      ['/admin/roles/list', undefined],
+      ['/admin/roles/update', { id: 'missing', description: 'x' }],
+      ['/admin/audit/list', { page: 1, pageSize: 20 }],
+    ] as const) {
+      const denied = await call(route, input, userToken)
+      expect(denied.success).toBe(false)
+      if (!denied.success)
+        expect(denied.error.httpStatus).toBe(403)
+    }
   })
 
-  it('returns echo result as HaiResult', async () => {
-    const app = createServerApp()
-    const response = await app.request(`${API_PREFIX}${apiContract.pathOf({{fullstack.contractExportName}}.app.echo)}`, {
+  it('allows refresh-token body transport only for an identified trusted native origin', async () => {
+    for (const [clientName, origin] of [['{{projectName}}-app', 'capacitor://localhost'], ['{{projectName}}-desktop', 'http://tauri.localhost']] as const) {
+      const headers = { 'content-type': 'application/json', 'x-request-client': clientName, 'x-hai-token-transport': 'body', origin }
+      const login = await transport.encryptedFetch(`http://localhost${PREFIX}/auth/login`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ identifier: 'admin', password: TEST_PASSWORD }),
+      })
+      const result = await login.json() as HaiResult<LoginData>
+      expect(result.success).toBe(true)
+      if (!result.success)
+        continue
+      expect(result.data.tokens.refreshToken).toBeTruthy()
+      expect(login.headers.get('set-cookie')).toBeNull()
+      const refresh = await transport.encryptedFetch(`http://localhost${PREFIX}/auth/refresh`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ refreshToken: result.data.tokens.refreshToken }),
+      })
+      const refreshed = await refresh.json() as HaiResult<{ tokens: { refreshToken: string } }>
+      expect(refreshed.success).toBe(true)
+      if (refreshed.success)
+        expect(refreshed.data.tokens.refreshToken).not.toBe(result.data.tokens.refreshToken)
+    }
+    for (const [clientName, origin] of [['{{projectName}}-app', 'http://untrusted.example'], ['unrecognized-client', 'capacitor://localhost']] as const) {
+      const response = await transport.encryptedFetch(`http://localhost${PREFIX}/auth/login`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-request-client': clientName, 'x-hai-token-transport': 'body', origin },
+        body: JSON.stringify({ identifier: 'admin', password: TEST_PASSWORD }),
+      })
+      const result = await response.json() as HaiResult<LoginData>
+      expect(result.success).toBe(true)
+      if (result.success)
+        expect(result.data.tokens.refreshToken).toBeUndefined()
+    }
+  })
+
+  it('paginates users and protects administrators from self deletion, disable and downgrade', async () => {
+    const listed = await call<{ items: AdminUser[], total: number }>('/admin/users/list', { page: 1, pageSize: 1 }, adminToken)
+    expect(listed.success).toBe(true)
+    if (listed.success) {
+      expect(listed.data.items).toHaveLength(1)
+      expect(listed.data.total).toBe(2)
+    }
+    for (const [route, input] of [['/admin/users/delete', { id: adminId }], ['/admin/users/update', { id: adminId, enabled: false }], ['/admin/users/update', { id: adminId, role: 'user' }]] as const) {
+      const denied = await call(route, input, adminToken)
+      expect(denied.success).toBe(false)
+      if (!denied.success)
+        expect(denied.error.httpStatus).toBe(403)
+    }
+  })
+
+  it('updates personal preferences, validates images and serves only allowed avatar resources', async () => {
+    expect((await call('/profile/update', { displayName: 'Updated', locale: 'en-US', theme: '{{fullstack.theme.defaultTheme}}' }, userToken)).success).toBe(true)
+    const current = await call<{ metadata: { locale: string, theme: string } }>('/auth/me', undefined, userToken, 'GET')
+    expect(current.success).toBe(true)
+    if (current.success)
+      expect(current.data.metadata).toMatchObject({ locale: 'en-US', theme: '{{fullstack.theme.defaultTheme}}' })
+    expect((await call('/profile/update', { email: 'temporary@example.com' }, userToken)).success).toBe(true)
+    const cleared = await call<AdminUser>('/profile/update', { email: '' }, userToken)
+    expect(cleared.success).toBe(true)
+    if (cleared.success)
+      expect(cleared.data.email).toBe('')
+    const invalid = await call('/profile/avatar', { contentType: 'image/png', base64: 'PHN2Zz48L3N2Zz4=' }, userToken)
+    expect(invalid.success).toBe(false)
+    if (!invalid.success)
+      expect(invalid.error.httpStatus).toBe(400)
+    const oversized = await call('/profile/avatar', { contentType: 'image/png', base64: Buffer.alloc(512 * 1024 + 1).toString('base64') }, userToken)
+    expect(oversized.success).toBe(false)
+    const anonymous = await call('/profile/avatar', { contentType: 'image/png', base64: PNG })
+    expect(anonymous.success).toBe(false)
+    if (!anonymous.success)
+      expect(anonymous.error.httpStatus).toBe(401)
+    const injected = await transport.encryptedFetch(`http://localhost${PREFIX}/profile/update`, {
       method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ message: 'hello unit' }),
+      headers: { 'content-type': 'application/json', 'authorization': `Bearer ${userToken}` },
+      body: JSON.stringify({ id: adminId, enabled: false, displayName: 'Intruder' }),
+    })
+    expect(injected.status).toBe(400)
+    const uploaded = await call<{ avatarUrl: string }>('/profile/avatar', { contentType: 'image/png', base64: PNG }, userToken)
+    expect(uploaded.success).toBe(true)
+    if (!uploaded.success)
+      return
+    expect(uploaded.data.avatarUrl).toMatch(/^\/api\/v1\/assets\/avatars\/[\w-]+\/[\w-]+\.png$/)
+    const asset = await app.request(uploaded.data.avatarUrl)
+    expect(asset.status).toBe(200)
+    expect(asset.headers.get('content-type')).toBe('image/png')
+    expect((await asset.arrayBuffer()).byteLength).toBeGreaterThan(0)
+    expect((await app.request(`${PREFIX}/assets/avatars/%2e%2e/config/_core.yml`)).status).toBe(404)
+    expect((await call('/admin/users/avatar', { id: user.id, contentType: 'image/png', base64: PNG }, adminToken)).success).toBe(true)
+    expect((await app.request(uploaded.data.avatarUrl)).status).toBe(404)
+    const hostile = await transport.encryptedFetch(`http://attacker.example${PREFIX}/profile/avatar`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'authorization': `Bearer ${userToken}` },
+      body: JSON.stringify({ contentType: 'image/png', base64: PNG }),
+    })
+    const hostileResult = await hostile.json() as HaiResult<{ avatarUrl: string }>
+    expect(hostileResult.success).toBe(true)
+    if (hostileResult.success) {
+      expect(hostileResult.data.avatarUrl).toMatch(/^\/api\/v1\/assets\//)
+      expect(hostileResult.data.avatarUrl).not.toContain('attacker.example')
+      const stored = await iam.user.getUser(user.id)
+      expect(stored.success).toBe(true)
+      if (stored.success)
+        expect(stored.data?.avatarUrl).toBe(hostileResult.data.avatarUrl)
+    }
+  })
+
+  it('lists two roles, updates descriptions and queries audit records without credentials or file content', async () => {
+    const roles = await call<{ items: { id: string, code: string, userCount: number }[] }>('/admin/roles/list', undefined, adminToken)
+    expect(roles.success).toBe(true)
+    if (roles.success) {
+      expect(roles.data.items.map(item => item.code).sort()).toEqual(['admin', 'user'])
+      const role = roles.data.items.find(item => item.code === 'user')!
+      expect(role.userCount).toBe(1)
+      expect((await call('/admin/roles/update', { id: role.id, description: 'Updated description' }, adminToken)).success).toBe(true)
+    }
+    const logs = await call<{ items: { action: string, details: string | null }[], total: number }>('/admin/audit/list', { page: 1, pageSize: 100 }, adminToken)
+    expect(logs.success).toBe(true)
+    if (logs.success) {
+      expect(logs.data.total).toBeGreaterThan(0)
+      expect(JSON.stringify(logs.data)).not.toContain(TEST_PASSWORD)
+      expect(JSON.stringify(logs.data)).not.toContain(PNG)
+    }
+  })
+
+  it('does not write profile fields when role synchronization fails', async () => {
+    const before = await iam.user.getUser(user.id)
+    expect(before.success).toBe(true)
+    const sync = vi.spyOn(iam.authz, 'syncRoles').mockResolvedValueOnce(err(HaiCommonError.API_ERROR, 'Injected role persistence failure'))
+    const failed = await call('/admin/users/update', { id: user.id, role: 'admin', email: 'changed@example.com', displayName: 'Should not change' }, adminToken)
+    sync.mockRestore()
+    expect(failed.success).toBe(false)
+    const after = await iam.user.getUser(user.id)
+    expect(after.success).toBe(true)
+    if (before.success && after.success)
+      expect(after.data).toMatchObject({ email: before.data?.email, displayName: before.data?.displayName })
+  })
+
+  it('keeps an already committed profile update successful when best-effort audit fails', async () => {
+    const log = vi.spyOn(audit, 'log').mockResolvedValueOnce(err(HaiCommonError.API_ERROR, 'Injected audit persistence failure'))
+    const logger = vi.spyOn(core.logger, 'error').mockImplementation(() => {})
+    try {
+      const result = await call<AdminUser>('/profile/update', { displayName: 'Committed profile' }, userToken)
+      expect(result.success).toBe(true)
+      if (result.success)
+        expect(result.data.displayName).toBe('Committed profile')
+      expect(logger).toHaveBeenCalledWith('Failed to record audit event', expect.objectContaining({ action: 'update', resource: 'profile' }))
+    }
+    finally {
+      log.mockRestore()
+      logger.mockRestore()
+    }
+  })
+
+  it('rolls back roles when profile persistence fails and keeps role changes effective in active sessions', async () => {
+    const update = vi.spyOn(iam.user, 'updateUser').mockResolvedValueOnce(err(HaiCommonError.API_ERROR, 'Injected user persistence failure'))
+    const failed = await call('/admin/users/update', { id: user.id, role: 'admin', email: 'changed@example.com' }, adminToken)
+    update.mockRestore()
+    expect(failed.success).toBe(false)
+    const roles = await iam.authz.getUserRoles(user.id)
+    expect(roles.success).toBe(true)
+    if (roles.success)
+      expect(roles.data.map(role => role.code)).toEqual(['user'])
+    expect((await call('/admin/users/update', { id: user.id, role: 'admin' }, adminToken)).success).toBe(true)
+    expect((await call('/admin/users/list', { page: 1, pageSize: 20 }, userToken)).success).toBe(true)
+    expect((await call('/admin/users/update', { id: user.id, role: 'user' }, adminToken)).success).toBe(true)
+    const denied = await call('/admin/users/list', { page: 1, pageSize: 20 }, userToken)
+    expect(denied.success).toBe(false)
+    if (!denied.success)
+      expect(denied.error.httpStatus).toBe(403)
+  })
+
+  it('rejects stale administrator snapshots and reports fresh user roles', async () => {
+    const stale = await iam.session.update(userToken, { roles: ['admin'], permissions: ['*'] })
+    expect(stale.success).toBe(true)
+    for (const [route, input] of [['/admin/users/list', { page: 1, pageSize: 20 }], ['/admin/roles/list', undefined], ['/admin/audit/list', { page: 1, pageSize: 20 }]] as const) {
+      const denied = await call(route, input, userToken)
+      expect(denied.success).toBe(false)
+      if (!denied.success)
+        expect(denied.error.httpStatus).toBe(403)
+    }
+    const current = await call<{ roles: string[] }>('/auth/me', undefined, userToken, 'GET')
+    expect(current.success).toBe(true)
+    if (current.success)
+      expect(current.data.roles).toEqual(['user'])
+  })
+
+  it('returns a conflict when another administrator holds the mutation lock and resumes after release', async () => {
+    const locked = await cache.lock.acquire('hai:app:admin-mutation', { owner: 'test-owner', ttl: 10 })
+    expect(locked.success).toBe(true)
+    try {
+      const result = await call('/admin/users/update', { id: user.id, displayName: 'Locked' }, adminToken)
+      expect(result.success).toBe(false)
+      if (!result.success)
+        expect(result.error.httpStatus).toBe(409)
+    }
+    finally {
+      expect((await cache.lock.release('hai:app:admin-mutation', 'test-owner')).success).toBe(true)
+    }
+    expect((await call('/admin/users/update', { id: user.id, displayName: 'Unlocked' }, adminToken)).success).toBe(true)
+  })
+
+  it('keeps single-writer protection after an expired lease and resumes after a slow mutation', async () => {
+    const other = await call<AdminUser>('/admin/users/create', { username: 'lease-admin', password: TEST_PASSWORD, role: 'admin' }, adminToken)
+    expect(other.success).toBe(true)
+    if (!other.success)
+      return
+    const otherLogin = await call<LoginData>('/auth/login', { identifier: 'lease-admin', password: TEST_PASSWORD })
+    expect(otherLogin.success).toBe(true)
+    if (!otherLogin.success)
+      return
+    let resume: () => void = () => {}
+    let entered: () => void = () => {}
+    const paused = new Promise<void>((resolve) => {
+      resume = resolve
+    })
+    const entry = new Promise<void>((resolve) => {
+      entered = resolve
     })
-    const body = await response.json()
+    const original = iam.user.updateUser
+    const update = vi.spyOn(iam.user, 'updateUser').mockImplementationOnce(async (id, data) => {
+      entered()
+      await paused
+      return original(id, data)
+    })
+    const first = call('/admin/users/update', { id: other.data.id, enabled: false }, adminToken)
+    await entry
+    const now = vi.spyOn(Date, 'now').mockReturnValue(Date.now() + 301_000)
+    try {
+      const conflicting = await call('/admin/users/update', { id: adminId, enabled: false }, otherLogin.data.tokens.accessToken)
+      expect(conflicting.success).toBe(false)
+      if (!conflicting.success)
+        expect(conflicting.error.httpStatus).toBe(409)
+      resume()
+      expect((await first).success).toBe(true)
+      const admin = await iam.user.getUser(adminId)
+      expect(admin.success).toBe(true)
+      if (admin.success)
+        expect(admin.data?.enabled).toBe(true)
+    }
+    finally {
+      resume()
+      now.mockRestore()
+      update.mockRestore()
+    }
+    expect((await call('/admin/users/delete', { id: other.data.id }, adminToken)).success).toBe(true)
+  })
+
+  it('serializes mutually destructive admin requests and preserves an enabled administrator', async () => {
+    const created = await call<AdminUser>('/admin/users/create', { username: 'second-admin', password: TEST_PASSWORD, role: 'admin' }, adminToken)
+    expect(created.success).toBe(true)
+    if (!created.success)
+      return
+    const loggedIn = await call<LoginData>('/auth/login', { identifier: 'second-admin', password: TEST_PASSWORD })
+    expect(loggedIn.success).toBe(true)
+    if (!loggedIn.success)
+      return
+    // 对手同时请求禁用原管理员；锁内重新鉴权阻止两个请求全部成功。
+    const results = await Promise.all([
+      call('/admin/users/update', { id: created.data.id, enabled: false }, adminToken),
+      call('/admin/users/update', { id: adminId, enabled: false }, loggedIn.data.tokens.accessToken),
+    ])
+    expect(results.filter(result => result.success)).toHaveLength(1)
+    const admins = await iam.user.listUsers({ enabled: true, include: ['roles'] })
+    expect(admins.success).toBe(true)
+    if (admins.success) {
+      const surviving = admins.data.items.filter(item => item.roles?.some(role => role.code === 'admin'))
+      expect(surviving).toHaveLength(1)
+      // 后续用仍有效的管理员会话验证其他操作。
+      if (surviving[0]?.id !== adminId) {
+        adminToken = loggedIn.data.tokens.accessToken
+        adminId = created.data.id
+      }
+    }
+  })
 
-    expect(response.status).toBe(200)
-    expect(body.success).toBe(true)
-    expect(body.data.message).toBe('hello unit')
-    expect(body.data.requestId).toBeDefined()
+  it('invalidates sessions on disable and password change and proves encrypted traffic', async () => {
+    expect((await call('/admin/users/update', { id: user.id, enabled: false }, adminToken)).success).toBe(true)
+    const denied = await call('/auth/me', undefined, userToken, 'GET')
+    expect(denied.success).toBe(false)
+    if (!denied.success)
+      expect(denied.error.httpStatus).toBe(401)
+    expect((await call('/admin/users/update', { id: user.id, enabled: true }, adminToken)).success).toBe(true)
+    const loggedIn = await call<LoginData>('/auth/login', { identifier: user.username, password: TEST_PASSWORD })
+    expect(loggedIn.success).toBe(true)
+    if (!loggedIn.success)
+      return
+    expect((await call('/auth/change-password', { oldPassword: TEST_PASSWORD, newPassword: 'ChangedTest123!' }, loggedIn.data.tokens.accessToken)).success).toBe(true)
+    expect((await call('/auth/me', undefined, loggedIn.data.tokens.accessToken, 'GET')).success).toBe(false)
+    const changedLogin = await call<LoginData>('/auth/login', { identifier: user.username, password: 'ChangedTest123!' })
+    expect(changedLogin.success).toBe(true)
+    if (changedLogin.success) {
+      expect((await call('/auth/logout', {}, changedLogin.data.tokens.accessToken)).success).toBe(true)
+      expect((await call('/auth/me', undefined, changedLogin.data.tokens.accessToken, 'GET')).success).toBe(false)
+    }
+    expect((await call('/admin/users/delete', { id: user.id }, adminToken)).success).toBe(true)
+    const removed = await iam.user.getUser(user.id)
+    expect(removed.success).toBe(true)
+    if (removed.success)
+      expect(removed.data).toBeNull()
+    expect(encryptedRequests).toBeGreaterThan(10)
+    expect(encryptedResponses).toBeGreaterThan(10)
   })
 })

package/templates/apps/fullstack/packages/{{projectName}}-serv/tests/runtime.test.ts.hbs

@@ -0,0 +1,48 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { audit } from '@h-ai/audit'
+import { cache } from '@h-ai/cache'
+import { core } from '@h-ai/core'
+import { crypto } from '@h-ai/crypto'
+import { iam } from '@h-ai/iam'
+import { reldb } from '@h-ai/reldb'
+import { storage } from '@h-ai/storage'
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+import { closeModules, initializeModules } from '../src/server/runtime.js'
+
+let storageRoot: string
+
+beforeEach(async () => {
+  storageRoot = await mkdtemp(path.join(os.tmpdir(), '{{projectName}}-bootstrap-'))
+  vi.stubEnv('HAI_DB_DATABASE', '":memory:"')
+  vi.stubEnv('HAI_STORAGE_ROOT', storageRoot)
+  vi.stubEnv('HAI_IAM_PASSWORD_REQUIREUPPERCASE', 'true')
+  core.init({ configDir: './config' })
+})
+
+afterEach(async () => {
+  await closeModules()
+  vi.unstubAllEnvs()
+  await rm(storageRoot, { recursive: true, force: true })
+})
+
+it.each([
+  { password: 'abc', reason: /at least 8 characters|至少为 8 个字符/ },
+  { password: 'lowercase123!', reason: /uppercase letters|大写字母/ },
+])('startup explains the failed password policy and permits a clean retry: $password', async ({ password, reason }) => {
+  vi.stubEnv('HAI_ADMIN_DEFAULT_PASSWORD', password)
+  await expect(initializeModules()).rejects.toThrow(reason)
+  for (const module of [audit, iam, storage, crypto, cache, reldb])
+    expect(module.isInitialized).toBe(false)
+
+  // 失败后再次初始化，确认未保留半成品管理员或未释放的模块。
+  vi.stubEnv('HAI_ADMIN_DEFAULT_PASSWORD', 'Bootstrap-retry-Admin123!')
+  await initializeModules()
+  const users = await iam.user.listUsers({ page: 1, pageSize: 10 })
+  expect(users.success).toBe(true)
+  if (users.success) {
+    expect(users.data.total).toBe(1)
+    expect(users.data.items[0]?.username).toBe('admin')
+  }
+})

package/templates/apps/fullstack/packages/{{projectName}}-serv/tsup.config.ts.hbs

@@ -3,7 +3,7 @@ import { defineConfig } from 'tsup'
 export default defineConfig({
   entry: ['src/index.ts'],
   format: ['esm'],
-  dts: true,
+  dts: { compilerOptions: { ignoreDeprecations: '6.0' } },
   sourcemap: true,
   clean: true,
 })

package/templates/apps/fullstack/packages/{{projectName}}-shared/README.md.hbs

@@ -1,39 +1,32 @@
 # {{fullstack.sharedPackageName}}
 
-Frontend shared package for **{{projectName}}**. Provides:
+Shared mini administration workspace for **{{projectName}}**. Web, Capacitor App and Tauri desktop use the same `AdminWorkspace`, responsive `AppShell`, typed API client and management store.
 
-- `AppShell` — common layout (header / footer / theme + language switchers)
-- `ThemeSwitcher`, `LanguageSwitcher`
-- `themeStore` — daisyUI theme persistence
-- `fetchAppInfo` — typed API client wrapping `@h-ai/api-client`
-- Shared Inlang Paraglide messages compiled from this package's `project.inlang/` + `messages/`
+- Administrators manage users, upload user avatars, assign the built-in administrator/user roles, edit role descriptions and query audit logs.
+- Ordinary users can only update their own profile, avatar, language, appearance and password. The server enforces access on every request.
+- `ManagementStore` owns API calls and business state; components render the state and forward user interactions.
+- Application name, version, environment and default locale come from the backend `app.info` contract, which reads `core` configuration. Do not duplicate these values in translations or frontend constants.
+- Requests, token refresh and JSON responses use the same `@h-ai/api-client` + `@h-ai/crypto` transport. Avatar uploads use encrypted JSON and validate PNG/JPEG/WebP content, with a 512 KiB limit.
+- Read metadata through the same initialized `managementApi.app.info()` client; inspect `success` before using `data`.
 
-Consumed by `{{projectName}}-web`, `{{projectName}}-app`, `{{projectName}}-desktop`, and the reserved `{{projectName}}-miniapp` guidance.
+All three Vite apps read the workspace root .env. Development and preview servers proxy /api to the local backend when no explicit API base is configured, so browser clients can use a single origin. In deployments, configure PUBLIC_API_BASE or the Web container runtime API origin for the actual service.
 
-## i18n collaboration
+An origin-only API base uses `/api/v1`. For a custom service `http.apiPrefix`, include that path in `PUBLIC_API_BASE` or the runtime API base; the client preserves the configured path and restricts avatar URLs to its matching resource prefix.
 
-- `packages/{{fullstack.sharedPackageName}}/messages/` stores **shared UI copy** used by reusable components such as `AppShell`, `ThemeSwitcher`, and `LanguageSwitcher`.
-- `apps/{{projectName}}-web/messages/`, `apps/{{projectName}}-app/messages/`, and `apps/{{projectName}}-desktop/messages/` store **frontend-specific product copy**.
-- `apps/{{projectName}}-miniapp/messages/` is prepared for mini-app-specific copy even though the mini target is currently a placeholder.
-- Keep `baseLocale` and `locales` aligned across shared and every frontend `project.inlang/settings.json`. The language switcher updates shared and the host app runtime together.
+## Authentication and preferences
 
-Rule of thumb: if a string appears inside reusable shared components, put it here; if it belongs to one product surface, put it in that frontend's `messages/` directory.
+Web and browser previews keep access tokens in memory and refresh tokens in the server's httpOnly Cookie. Requests include credentials; reload restores the session through the encrypted refresh flow. Never store authentication tokens in localStorage.
 
-## Scripts
+Capacitor native uses `createCapacitorTokenStorage()` and the trusted native token channel. Tauri native uses memory token storage and requires a new login after restarting the application. Native builds require a reachable `PUBLIC_API_BASE` in the workspace root `.env`; missing configuration produces a connection configuration error. Both send their frontend `clientName` and `X-HAI-Token-Transport: body`; the service verifies the allowed native origin before returning a refresh token in JSON.
 
-- `pnpm paraglide:compile` — compile messages → `src/lib/paraglide/`
-- `pnpm paraglide:watch` — watch + recompile on message edits
-- `pnpm typecheck`, `pnpm lint`, `pnpm test`
+Language and theme preferences are saved in IAM user metadata, restored after login and synchronized with the shared/host Paraglide runtimes and `core.i18n`. The small reactive theme store delegates DOM updates and safe appearance caching to `@h-ai/ui/theme` (`applyTheme` / `getSavedTheme`); the framework uses the `theme` localStorage key. Appearance selectors live in personal settings and save through the authenticated profile contract.
 
-## Adding a locale
+## i18n and themes
 
-1. Add the locale to `project.inlang/settings.json` `locales` array.
-2. Add the same locale to every enabled frontend `project.inlang/settings.json`.
-3. Create `messages/{locale}.json` in shared and each enabled frontend.
-4. Run root `pnpm i18n:compile` to compile shared and every enabled frontend Paraglide output. You can also run `pnpm paraglide:compile` inside one package when editing that package only.
+Shared page copy belongs in `messages/{zh-CN,en-US}.json`. Frontend-specific copy belongs in each app's own messages directory. Keep `baseLocale` and `locales` aligned across all enabled projects, then run root `pnpm i18n:compile`; do not edit generated Paraglide files.
 
-## Customizing theme and shell
+The scaffold theme configuration determines the themes compiled into frontend CSS. Personal settings offer only those available themes. Customize the common layout in `src/lib/components/AppShell.svelte`, the management pages in adjacent components, and business behavior in `src/lib/stores/management-store.svelte.ts`.
 
-- Theme names come from the scaffold `fullstack.theme` config and are rendered into each frontend `src/app.css` daisyUI plugin block.
-- `themeStore` persists the selected theme in local storage under `{{projectName}}:theme`.
-- To customize the global chrome, edit `src/lib/components/AppShell.svelte`; to customize a single frontend page, edit that frontend's route and messages.
+## Validation
+
+Run root `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm test` and `pnpm test:e2e`. Shared API tests exercise real transport key exchange, encrypted request/response handling, configured core metadata and credential forwarding. Root browser tests cover administrator and ordinary-user workflows, avatar rendering, persisted preferences, password/session invalidation and narrow-screen layout.