@h-ai/cli 0.1.0-alpha.59 → 0.1.0-alpha.60

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.59",
+  "version": "0.1.0-alpha.60",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -30,7 +30,7 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "dependencies": {
-    "@h-ai/core": "0.1.0-alpha.59",
+    "@h-ai/core": "0.1.0-alpha.60",
     "cac": "^7.0.1",
     "chalk": "^6.0.1",
     "fast-wrap-ansi": "^0.2.2",
@@ -41,11 +41,11 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@h-ai/cache": "0.1.0-alpha.59",
-    "@h-ai/deploy": "0.1.0-alpha.59",
-    "@h-ai/reach": "0.1.0-alpha.59",
-    "@h-ai/reldb": "0.1.0-alpha.59",
-    "@h-ai/storage": "0.1.0-alpha.59",
+    "@h-ai/cache": "0.1.0-alpha.60",
+    "@h-ai/deploy": "0.1.0-alpha.60",
+    "@h-ai/reach": "0.1.0-alpha.60",
+    "@h-ai/reldb": "0.1.0-alpha.60",
+    "@h-ai/storage": "0.1.0-alpha.60",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^26.6.5",
     "@types/prompts": "^2.4.9",

package/templates/README.md

@@ -142,3 +142,11 @@ import { iam } from '@h-ai/iam'
 ### 新增 feature 路由
 
 在 `features/{featureId}/routes-shared/`（API 路由）或 `features/{featureId}/routes-{appType}/`（UI 页面）下创建文件，然后在 `cli-template-engine.ts` 的 `FEATURE_ROUTE_DIRS` / `FEATURE_APP_ROUTE_DIRS` 中注册该目录。
+
+## 配置驱动认证页面
+
+协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+
+选用 IAM 的 admin/h5/website 模板提供 AuthPanel 和标准认证路由；mobile-app 与 fullstack Web/App/Desktop 使用 API 客户端共享动作。修改服务端 config/_iam.yml 即可控制登录方式、注册、重置、协议和品牌，无需改表单。配置 Reach 模板和真实发送 Provider 后启用 OTP/重置。分布式部署使用共享数据库与 Redis。
+
+LDAP/Reach 是可选 peer；IAM 不强制启用 Reach。默认 LDAP 客户端由应用选择安装 ldapts。自定义通知回调、协议弹窗、表单 snippet 用法随 hai-iam/hai-ui skills 完整复制到生成项目，不能要求应用读取本仓库私有路径。

package/templates/apps/api/apps/{{projectName}}-service/README.md.hbs

@@ -21,3 +21,15 @@ pnpm --filter {{api.servicePackageName}} test
 - `src/app.ts`：HTTP App 装配
 - `src/lib/server/init.ts`：模块初始化与关闭
 - `src/server/procedures/`：应用级 procedures
+
+{{#if features.iam}}
+## IAM 认证配置
+
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。客户端可通过安全公开配置和框架认证动作接入 `AuthPanel`。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+
+LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
+
+协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+
+完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
+{{/if}}

package/templates/apps/api/apps/{{projectName}}-service/src/app.ts.hbs

@@ -59,6 +59,10 @@ export function {{api.serviceAppFactoryName}}(_options: CreateApiServiceAppOptio
     },
 {{#if features.iam}}
     iam,
+    refreshCookie,
+{{/if}}
+{{#if features.crypto}}
+    transport,
 {{/if}}
     middlewares: [
       {
@@ -71,13 +75,6 @@ export function {{api.serviceAppFactoryName}}(_options: CreateApiServiceAppOptio
       },
     ],
   }
-{{#if features.iam}}
-
-  appOptions.refreshCookie = refreshCookie
-{{/if}}{{#if features.crypto}}
-  if (transport)
-    appOptions.transport = transport
-{{/if}}
 
   return serv.createApp(appOptions)
 }

package/templates/apps/api/apps/{{projectName}}-service/src/lib/server/init.ts.hbs

@@ -8,6 +8,7 @@
 {{/if}}import { core } from '@h-ai/core'
 {{#if features.crypto}}import { crypto } from '@h-ai/crypto'
 {{/if}}{{#if features.iam}}import { iam, IamConfigSchema } from '@h-ai/iam'
+{{/if}}{{#if features.reach}}import { reach, ReachConfigSchema } from '@h-ai/reach'
 {{/if}}{{#if features.db}}import { reldb, ReldbConfigSchema } from '@h-ai/reldb'
 {{/if}}import { ServConfigSchema } from '@h-ai/serv'
 {{#if features.storage}}import { storage, StorageConfigSchema } from '@h-ai/storage'
@@ -122,6 +123,14 @@ async function doInit(): Promise<void> {
   if (!cacheResult.success) {
     throw new Error(`Cache initialization failed: ${cacheResult.error.message}`)
   }
+{{/if}}{{#if features.reach}}
+
+  const reachConfig = core.config.get('reach')
+  if (reachConfig) {
+    const result = await reach.init(ReachConfigSchema.parse(reachConfig))
+    if (!result.success)
+      throw new Error('Reach initialization failed')
+  }
 {{/if}}{{#if features.vecdb}}
 
   const vecdbResult = await vecdb.init(vecdbConfig)
@@ -130,7 +139,7 @@ async function doInit(): Promise<void> {
   }
 {{/if}}{{#if features.iam}}
 
-  const iamResult = await iam.init(iamConfig)
+  const iamResult = await iam.init({ ...iamConfig{{#if features.reach}}, reach{{/if}} })
   if (!iamResult.success) {
     throw new Error(`IAM initialization failed: ${iamResult.error.message}`)
   }
@@ -159,6 +168,7 @@ export async function closeApp(): Promise<void> {
 {{#if features.ai}}    ['ai', () => ai.close()],
 {{/if}}{{#if features.storage}}    ['storage', () => storage.close()],
 {{/if}}{{#if features.iam}}    ['iam', () => iam.close()],
+{{/if}}{{#if features.reach}}    ['reach', () => reach.close()],
 {{/if}}{{#if features.vecdb}}    ['vecdb', () => vecdb.close()],
 {{/if}}{{#if features.cache}}    ['cache', () => cache.close()],
 {{/if}}{{#if features.db}}    ['reldb', () => reldb.close()],

package/templates/apps/api/apps/{{projectName}}-service/tests/service.test.ts.hbs

@@ -146,7 +146,8 @@ describe('{{api.servicePackageName}}', () => {
 {{#if features.iam}}
   it('registers a user and returns authenticated echo context', async () => {
     const user = uniqueUser('svc')
-    const register = await client.iam.auth.register({
+    const authActions = apiClient.createAuthActions(client)
+    const register = await authActions.register({
       username: user.username,
       password: user.password,
       email: user.email,

package/templates/apps/api/e2e/api-service.spec.ts.hbs

@@ -1,8 +1,36 @@
-import { apiContract } from '@h-ai/api-contract'
+import process from 'node:process'
+import { apiClient } from '@h-ai/api-client'
+{{#if features.crypto}}
+import { crypto } from '@h-ai/crypto'
+{{/if}}
 import { expect, test } from '@playwright/test'
 import { {{api.contractExportName}} } from '{{api.contractPackageName}}'
 
 const API_PREFIX = '/api/v1'
+const client = apiClient.create({{api.contractExportName}})
+
+test.beforeAll(async () => {
+{{#if features.crypto}}
+  expect((await crypto.init()).success).toBe(true)
+{{/if}}
+  const result = await client.init({
+    baseUrl: `${process.env.BASE_URL || 'http://127.0.0.1:3000'}${API_PREFIX}`,
+{{#if features.iam}}
+    auth: { storage: apiClient.tokenStorage.memory() },
+{{/if}}
+{{#if features.crypto}}
+    transport: process.env.HAI_SERV_TRANSPORT === 'false' ? undefined : { crypto },
+{{/if}}
+  })
+  expect(result.success).toBe(true)
+})
+
+test.afterAll(async () => {
+  await client.close()
+{{#if features.crypto}}
+  await crypto.close()
+{{/if}}
+})
 
 test('service health endpoint returns ok', async ({ request }) => {
   const response = await request.get('/health')
@@ -11,14 +39,52 @@ test('service health endpoint returns ok', async ({ request }) => {
   await expect(response.json()).resolves.toEqual({ status: 'ok' })
 })
 
-test('service app.info endpoint returns HaiResult', async ({ request }) => {
-  const response = await request.post(`${API_PREFIX}${apiContract.pathOf({{api.contractExportName}}.app.info)}`)
-  const body = await response.json()
-
-  expect(response.status()).toBe(200)
+test('service app.info endpoint returns HaiResult', async () => {
+  const body = await client.app.info()
   expect(body.success).toBe(true)
+  if (!body.success)
+    return
   expect(body.data.name).toBe(process.env.HAI_CORE_NAME ?? '{{projectName}} API Service')
   expect(body.data.version).toBe(process.env.HAI_CORE_VERSION ?? '0.1.0')
   expect(body.data.env).toBe(process.env.HAI_CORE_ENV ?? 'development')
   expect(typeof body.data.transportEnabled).toBe('boolean')
 })
+{{#if features.iam}}
+
+/** 通过真实 API 验证 IAM 开关、登录、通知和重置，不需要页面适配。 */
+test('configured IAM supports registration, OTP and reset', async ({ request }) => {
+  test.setTimeout(60_000)
+  const actions = apiClient.createAuthActions(client)
+  const publicConfig = await actions.publicConfig()
+  expect(publicConfig.success).toBe(true)
+  if (!publicConfig.success)
+    return
+  expect(publicConfig.data?.register.enabled).toBe(true)
+  const username = `api${Date.now()}`
+  const email = `${username}@example.com`
+  const password = 'ApiPassword123'
+  expect((await actions.register({ username, email, password })).success).toBe(true)
+  expect((await actions.login({ identifier: username, password })).success).toBe(true)
+  if (!publicConfig.data?.login.email) {
+    // 无 Reach/发送回调时，基础认证仍可用，未就绪的通知入口保持关闭。
+    expect((await actions.sendOtp(email)).success).toBe(false)
+    return
+  }
+  if (!process.env.IAM_NOTIFICATION_URL)
+    return
+  async function received(template: string) {
+    const response = await request.get(`${process.env.IAM_NOTIFICATION_URL}/messages?to=${encodeURIComponent(email)}`)
+    const messages = await response.json() as { template: string, vars: Record<string, string> }[]
+    return messages.findLast(item => item.template === template)?.vars
+  }
+  expect((await actions.sendOtp(email)).success).toBe(true)
+  const otp = await received('otp_email')
+  expect(Boolean(otp?.code)).toBe(true)
+  expect((await actions.login({ identifier: email, method: 'email', code: otp?.code })).success).toBe(true)
+  expect((await actions.requestPasswordReset(email)).success).toBe(true)
+  const reset = await received('password_reset')
+  expect(Boolean(reset?.token)).toBe(true)
+  expect((await actions.confirmPasswordReset(reset?.token ?? '', 'ApiResetPassword456')).success).toBe(true)
+  expect((await actions.login({ identifier: username, password: 'ApiResetPassword456' })).success).toBe(true)
+})
+{{/if}}

package/templates/apps/api/package.json.hbs

@@ -25,6 +25,10 @@
     "{{api.contractPackageName}}": "workspace:*"
   },
   "devDependencies": {
+    "@h-ai/api-client": "{{haiPackageSpecifier}}",
+{{#if features.crypto}}
+    "@h-ai/crypto": "{{haiPackageSpecifier}}",
+{{/if}}
     "@antfu/eslint-config": "{{api.packageSpecifiers.antfuEslintConfig}}",
     "@playwright/test": "{{api.packageSpecifiers.playwright}}",
     "@types/node": "{{api.packageSpecifiers.nodeTypes}}",

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

@@ -35,4 +35,14 @@ pnpm --filter {{projectName}}-app deploy
 ```
 
 部署前确认 `PUBLIC_API_BASE` 在 `.env` 中指向可访问的后端服务。Android 模拟器访问宿主机通常使用 `http://10.0.2.2:3000`。
+
+## IAM 认证配置
+
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+
+LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
+
+协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+
+完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-app/project.inlang/settings.json.hbs

@@ -8,7 +8,7 @@
     {{/each}}
   ],
   "modules": [
-    "https://cdn.jsdelivr.net/npm/@inlang/plugin-message-format@latest/dist/index.js"
+    "../../node_modules/@inlang/plugin-message-format/dist/index.js"
   ],
   "plugin.inlang.messageFormat": {
     "pathPattern": "./messages/{locale}.json"

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

@@ -34,4 +34,14 @@ pnpm --filter {{projectName}}-desktop deploy
 ```
 
 打包前需要安装 Rust 工具链和 Tauri 平台依赖。生产环境部署时同步调整 `.env` 中的 `PUBLIC_API_BASE` 与 `src-tauri/tauri.conf.json` 的 `connect-src` 白名单。
+
+## IAM 认证配置
+
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+
+LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
+
+协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+
+完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-desktop/project.inlang/settings.json.hbs

@@ -8,7 +8,7 @@
     {{/each}}
   ],
   "modules": [
-    "https://cdn.jsdelivr.net/npm/@inlang/plugin-message-format@latest/dist/index.js"
+    "../../node_modules/@inlang/plugin-message-format/dist/index.js"
   ],
   "plugin.inlang.messageFormat": {
     "pathPattern": "./messages/{locale}.json"

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

@@ -7,6 +7,8 @@
 - `project.inlang/settings.json`：小程序端 locale 配置
 - `messages/zh-CN.json`、`messages/en-US.json`：小程序端自有文案
 
+消息格式插件复用 workspace 已安装的依赖，从根目录 `node_modules` 加载；生成后先在 workspace 根目录安装依赖，无需从 CDN 加载插件。
+
 后续实现时建议复用 `packages/{{fullstack.contractPackageName}}` 中的 Schema 与路径常量，保持接口真相源一致。
 
 协同边界：跨端通用文案/组件放 `packages/{{fullstack.sharedPackageName}}`，小程序独有页面文案放本目录 `messages/`。

package/templates/apps/fullstack/apps/{{projectName}}-miniapp/project.inlang/settings.json.hbs

@@ -8,7 +8,7 @@
     {{/each}}
   ],
   "modules": [
-    "https://cdn.jsdelivr.net/npm/@inlang/plugin-message-format@latest/dist/index.js"
+    "../../node_modules/@inlang/plugin-message-format/dist/index.js"
   ],
   "plugin.inlang.messageFormat": {
     "pathPattern": "./messages/{locale}.json"

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

@@ -27,4 +27,14 @@ pnpm --filter {{projectName}}-web package
 # 当前模板的 deploy 入口默认执行 package，可替换为 CDN / 容器发布脚本
 pnpm --filter {{projectName}}-web deploy
 ```
+
+## IAM 认证配置
+
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+
+LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
+
+协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+
+完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。
 {{/if}}

package/templates/apps/fullstack/apps/{{projectName}}-web/project.inlang/settings.json.hbs

@@ -8,7 +8,7 @@
     {{/each}}
   ],
   "modules": [
-    "https://cdn.jsdelivr.net/npm/@inlang/plugin-message-format@latest/dist/index.js"
+    "../../node_modules/@inlang/plugin-message-format/dist/index.js"
   ],
   "plugin.inlang.messageFormat": {
     "pathPattern": "./messages/{locale}.json"

package/templates/apps/fullstack/e2e/fullstack.spec.ts.hbs

@@ -1,6 +1,8 @@
 import type { Page } from '@playwright/test'
 import { Buffer } from 'node:buffer'
 import { randomUUID } from 'node:crypto'
+import { mkdir } from 'node:fs/promises'
+import path from 'node:path'
 import process from 'node:process'
 import { apiContract } from '@h-ai/api-contract'
 import { expect, test } from '@playwright/test'
@@ -43,6 +45,66 @@ test('service rejects plaintext business requests', async ({ request }) => {
 })
 
 {{#if fullstack.e2eFrontend}}
+test('shared authentication supports public registration with configuration', async ({ page }) => {
+  test.setTimeout(90_000)
+  const evidence = process.env.HAI_AUTH_EVIDENCE_DIR || path.resolve('test-results/auth-screenshots')
+  await mkdir(evidence, { recursive: true })
+  await page.goto('/')
+  await expect(page.getByTestId('login-form')).toBeVisible()
+  await page.screenshot({ path: path.join(evidence, '{{projectName}}-login.png'), fullPage: true })
+  await page.getByRole('button', { name: /立即注册|Register now/i }).click()
+  await expect(page.locator('input[name="username"]')).toBeVisible()
+  await page.screenshot({ path: path.join(evidence, '{{projectName}}-register.png'), fullPage: true })
+  const username = `signup${Date.now()}`
+  await page.locator('input[name="username"]').fill(username)
+  await page.locator('input[name="email"]').fill(`${username}@example.com`)
+  await page.locator('input[type="password"]').nth(0).fill('SignupPassword123')
+  await page.locator('input[type="password"]').nth(1).fill('SignupPassword123')
+  await page.locator('button[type="submit"]').click()
+  await expect(page.getByTestId('settings-page')).toBeVisible()
+  expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+  if (!process.env.IAM_NOTIFICATION_URL)
+    return
+  const email = `${username}@example.com`
+  await page.getByTestId('logout').click()
+  await page.getByRole('button', { name: /邮件验证码|Email code/i, exact: true }).click()
+  await page.screenshot({ path: path.join(evidence, '{{projectName}}-email.png'), fullPage: true })
+  await page.locator('#login-username').fill(email)
+  await page.getByRole('button', { name: /发送验证码|Send code/i, exact: true }).click()
+  await expect(page.getByRole('button', { name: /秒后重发|Resend in/ })).toBeDisabled()
+  async function received(template: string) {
+    const response = await page.request.get(`${process.env.IAM_NOTIFICATION_URL}/messages?to=${encodeURIComponent(email)}`)
+    const messages = await response.json() as { template: string, vars: Record<string, string> }[]
+    return messages.findLast(item => item.template === template)?.vars
+  }
+  const otp = await received('otp_email')
+  expect(Boolean(otp?.code)).toBe(true)
+  await page.locator('#login-code').fill(otp?.code ?? '')
+  await page.locator('button[type="submit"]').click()
+  await expect(page.getByTestId('settings-page')).toBeVisible()
+  await page.getByTestId('logout').click()
+  await page.getByRole('button', { name: /忘记密码|Forgot password/i }).click()
+  await page.screenshot({ path: path.join(evidence, '{{projectName}}-forgot.png'), fullPage: true })
+  await page.locator('input[type="email"]').fill(email)
+  await page.locator('button[type="submit"]').click()
+  await expect(page.locator('.alert-success')).toBeVisible()
+  const reset = await received('password_reset')
+  expect(Boolean(reset?.token)).toBe(true)
+  await page.getByRole('button', { name: /已有重置令牌|I have a reset token/i }).click()
+  await page.screenshot({ path: path.join(evidence, '{{projectName}}-reset.png'), fullPage: true })
+  await page.goto(`/?token=${encodeURIComponent(reset?.token ?? '')}`)
+  await expect(page.locator('input[type="password"]').nth(0)).toBeVisible()
+  await page.locator('input[type="password"]').nth(0).fill('FullstackReset456')
+  await page.locator('input[type="password"]').nth(1).fill('FullstackReset456')
+  await page.locator('button[type="submit"]').click()
+  await expect(page.locator('.alert-success')).toBeVisible()
+  await page.getByRole('button', { name: /^(登录|Sign in|Login)$/i }).click()
+  await login(page, username, 'FullstackReset456')
+  await expect(page.getByTestId('settings-page')).toBeVisible()
+  expect(new URL(page.url()).searchParams.has('token')).toBe(false)
+  await page.reload()
+  await expect(page.getByTestId('settings-page')).toBeVisible()
+})
 
 test('frontend displays configured core metadata and restores the administrator session', async ({ page }) => {
   await page.goto('/')
@@ -191,7 +253,7 @@ test('administrator and user complete account, avatar, preference, password and
     await userPage.getByTestId('password-form').getByRole('button', { name: /Change password/i }).click()
     await expect(userPage.getByTestId('login-form')).toBeVisible()
     await login(userPage, username, password)
-    await expect(userPage.getByTestId('login-form')).toContainText(/不正确|incorrect/)
+    await expect(userPage.getByTestId('login-form')).toContainText(/不正确|incorrect/i)
     await login(userPage, username, newPassword)
     await expect(userPage.getByTestId('settings-page')).toBeVisible()
 

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

@@ -6,7 +6,7 @@
 
 - `src/app-schemas.ts`：跨接口、跨层复用的输入/数据 Schema 与类型。
 - `src/app-contract.ts`：app 领域 contract；每个业务 path 直接写在对应接口定义中。
-- `src/admin-schemas.ts` / `src/admin-contract.ts`：管理员用户、固定角色、分页审计、个人设置、加密 JSON 头像上传 Schema/类型/路由；认证复用框架的 IAM auth contract，未开放自助注册和其它认证方式。
+- `src/admin-schemas.ts` / `src/admin-contract.ts`：管理员用户、固定角色、分页审计、个人设置、加密 JSON 头像上传 Schema/类型/路由；认证复用框架的 IAM auth contract，通过服务端配置启用注册、密码/LDAP/验证码登录及密码重置。
 - `src/{{projectName}}-contract.ts`：工程级 contract，供 `@h-ai/serv` 与 `@h-ai/api-client` 共用。
 
 只使用一次的输出 Schema 直接内联到 `.output(...)`；同一 contract 文件内重复使用时才保留私有常量。

package/templates/apps/fullstack/packages/{{projectName}}-contract/src/admin-contract.ts.hbs

@@ -56,8 +56,15 @@ export const profileContract = {
     .output(apiContract.haiResultSchema(AvatarOutputSchema)),
 }
 
-/** 复用框架认证契约，避免额外开放自助注册和未配置的认证方式。 */
+/** 复用框架认证契约；注册、通知和登录方式由 IAM 配置控制。 */
 export const authContract = {
+  publicConfig: apiContract.iam.auth.publicConfig,
+  register: apiContract.iam.auth.register,
+  loginWithLdap: apiContract.iam.auth.loginWithLdap,
+  loginWithOtp: apiContract.iam.auth.loginWithOtp,
+  sendOtp: apiContract.iam.auth.sendOtp,
+  requestPasswordReset: apiContract.iam.auth.requestPasswordReset,
+  confirmPasswordReset: apiContract.iam.auth.confirmPasswordReset,
   login: apiContract.iam.auth.login,
   logout: apiContract.iam.auth.logout,
   currentUser: apiContract.iam.auth.currentUser,

package/templates/apps/fullstack/packages/{{projectName}}-contract/src/admin-schemas.ts.hbs

@@ -28,7 +28,7 @@ export const AdminUsersSchema = z.object({
 })
 export const AdminCreateUserSchema = z.object({
   username: z.string().min(3).max(64).regex(/^[\w-]+$/),
-  password: z.string().min(8).max(128),
+  password: z.string().min(1),
   email: z.email().optional(),
   displayName: z.string().max(100).optional(),
   role: AdminRoleCodeSchema.default('user'),

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

@@ -33,3 +33,13 @@ CLI 已生成根目录 `.env`，`HAI_ADMIN_DEFAULT_PASSWORD` 为每个项目独
 - Web 镜像不烘焙 API 地址；启动时使用 `-e PUBLIC_API_BASE=https://api.example.com` 注入，同一镜像可部署到不同环境。未设置时 Web 默认请求自身 origin。
 - YAML 配置使用 `${ENV_NAME:default}` 接收运行时环境变量；不要把密钥写入镜像。
 - 将 SQLite/本地存储放入本目录 `data/` 后运行 `pnpm docker:build:data` / `pnpm podman:build:data`，可生成带初始数据的镜像，持续写入仍应使用 volume。
+
+## IAM 认证配置
+
+服务端 `config/_iam.yml` 统一控制登录、注册、重置、协议与 `ui` 品牌。邮件/短信可用 `_reach.yml` 中的 Provider/标准模板或自定义发送回调。`AuthPanel` 使用安全公开配置及框架认证动作；无需在页面适配 Token、验证码倒计时和错误提示。所有节点共享同一 DB 与 Redis；Memory 仅用于单进程。
+
+LDAP/Reach 均可选：基础认证无需安装。默认 LDAP 客户端需在 IAM 服务端 workspace 安装 ldapts，再配置 login.ldap 与连接信息。自定义 onOtpSendEmail/onOtpSendSms/onPasswordResetRequest 回调可独立于 Reach 使用，投递失败须拒绝 Promise。协议在 Modal 显示；LoginForm/RegisterForm 提供 header/extraFields/footer，AuthPanel 透传 loginHeader/loginFields/loginFooter 和 registerHeader/registerFields/registerFooter。配置及例子见生成项目的 hai-iam/hai-ui skills。
+
+协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+
+完整契约见生成应用的 `.agents/skills/hai-iam/reference.md`。

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_iam.yml.hbs

@@ -19,3 +19,49 @@ rbac:
   defaultRole: user
 # 仅由应用创建 admin/user，避免生成无业务用途的默认角色与权限。
 seedDefaultData: false
+
+# 注册与登录安全
+register:
+  enabled: true
+  defaultEnabled: true
+security:
+  maxLoginAttempts: 5
+  lockoutDuration: 900
+
+# LDAP 可选：安装 ldapts 后开启 login.ldap，并声明 ldap 连接配置或注入工厂。
+# OTP 需启用 login.otp，并选择 Reach 标准模板或自定义发送回调。
+otp:
+  email: true
+  sms: true
+  length: 6
+  expiresIn: 300
+  maxAttempts: 3
+  resendInterval: 60
+passwordReset:
+  enabled: true
+  mode: email # phone 使用 password_reset_sms 模板
+  tokenExpiresIn: 3600
+  maxAttempts: 3
+  # resetUrl: https://example.com/auth/reset-password
+agreements:
+  showOnRegister: true
+  showOnLogin: false
+  # Markdown 正文由公开配置传给所有客户端，在弹窗内安全渲染。
+  userAgreementMarkdown: |
+    # 用户协议示例
+
+    请妥善保管账户凭据，并按应用提供的功能使用服务。
+  privacyPolicyMarkdown: |
+    # 隐私政策示例
+
+    注册资料用于账户管理，会话信息用于身份认证。
+  # userAgreementUrl: https://example.com/terms
+  # privacyPolicyUrl: https://example.com/privacy
+ui:
+  variant: card
+  # title: Account center
+  # subtitle: Welcome back
+  # brandTitle: Your application
+  # brandText: Sign in securely
+  # logoUrl: /logo.svg
+  # illustrationUrl: /auth-illustration.svg

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_reach.yml.hbs

@@ -0,0 +1,21 @@
+# 开发触达示例；生产环境改为 SMTP、短信或 API Provider。
+providers:
+  - name: email
+    type: console
+  - name: sms
+    type: console
+templates:
+  - name: otp_email
+    provider: email
+    subject: Verification code
+    body: 'Your verification code is {code}.'
+  - name: otp_sms
+    provider: sms
+    body: 'Your verification code is {code}.'
+  - name: password_reset
+    provider: email
+    subject: Password reset
+    body: 'Reset your password: {resetUrl}. Expires at {expiresAt}.'
+  - name: password_reset_sms
+    provider: sms
+    body: 'Reset your password: {resetUrl}. Expires at {expiresAt}.'

package/templates/apps/fullstack/packages/{{projectName}}-serv/package.json.hbs

@@ -34,6 +34,7 @@
     "@h-ai/core": "{{haiPackageSpecifier}}",
     "@h-ai/crypto": "{{haiPackageSpecifier}}",
     "@h-ai/iam": "{{haiPackageSpecifier}}",
+    "@h-ai/reach": "{{haiPackageSpecifier}}",
     "@h-ai/reldb": "{{haiPackageSpecifier}}",
     "@h-ai/serv": "{{haiPackageSpecifier}}",
     "@h-ai/storage": "{{haiPackageSpecifier}}",

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/server/admin-service.ts.hbs

@@ -113,7 +113,7 @@ export async function createAdminUser(input: AdminCreateUser, context: ServConte
     return role
   if (!role.data)
     return err(HaiCommonError.NOT_FOUND, serverM('notFound', { locale: context.locale }))
-  const registered = await iam.user.register(input)
+  const registered = await iam.user.createUser(input)
   if (!registered.success)
     return registered
   const userId = registered.data.user.id

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/server/procedures/admin-procedures.ts.hbs

@@ -20,7 +20,7 @@ import { serverM } from '../messages.js'
 
 /** 身份认证沿用框架公共契约与 refresh-cookie 传输。 */
 export function createAuthProcedures() {
-  const { currentUser, refresh } = createIamProcedures({ iam }).auth
+  const { currentUser, refresh, publicConfig, loginWithOtp, loginWithLdap, register, sendOtp, requestPasswordReset, confirmPasswordReset } = createIamProcedures({ iam }).auth
   const { login, logout, changePassword } = authContract
   // 仅覆写需要业务审计的认证操作，其余直接复用框架；未选认证入口不挂载。
   const audited = serv.implement({ login, logout, changePassword }).context<ServContext>().route('login', async ({ input, context }) => {
@@ -42,7 +42,7 @@ export function createAuthProcedures() {
     await recordAudit(context, 'password-change', 'profile', context.session.userId)
     return result
   }).build()
-  return { ...audited, currentUser, refresh }
+  return { ...audited, currentUser, refresh, publicConfig, loginWithOtp, loginWithLdap, register, sendOtp, requestPasswordReset, confirmPasswordReset }
 }
 
 export function createAdminProcedures() {

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/server/runtime.ts.hbs

@@ -7,6 +7,7 @@ import { cache, CacheConfigSchema } from '@h-ai/cache'
 import { core } from '@h-ai/core'
 import { crypto } from '@h-ai/crypto'
 import { iam, IamConfigSchema } from '@h-ai/iam'
+import { reach, ReachConfigSchema } from '@h-ai/reach'
 import { reldb, ReldbConfigSchema } from '@h-ai/reldb'
 import { ServConfigSchema } from '@h-ai/serv'
 import { storage, StorageConfigSchema } from '@h-ai/storage'
@@ -39,7 +40,10 @@ async function runInitialization(): Promise<void> {
     requireInitialized(await cache.init(cacheConfig), 'cache')
     requireInitialized(await crypto.init(), 'crypto')
     requireInitialized(await storage.init(storageConfig), 'storage')
-    requireInitialized(await iam.init(iamConfig), 'iam')
+    const reachConfig = core.config.get('reach')
+    if (reachConfig)
+      requireInitialized(await reach.init(ReachConfigSchema.parse(reachConfig)), 'reach')
+    requireInitialized(await iam.init({ ...iamConfig, reach }), 'iam')
     requireInitialized(await audit.init(auditConfig), 'audit')
     await ensureRolesAndAdmin()
     initialized = true
@@ -71,7 +75,7 @@ async function ensureRolesAndAdmin(): Promise<void> {
   const password = process.env.HAI_ADMIN_DEFAULT_PASSWORD?.trim()
   if (!password)
     throw new Error('Set HAI_ADMIN_DEFAULT_PASSWORD before the first start to create the administrator account')
-  const registered = requireInitialized(await iam.user.register({ username: 'admin', password, displayName: serverM('admin') }), 'iam-bootstrap')
+  const registered = requireInitialized(await iam.user.createUser({ username: 'admin', password, displayName: serverM('admin') }), 'iam-bootstrap')
   const adminRole = requireInitialized(await iam.authz.getRoleByCode('admin'), 'iam-role')
   if (!adminRole)
     throw new Error('Administrator role is missing')
@@ -87,7 +91,7 @@ async function ensureRolesAndAdmin(): Promise<void> {
 
 /** 关闭顺序与依赖初始化顺序相反，同时覆盖启动失败路径。 */
 export async function closeModules(): Promise<void> {
-  for (const [name, module] of [['audit', audit], ['iam', iam], ['storage', storage], ['crypto', crypto], ['cache', cache], ['reldb', reldb]] as const) {
+  for (const [name, module] of [['audit', audit], ['iam', iam], ['reach', reach], ['storage', storage], ['crypto', crypto], ['cache', cache], ['reldb', reldb]] as const) {
     if (!module.isInitialized)
       continue
     const result = await module.close()