@gong-ym/ai-spec-auto 0.2.3

package/src/governance/audit-log.js

@@ -0,0 +1,368 @@
+/**
+ * P3.3 审计日志 — 内存模型 + NDJSON 最小文件持久化
+ *
+ * 审计事件 schema、写入、查询、红脱策略、NDJSON 文件持久化
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ============================================================
+// 审计事件类型
+// ============================================================
+
+const AUDIT_EVENT_TYPES = Object.freeze({
+  ASSET_CHANGE: 'asset_change',
+  PERMISSION_CHANGE: 'permission_change',
+  POLICY_DENIED: 'policy_denied',
+  GRAY_RELEASE: 'gray_release',
+  ROLLBACK: 'rollback',
+  REVIEW_ACTION: 'review_action',
+  SECURITY_SCAN: 'security_scan',
+});
+
+const AUDIT_SEVERITY = Object.freeze({
+  INFO: 'info',
+  WARN: 'warn',
+  ERROR: 'error',
+  BLOCKING: 'blocking',
+});
+
+const AUDIT_RESULT = Object.freeze({
+  SUCCESS: 'success',
+  DENIED: 'denied',
+  ERROR: 'error',
+});
+
+const VALID_EVENT_TYPES = new Set(Object.values(AUDIT_EVENT_TYPES));
+const VALID_SEVERITY = new Set(Object.values(AUDIT_SEVERITY));
+const VALID_RESULT = new Set(Object.values(AUDIT_RESULT));
+
+// ============================================================
+// 敏感信息红脱（复用 P2 模式）
+// ============================================================
+
+const SENSITIVE_PATTERNS = [
+  { pattern: /password\s*[=:]\s*["'][^"']*["']/gi, replacement: 'password=[REDACTED]' },
+  { pattern: /password\s*[=:]\s*\S+/gi, replacement: 'password=[REDACTED]' },
+  { pattern: /api[_-]?key\s*[=:]\s*["'][^"']*["']/gi, replacement: 'api_key=[REDACTED]' },
+  { pattern: /api[_-]?key\s*[=:]\s*\S+/gi, replacement: 'api_key=[REDACTED]' },
+  { pattern: /secret\s*[=:]\s*["'][^"']*["']/gi, replacement: 'secret=[REDACTED]' },
+  { pattern: /secret\s*[=:]\s*\S+/gi, replacement: 'secret=[REDACTED]' },
+  { pattern: /token\s*[=:]\s*["'][^"']*["']/gi, replacement: 'token=[REDACTED]' },
+  { pattern: /token\s*[=:]\s*\S+/gi, replacement: 'token=[REDACTED]' },
+  { pattern: /access[_-]?key\s*[=:]\s*["'][^"']*["']/gi, replacement: 'access_key=[REDACTED]' },
+  { pattern: /access[_-]?key\s*[=:]\s*\S+/gi, replacement: 'access_key=[REDACTED]' },
+  { pattern: /private[_-]?key\s*[=:]\s*["'][^"']*["']/gi, replacement: 'private_key=[REDACTED]' },
+  { pattern: /private[_-]?key\s*[=:]\s*\S+/gi, replacement: 'private_key=[REDACTED]' },
+];
+
+function redactSensitive(text) {
+  if (typeof text !== 'string') return text;
+  let result = text;
+  for (const { pattern, replacement } of SENSITIVE_PATTERNS) {
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+}
+
+const SENSITIVE_KEY_PATTERNS = /^(password|api[_-]?key|secret|token|access[_-]?key|private[_-]?key|raw[_-]?prompt)$/i;
+
+function redactObject(obj) {
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj === 'string') return redactSensitive(obj);
+  if (typeof obj !== 'object') return obj;
+  if (Array.isArray(obj)) return obj.map(redactObject);
+
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (SENSITIVE_KEY_PATTERNS.test(key)) {
+      result[key] = '[REDACTED]';
+    } else if (typeof value === 'string') {
+      result[key] = redactSensitive(value);
+    } else if (typeof value === 'object' && value !== null) {
+      result[key] = redactObject(value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+// ============================================================
+// 审计日志类
+// ============================================================
+
+class AuditLog {
+  constructor(options = {}) {
+    /** @type {object[]} */
+    this.entries = [];
+    /** @type {number} */
+    this._nextEventId = 1;
+    /** @type {number} */
+    this._maxEntries = options.maxEntries || 10000;
+    /** @type {string|null} */
+    this.storagePath = options.storagePath || null;
+    /** @type {boolean} */
+    this.loadExisting = options.loadExisting !== false;
+    /** @type {boolean} */
+    this.appendOnRecord = options.appendOnRecord !== false;
+    /** @type {object[]} */
+    this.loadErrors = [];
+
+    // 指定 storagePath 且 loadExisting 不为 false 时，加载历史记录
+    if (this.storagePath && this.loadExisting) {
+      this.loadFromFile();
+    }
+  }
+
+  /**
+   * 从 NDJSON 文件加载历史记录
+   * @returns {object[]} 加载的记录
+   */
+  loadFromFile() {
+    if (!this.storagePath) return [];
+
+    try {
+      if (!fs.existsSync(this.storagePath)) return [];
+    } catch {
+      return [];
+    }
+
+    let content;
+    try {
+      content = fs.readFileSync(this.storagePath, 'utf-8');
+    } catch {
+      return [];
+    }
+
+    if (!content || !content.trim()) return [];
+
+    const lines = content.split('\n');
+    const loaded = [];
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (!line) continue;
+
+      try {
+        const entry = JSON.parse(line);
+        loaded.push(entry);
+
+        // 恢复 eventId 编号
+        if (entry.eventId && typeof entry.eventId === 'string') {
+          const match = entry.eventId.match(/^audit-(\d+)$/);
+          if (match) {
+            const num = parseInt(match[1], 10);
+            if (num >= this._nextEventId) {
+              this._nextEventId = num + 1;
+            }
+          }
+        }
+      } catch (err) {
+        this.loadErrors.push({
+          lineNumber: i + 1,
+          line: line.substring(0, 200),
+          message: err.message || 'JSON 解析失败',
+        });
+      }
+    }
+
+    // 应用 maxEntries 约束
+    this.entries = loaded.length > this._maxEntries
+      ? loaded.slice(-this._maxEntries)
+      : loaded;
+
+    return this.entries;
+  }
+
+  /**
+   * 追加一条已红脱的 entry 到 NDJSON 文件
+   * @param {object} entry
+   */
+  appendToFile(entry) {
+    if (!this.storagePath) return;
+    if (this.appendOnRecord === false) return;
+
+    const dir = path.dirname(this.storagePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    const line = JSON.stringify(entry) + '\n';
+    fs.appendFileSync(this.storagePath, line, 'utf-8');
+  }
+
+  /**
+   * 写入审计事件（自动红脱）
+   * @param {object} params
+   * @returns {object} 审计记录
+   */
+  record({ eventType, actor, target, action, result, severity = 'info', message = '', metadata = {} }) {
+    if (!eventType || !VALID_EVENT_TYPES.has(eventType)) {
+      throw new Error(`无效事件类型: ${eventType}，必须是 ${[...VALID_EVENT_TYPES].join(', ')} 之一`);
+    }
+    if (!VALID_SEVERITY.has(severity)) {
+      throw new Error(`无效严重级别: ${severity}，必须是 ${[...VALID_SEVERITY].join(', ')} 之一`);
+    }
+    if (result && !VALID_RESULT.has(result)) {
+      throw new Error(`无效结果: ${result}，必须是 ${[...VALID_RESULT].join(', ')} 之一`);
+    }
+
+    const entry = {
+      eventId: `audit-${this._nextEventId++}`,
+      eventType,
+      actor: actor || 'system',
+      target: target || '',
+      action: action || '',
+      result: result || 'success',
+      severity,
+      message: redactSensitive(message || ''),
+      metadata: redactObject(metadata || {}),
+      timestamp: new Date().toISOString(),
+    };
+
+    this.entries.push(entry);
+
+    // 超出上限时移除最旧的
+    if (this.entries.length > this._maxEntries) {
+      this.entries = this.entries.slice(-this._maxEntries);
+    }
+
+    // 追加到文件（使用已红脱的 entry）
+    this.appendToFile(entry);
+
+    return { ...entry, metadata: { ...entry.metadata } };
+  }
+
+  /**
+   * 查询审计日志
+   * @param {object} filters
+   * @returns {object[]}
+   */
+  query({ eventType, actor, target, result, severity, from, to, limit = 100 } = {}) {
+    let filtered = this.entries;
+
+    if (eventType) {
+      filtered = filtered.filter(e => e.eventType === eventType);
+    }
+    if (actor) {
+      filtered = filtered.filter(e => e.actor === actor);
+    }
+    if (target) {
+      filtered = filtered.filter(e => e.target === target);
+    }
+    if (result) {
+      filtered = filtered.filter(e => e.result === result);
+    }
+    if (severity) {
+      filtered = filtered.filter(e => e.severity === severity);
+    }
+    if (from) {
+      filtered = filtered.filter(e => e.timestamp >= from);
+    }
+    if (to) {
+      filtered = filtered.filter(e => e.timestamp <= to);
+    }
+
+    return filtered.slice(-limit).map(e => ({ ...e, metadata: { ...e.metadata } }));
+  }
+
+  /**
+   * 按事件类型统计
+   * @returns {object}
+   */
+  getStats() {
+    const byType = {};
+    const bySeverity = {};
+    const byResult = {};
+
+    for (const entry of this.entries) {
+      byType[entry.eventType] = (byType[entry.eventType] || 0) + 1;
+      bySeverity[entry.severity] = (bySeverity[entry.severity] || 0) + 1;
+      byResult[entry.result] = (byResult[entry.result] || 0) + 1;
+    }
+
+    return {
+      total: this.entries.length,
+      byType,
+      bySeverity,
+      byResult,
+    };
+  }
+
+  /**
+   * 导出审计日志
+   * @param {string} format - 'json' | 'ndjson'
+   * @returns {string}
+   */
+  export(format = 'json') {
+    if (format === 'ndjson') {
+      return this.entries.map(e => JSON.stringify(e)).join('\n');
+    }
+    return JSON.stringify(this.entries, null, 2);
+  }
+
+  /**
+   * 清空审计日志（同时清空内存和持久化文件）
+   */
+  clear() {
+    this.entries = [];
+    this._nextEventId = 1;
+    this.loadErrors = [];
+
+    if (this.storagePath) {
+      const dir = path.dirname(this.storagePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      fs.writeFileSync(this.storagePath, '', 'utf-8');
+    }
+  }
+
+  /**
+   * 获取坏行加载错误
+   * @returns {object[]}
+   */
+  getLoadErrors() {
+    return this.loadErrors.map(e => ({ ...e }));
+  }
+
+  /**
+   * 条目数量
+   * @returns {number}
+   */
+  get size() {
+    return this.entries.length;
+  }
+
+  /**
+   * 导出为 JSON
+   * @returns {object[]}
+   */
+  toJSON() {
+    return this.entries.map(e => ({ ...e, metadata: { ...e.metadata } }));
+  }
+}
+
+/**
+ * 工厂函数
+ * @param {object} [options]
+ * @returns {AuditLog}
+ */
+function createAuditLog(options) {
+  return new AuditLog(options);
+}
+
+module.exports = {
+  AUDIT_EVENT_TYPES,
+  AUDIT_SEVERITY,
+  AUDIT_RESULT,
+  VALID_EVENT_TYPES,
+  VALID_SEVERITY,
+  VALID_RESULT,
+  AuditLog,
+  createAuditLog,
+  redactSensitive,
+  redactObject,
+};

package/src/governance/gray-release.js

@@ -0,0 +1,312 @@
+/**
+ * P3.4 灰度发布
+ *
+ * 灰度规则引擎：按组织/团队/项目/百分比发布资产版本
+ */
+
+// ============================================================
+// 常量
+// ============================================================
+
+const GRAY_SCOPE_TYPES = Object.freeze({
+  ORG: 'org',
+  TEAM: 'team',
+  PROJECT: 'project',
+  PERCENTAGE: 'percentage',
+});
+
+const GRAY_STATUS = Object.freeze({
+  ACTIVE: 'active',
+  RECLAIMED: 'reclaimed',
+  EXPANDED: 'expanded',
+  FULLY_RELEASED: 'fully_released',
+});
+
+const VALID_SCOPE_TYPES = new Set(Object.values(GRAY_SCOPE_TYPES));
+const VALID_GRAY_STATUS = new Set(Object.values(GRAY_STATUS));
+
+// ============================================================
+// 灰度发布引擎
+// ============================================================
+
+class GrayReleaseEngine {
+  constructor() {
+    /** @type {Map<string, object>} grayReleaseId → 灰度发布记录 */
+    this.releases = new Map();
+    /** @type {Map<string, object[]>} assetId → 灰度规则[] */
+    this.rules = new Map();
+    /** @type {number} */
+    this._nextRuleId = 1;
+    /** @type {number} */
+    this._nextReleaseId = 1;
+  }
+
+  /**
+   * 创建灰度规则
+   * @param {object} params
+   * @returns {object} 灰度规则
+   */
+  createGrayRule({ assetId, version, scope, scopeValue, percentage, rollbackVersion = null }) {
+    if (!assetId || !version || !scope) {
+      throw new Error('assetId, version, scope 必填');
+    }
+    if (!VALID_SCOPE_TYPES.has(scope)) {
+      throw new Error(`无效范围类型: ${scope}，必须是 ${[...VALID_SCOPE_TYPES].join(', ')} 之一`);
+    }
+    if (scope === 'percentage') {
+      if (typeof percentage !== 'number' || percentage < 0 || percentage > 100) {
+        throw new Error('百分比范围必须是 0-100 的数字');
+      }
+    } else {
+      if (!scopeValue) {
+        throw new Error('非百分比范围必须提供 scopeValue');
+      }
+    }
+
+    const ruleId = `gray-rule-${this._nextRuleId++}`;
+    const rule = {
+      ruleId,
+      assetId,
+      version,
+      scope,
+      scopeValue: scopeValue || null,
+      percentage: scope === 'percentage' ? percentage : null,
+      rollbackVersion,
+      createdAt: new Date().toISOString(),
+    };
+
+    if (!this.rules.has(assetId)) {
+      this.rules.set(assetId, []);
+    }
+    this.rules.get(assetId).push(rule);
+
+    return { ...rule };
+  }
+
+  /**
+   * 创建灰度发布
+   * @param {object} params
+   * @returns {object} 灰度发布记录
+   */
+  createGrayRelease({ assetId, version, rules, createdBy, metadata = {} }) {
+    if (!assetId || !version || !createdBy) {
+      throw new Error('assetId, version, createdBy 必填');
+    }
+    if (!rules || !Array.isArray(rules) || rules.length === 0) {
+      throw new Error('rules 必填且不能为空');
+    }
+
+    // 检查约束：无 rollbackVersion 时不允许 100% 灰度
+    const hasFullPercentage = rules.some(r => r.scope === 'percentage' && r.percentage === 100);
+    if (hasFullPercentage) {
+      const hasRollback = rules.some(r => r.rollbackVersion);
+      if (!hasRollback) {
+        throw new Error('无 rollbackVersion 的资产不允许 100% 灰度发布');
+      }
+    }
+
+    const releaseId = `gray-${this._nextReleaseId++}`;
+    const now = new Date().toISOString();
+
+    const release = {
+      releaseId,
+      assetId,
+      version,
+      rules: rules.map(r => ({ ...r })),
+      status: GRAY_STATUS.ACTIVE,
+      createdBy,
+      metadata,
+      createdAt: now,
+      updatedAt: now,
+      reclaimedAt: null,
+      reclaimReason: null,
+    };
+
+    this.releases.set(releaseId, release);
+
+    return { ...release, rules: release.rules.map(r => ({ ...r })) };
+  }
+
+  /**
+   * 评估上下文是否命中灰度
+   * @param {string} releaseId
+   * @param {object} context - { org?, team?, project?, userId? }
+   * @returns {object} { matched: boolean, matchedRule?, reason? }
+   */
+  evaluateScope(releaseId, context) {
+    const release = this.releases.get(releaseId);
+    if (!release) return { matched: false, reason: `灰度发布 ${releaseId} 不存在` };
+    if (release.status !== GRAY_STATUS.ACTIVE) {
+      return { matched: false, reason: `灰度发布状态为 ${release.status}，不可评估` };
+    }
+
+    for (const rule of release.rules) {
+      if (this._matchRule(rule, context)) {
+        return { matched: true, matchedRule: { ...rule } };
+      }
+    }
+
+    return { matched: false, reason: '未命中任何灰度规则' };
+  }
+
+  /**
+   * 获取灰度状态
+   * @param {string} releaseId
+   * @returns {object|null}
+   */
+  getGrayStatus(releaseId) {
+    const release = this.releases.get(releaseId);
+    if (!release) return null;
+    return { ...release, rules: release.rules.map(r => ({ ...r })) };
+  }
+
+  /**
+   * 回收灰度发布（回退到 rollbackVersion）
+   * @param {string} releaseId
+   * @param {string} reason
+   * @returns {object} { ok, release?, error? }
+   */
+  reclaimGrayRelease(releaseId, reason) {
+    if (!reason) return { ok: false, error: '回收原因必填' };
+
+    const release = this.releases.get(releaseId);
+    if (!release) return { ok: false, error: `灰度发布 ${releaseId} 不存在` };
+    if (release.status !== GRAY_STATUS.ACTIVE && release.status !== GRAY_STATUS.EXPANDED) {
+      return { ok: false, error: `灰度发布状态为 ${release.status}，不可回收` };
+    }
+
+    release.status = GRAY_STATUS.RECLAIMED;
+    release.reclaimReason = reason;
+    release.reclaimedAt = new Date().toISOString();
+    release.updatedAt = new Date().toISOString();
+
+    return { ok: true, release: { ...release, rules: release.rules.map(r => ({ ...r })) } };
+  }
+
+  /**
+   * 扩大灰度范围
+   * @param {string} releaseId
+   * @param {number} newPercentage
+   * @returns {object} { ok, release?, error? }
+   */
+  expandGrayRelease(releaseId, newPercentage) {
+    if (typeof newPercentage !== 'number' || newPercentage < 0 || newPercentage > 100) {
+      return { ok: false, error: '百分比必须是 0-100 的数字' };
+    }
+
+    const release = this.releases.get(releaseId);
+    if (!release) return { ok: false, error: `灰度发布 ${releaseId} 不存在` };
+    if (release.status !== GRAY_STATUS.ACTIVE) {
+      return { ok: false, error: `灰度发布状态为 ${release.status}，不可扩展` };
+    }
+
+    // 找到百分比规则并更新
+    let found = false;
+    for (const rule of release.rules) {
+      if (rule.scope === 'percentage') {
+        if (newPercentage < rule.percentage) {
+          return { ok: false, error: '新百分比不能小于当前百分比' };
+        }
+        rule.percentage = newPercentage;
+        found = true;
+      }
+    }
+
+    if (!found) {
+      return { ok: false, error: '未找到百分比类型的灰度规则' };
+    }
+
+    release.status = newPercentage === 100 ? GRAY_STATUS.FULLY_RELEASED : GRAY_STATUS.EXPANDED;
+    release.updatedAt = new Date().toISOString();
+
+    return { ok: true, release: { ...release, rules: release.rules.map(r => ({ ...r })) } };
+  }
+
+  /**
+   * 列出灰度发布
+   * @param {string} [assetId]
+   * @returns {object[]}
+   */
+  listGrayReleases(assetId) {
+    const result = [];
+    for (const release of this.releases.values()) {
+      if (!assetId || release.assetId === assetId) {
+        result.push({ ...release, rules: release.rules.map(r => ({ ...r })) });
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 获取统计
+   * @returns {object}
+   */
+  getStats() {
+    const byStatus = {};
+    for (const release of this.releases.values()) {
+      byStatus[release.status] = (byStatus[release.status] || 0) + 1;
+    }
+    return {
+      totalReleases: this.releases.size,
+      totalRules: [...this.rules.values()].reduce((sum, arr) => sum + arr.length, 0),
+      byStatus,
+    };
+  }
+
+  /**
+   * 重置
+   */
+  reset() {
+    this.releases.clear();
+    this.rules.clear();
+    this._nextRuleId = 1;
+    this._nextReleaseId = 1;
+  }
+
+  // ============================================================
+  // 内部方法
+  // ============================================================
+
+  _matchRule(rule, context) {
+    switch (rule.scope) {
+      case 'org':
+        return context.org === rule.scopeValue;
+      case 'team':
+        return context.team === rule.scopeValue;
+      case 'project':
+        return context.project === rule.scopeValue;
+      case 'percentage': {
+        // 基于 userId 的确定性哈希分配
+        const hash = this._simpleHash(context.userId || '');
+        return (hash % 100) < rule.percentage;
+      }
+      default:
+        return false;
+    }
+  }
+
+  _simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      hash = ((hash << 5) - hash + str.charCodeAt(i)) | 0;
+    }
+    return Math.abs(hash);
+  }
+}
+
+/**
+ * 工厂函数
+ * @returns {GrayReleaseEngine}
+ */
+function createGrayReleaseEngine() {
+  return new GrayReleaseEngine();
+}
+
+module.exports = {
+  GRAY_SCOPE_TYPES,
+  GRAY_STATUS,
+  VALID_SCOPE_TYPES,
+  VALID_GRAY_STATUS,
+  GrayReleaseEngine,
+  createGrayReleaseEngine,
+};

package/src/governance/index.js

@@ -0,0 +1,31 @@
+/**
+ * Governance 模块 barrel 导出
+ */
+
+const rbacTypes = require('./rbac-types');
+const rbac = require('./rbac');
+const assetReview = require('./asset-review');
+const auditLog = require('./audit-log');
+const grayRelease = require('./gray-release');
+const rollback = require('./rollback');
+const policyTypes = require('./policy-types');
+const securityPolicy = require('./security-policy');
+
+module.exports = {
+  // 类型与常量
+  ...rbacTypes,
+  // RBAC 权限模型
+  ...rbac,
+  // 资产审核工作流
+  ...assetReview,
+  // 审计日志
+  ...auditLog,
+  // 灰度发布
+  ...grayRelease,
+  // 版本回滚
+  ...rollback,
+  // 安全策略类型
+  ...policyTypes,
+  // 安全策略引擎
+  ...securityPolicy,
+};