@h-ai/iam 0.1.0-alpha.69 → 0.1.0-alpha.71

package/README.en.md

@@ -882,6 +882,10 @@ Sessions and refresh consumption share one versioned `hai:iam:sessions:{SHA256(u
 
 `iam.session.update(token, patch, expectedVersion)` requires the Session.version from the read. Stale versions return CONFLICT; revoked tokens return SESSION_NOT_FOUND. Timestamp-only sliding updates keep the content version, allowing normal parallel requests. Batch permission updates bind the initial token/version set and never apply delayed snapshots to later sign-ins; newer content versions require re-reading authorization before retry.
 
+## Schema and credential notifications
+
+After RelDB initialization, `migrateIam({ dryRun: true })` previews changes without writes. iam.init upgrades supported credential/reset columns, retaining users/passwords and permissions. Back up and stop old writers first. Legacy sessions without credential versions must sign in again; never roll back credential generations to restore authorization. Default Reach notifications use sensitive/expiresAt/idempotencyKey without plaintext persistence or delayed replay. Custom callbacks must enforce the same expiry and credential protection.
+
 ## Development and testing
 
 Public examples import from `@h-ai/iam` and distinguish defaultable `IamConfigInput` from parsed `IamConfig`. Initialize server dependencies, check `HaiResult.success`, update sessions with their observed `version`, and reuse persistent notification idempotency keys. Strategy/repository examples marked as internal context do not define application deep imports. The checker verifies types only; Redis/database, LDAP and delivery behavior still require their integration tests. See the [JSDoc conventions (Chinese)](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证).

package/README.ja.md

@@ -878,6 +878,10 @@ if (!result.success) {
 
 `iam.session.update(token, patch, expectedVersion)` は読み取った Session.version が必須です。旧版は CONFLICT、失効 Token は SESSION_NOT_FOUND を返し、新しい状態を上書きしません。自動延長の時刻だけの更新は内容版を変更せず、通常の並行リクエストを許容します。権限一括更新は最初の Token/版集合に限定し、後続ログインに古い値を適用しません。
 
+## スキーマと認証情報の通知
+
+RelDB 初期化後の `migrateIam({ dryRun: true })` は読み取り専用です。iam.init は対応する認証・リセット列を補い、ユーザー、パスワードと権限を保持します。事前に旧書込を停止しバックアップしてください。安全世代のない旧セッションは再ログインが必要で、認可復元のため世代を戻してはいけません。既定 Reach 通知は sensitive/expiresAt/idempotencyKey で平文保存や遅延再送を防ぎます。独自コールバックも同じ期限と保護を守ってください。
+
 ## 開発とテスト
 
 公開例は `@h-ai/iam` を使用し、既定値を省略できる `IamConfigInput` と解析済み `IamConfig` を区別します。依存を先に初期化し、`HaiResult.success` を確認し、会話更新には読取時の `version`、通知には永続的な冪等キーを使います。「模块内部上下文」の戦略・倉庫例はアプリ向け深い import の契約ではありません。チェッカーは型だけを確認し、Redis/DB・LDAP・配送の動作には対応する統合テストが必要です。[JSDoc 規約](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证)も参照してください。

package/README.md

@@ -891,6 +891,10 @@ if (!result.success) {
 
 `iam.session.update(token, patch, expectedVersion)` 必须传入读取到的 Session.version。旧版本返回 CONFLICT，已撤销 token 返回 SESSION_NOT_FOUND；不会将旧内容重新写回或覆盖新会话。仅滑动时间戳更新不改变内容版本，允许正常并行请求。批量权限更新绑定首次读取的 token/版本集合，不将迟到数据应用到后续登录；遇到较新内容版本失败，调用方重新查询授权后再提交。
 
+## 持久结构与凭据通知
+
+`migrateIam({ dryRun: true })` 在 RelDB 初始化后只读预检；iam.init 自动补齐支持版本的凭据/重置字段，保留用户与密码，不修改业务权限。升级前备份停旧写入；没有安全代次的旧会话需重新登录，不能回退数据库安全代次来恢复授权。默认 Reach 通知使用 sensitive/expiresAt/idempotencyKey，不落明文、不延迟重投；自定义回调同样须遵守有效期与凭据保护。
+
 ## 开发测试
 
 公开示例从 `@h-ai/iam` 导入，区分可省略默认值的 `IamConfigInput` 与 Schema 解析后的 `IamConfig`。服务端依赖先初始化；`HaiResult` 先检查 `success`，会话修改使用读取到的 `version`，通知复用持久幂等键。内部策略/仓储示例标记为“模块内部上下文”，不作为应用的深层导入入口。检查器只验证示例类型；真实 Redis/数据库、LDAP 和通知投递仍需对应集成测试。见[模块 JSDoc 约定](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证)。

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { IamFunctions } from './browser.js';
 export { AgreementConfig, AgreementConfigSchema, AgreementDisplay, ApiKey, ApiKeyConfig, ApiKeyConfigSchema, ApiKeyCredentials, ApiKeyOperations, ApiKeySortDirection, ApiKeySortField, AuthResult, AuthStrategy, AuthStrategyType, AuthStrategyTypeSchema, AuthUiConfig, AuthUiConfigSchema, AuthnOperations, AuthzOperations, ConsumeTicketOptions, ConsumedTicket, CreateApiKeyOptions, CreateApiKeyResult, CreateSessionOptions, Credentials, HaiIamError, IamConfig, IamConfigInput, IamConfigSchema, IamConfigSettingsInput, IamNotificationContext, IamPublicConfig, IssueTicketOptions, IssuedTicket, LdapClientFactory, LdapConfig, LdapConfigSchema, LdapCredentials, ListApiKeysOptions, ListUsersOptions, LoginConfig, LoginConfigSchema, OtpConfig, OtpConfigSchema, OtpCredentials, PasswordConfig, PasswordConfigSchema, PasswordCredentials, PasswordResetConfig, PasswordResetConfigSchema, Permission, PermissionQueryOptions, PermissionType, RbacConfig, RbacConfigSchema, RegisterConfig, RegisterConfigSchema, RegisterOptions, RegisterResult, Role, SecurityConfig, SecurityConfigSchema, Session, SessionConfig, SessionConfigSchema, SessionData, SessionFieldUpdates, SessionOperations, StoredUser, TicketGrant, TicketOperations, TokenPair, UpdateCurrentUserInput, User, UserOperations, UserSortDirection, UserSortField } from './browser.js';
+import * as _h_ai_core from '@h-ai/core';
+import * as _h_ai_reldb from '@h-ai/reldb';
 import 'zod';
-import '@h-ai/core';
 import '@h-ai/reach';
-import '@h-ai/reldb';
 
 /**
  * @h-ai/iam — IAM 服务主入口
@@ -29,4 +29,16 @@ import '@h-ai/reldb';
  */
 declare const iam: IamFunctions;
 
-export { IamFunctions, iam };
+/**
+ * 预检或迁移 IAM 表。升级保留用户和密码；旧版无安全代次的会话需重新登录。
+ * @example
+ * ```ts
+ * import { migrateIam } from '@h-ai/iam'
+ * const plan = await migrateIam({ dryRun: true }) // RelDB 已初始化；只读。
+ * ```
+ */
+declare function migrateIam(options?: {
+    dryRun?: boolean;
+}): Promise<_h_ai_core.HaiResult<_h_ai_reldb.SchemaMigrationPlan>>;
+
+export { IamFunctions, iam, migrateIam };

package/dist/index.js

@@ -3,7 +3,7 @@ export { AgreementConfigSchema, ApiKeyConfigSchema, AuthStrategyTypeSchema, Auth
 import { cache } from '@h-ai/cache';
 import { core, err, ok } from '@h-ai/core';
 import { crypto as crypto$1 } from '@h-ai/crypto';
-import { reldb, BaseReldbCrudRepository } from '@h-ai/reldb';
+import { migrateSchema, reldb, schemaColumns, BaseReldbCrudRepository, HaiReldbError } from '@h-ai/reldb';
 import { createHash, randomBytes } from 'crypto';
 import { audit } from '@h-ai/audit';
 
@@ -3168,8 +3168,7 @@ function createRbacManager(config) {
         if (!createResult.success) {
           if (ownTx)
             await tx.rollback();
-          const msg = createResult.error.message.toLowerCase();
-          if (msg.includes("unique") || msg.includes("duplicate")) {
+          if (createResult.error.code === HaiReldbError.DUPLICATE_ENTRY.code) {
             return err(HaiIamError.ROLE_ALREADY_EXISTS, iamM("iam_roleAlreadyExist"));
           }
           return mapRepositoryError2("iam_createRoleFailed", createResult.error.message);
@@ -3208,10 +3207,6 @@ function createRbacManager(config) {
       } catch (error) {
         if (ownTx)
           await tx.rollback();
-        const msg = String(error).toLowerCase();
-        if (msg.includes("unique") || msg.includes("duplicate")) {
-          return err(HaiIamError.ROLE_ALREADY_EXISTS, iamM("iam_roleAlreadyExist"));
-        }
         return err(
           HaiIamError.REPOSITORY_ERROR,
           iamM("iam_createRoleFailed", { params: { message: String(error) } }),
@@ -3396,8 +3391,7 @@ function createRbacManager(config) {
         if (!createResult.success) {
           if (ownTx)
             await tx.rollback();
-          const msg = createResult.error.message.toLowerCase();
-          if (msg.includes("unique") || msg.includes("duplicate")) {
+          if (createResult.error.code === HaiReldbError.DUPLICATE_ENTRY.code) {
             return err(HaiIamError.PERMISSION_ALREADY_EXISTS, iamM("iam_permissionAlreadyExist"));
           }
           return mapRepositoryError2("iam_createPermissionFailed", createResult.error.message);
@@ -3425,10 +3419,6 @@ function createRbacManager(config) {
       } catch (error) {
         if (ownTx)
           await tx.rollback();
-        const msg = String(error).toLowerCase();
-        if (msg.includes("unique") || msg.includes("duplicate")) {
-          return err(HaiIamError.PERMISSION_ALREADY_EXISTS, iamM("iam_permissionAlreadyExist"));
-        }
         return err(
           HaiIamError.REPOSITORY_ERROR,
           iamM("iam_createPermissionFailed", { params: { message: String(error) } }),
@@ -3600,6 +3590,31 @@ function createRbacManager(config) {
     }
   };
 }
+var columns = { credential_version: "VARCHAR(255) NOT NULL DEFAULT ''", reset_version: "VARCHAR(255) NOT NULL DEFAULT ''", reset_hash: "TEXT", reset_expires_at: "BIGINT", reset_attempts: "INTEGER NOT NULL DEFAULT 0" };
+var steps = [{
+  version: 1,
+  name: "credential-and-reset-versions",
+  async needed(sql) {
+    const found = await schemaColumns(reldb, "hai_iam_users", sql);
+    return found.success ? ok(found.data.length > 0 && Object.keys(columns).some((name) => !found.data.includes(name))) : found;
+  },
+  async apply(sql) {
+    const found = await schemaColumns(reldb, "hai_iam_users", sql);
+    if (!found.success)
+      return found;
+    for (const [name, definition] of Object.entries(columns)) {
+      if (found.data.includes(name))
+        continue;
+      const added = await sql.execute(`ALTER TABLE hai_iam_users ADD COLUMN ${name} ${definition}`);
+      if (!added.success)
+        return added;
+    }
+    return ok(void 0);
+  }
+}];
+function migrateIam(options = {}) {
+  return migrateSchema(reldb, "iam", steps, options);
+}
 
 // src/iam-notifications.ts
 async function resolveIamNotifications(input) {
@@ -3620,7 +3635,7 @@ async function resolveIamNotifications(input) {
     const provider = configured.get(template);
     if (!reach?.isInitialized || !provider || !to)
       throw new Error(iamM("iam_passwordResetDeliveryFailed"));
-    const result = await reach.send({ provider, to, template, vars, idempotencyKey: context.idempotencyKey });
+    const result = await reach.send({ provider, to, template, vars, idempotencyKey: context.idempotencyKey, sensitive: true, expiresAt: context.expiresAt.getTime() });
     if (!result.success || !result.data.success)
       throw new Error(iamM("iam_passwordResetDeliveryFailed"));
   }
@@ -4359,15 +4374,14 @@ function mapRepositoryError(messageKey, message) {
     iamM(messageKey, { params: { message } })
   );
 }
-function mapUpdateErrorAsDomainError(message) {
-  const loweredMessage = message.toLowerCase();
-  if (loweredMessage.includes("unique") || loweredMessage.includes("duplicate")) {
+function mapUpdateErrorAsDomainError(error) {
+  if (error.code === HaiReldbError.DUPLICATE_ENTRY.code) {
     return err(
       HaiIamError.USER_ALREADY_EXISTS,
       iamM("iam_userAlreadyExist")
     );
   }
-  return mapRepositoryError("iam_updateUserFailed", message);
+  return mapRepositoryError("iam_updateUserFailed", error.message);
 }
 async function validateUniqueFieldsForUpdate(userRepository, userId, data) {
   const currentResult = await userRepository.findById(userId);
@@ -4471,7 +4485,7 @@ function buildRegistrationOps(ctx) {
     }, tx);
     if (!createResult.success) {
       await tx.rollback();
-      return mapUpdateErrorAsDomainError(createResult.error.message);
+      return mapUpdateErrorAsDomainError(createResult.error);
     }
     const createdUserResult = await userRepository.findByUsername(options.username, tx);
     if (!createdUserResult.success || !createdUserResult.data) {
@@ -4658,7 +4672,7 @@ function buildUserMutationOps(ctx) {
       }
       const updateResult = await userRepository.updateById(userId, safeData);
       if (!updateResult.success) {
-        return mapUpdateErrorAsDomainError(updateResult.error.message);
+        return mapUpdateErrorAsDomainError(updateResult.error);
       }
       if (updateResult.data.changes === 0) {
         return err(
@@ -4698,7 +4712,7 @@ function buildUserMutationOps(ctx) {
       }
       const updateResult = await userRepository.updateById(userId, data);
       if (!updateResult.success) {
-        return mapUpdateErrorAsDomainError(updateResult.error.message);
+        return mapUpdateErrorAsDomainError(updateResult.error);
       }
       if (updateResult.data.changes === 0) {
         return err(
@@ -5042,6 +5056,9 @@ var iam = {
       const parsed = parseResult.data;
       const { onPasswordResetRequest, onOtpSendEmail, onOtpSendSms } = await resolveIamNotifications(config);
       logger11.info("IAM notification channels resolved", { email: Boolean(onOtpSendEmail), sms: Boolean(onOtpSendSms), passwordReset: Boolean(onPasswordResetRequest) });
+      const migration = await migrateIam();
+      if (!migration.success)
+        return migration;
       const credentialUsers = await createDbUserRepository();
       const sessionResult = await createSessionOperations({
         config: parsed,
@@ -5171,6 +5188,6 @@ var iam = {
   }
 };
 
-export { iam };
+export { iam, migrateIam };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map