@vnptnan/gate 0.0.0-stage → 1.0.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# VNPTNAN_GATE: Cổng kiểm soát ATBMTT khi dùng AI trong phát triển phần mềm
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Chặn secret, dữ liệu cá nhân khách hàng, file cấm và package đáng ngờ **trước khi chúng rời máy dev**. Cổng chạy ở năm điểm:
+
+| Điểm | Cơ chế |
+|---|---|
+| 0 · Gửi prompt | Hook `UserPromptSubmit` của Claude Code, Codex (`engine/prompt-check.sh`) |
+| 1 · Commit | `pre-commit`: quét các dòng được thêm |
+| 2 · Push | `pre-push`: quét mọi commit sắp rời máy, kể cả commit tạo bằng lệnh plumbing |
+| 3 · Máy chủ GitLab | `pre-receive`: chặn cả máy chưa cài gì, có ở GitLab bản Free, không cần CI |
+| 4 · CI | Mẫu `ci/.gitlab-ci.yml`: quét toàn cây, dependency |
+
+Cổng không dùng AI để quyết định. Có 43 rule regex tiếng Việt (`rules/gate.rules`, id `g-`), một engine bash dùng chung cho mọi điểm, log luôn che giá trị secret. Bộ này bổ sung cho VNPTNAN_HARNESS (hook trong phiên AI): hai bên dùng tên hook, thư mục, lệnh và id rule khác nhau.
+
+## Cài trên máy dev Windows
+
+Cần Git for Windows và Node.js 16.7 trở lên.
+
+```powershell
+npx -y @vnptnan/gate          # xin quyền admin, cài, tự cập nhật hằng ngày
+vnptnan-gate doctor           # mở terminal mới rồi kiểm tra
+```
+
+| Lệnh | Việc |
+|---|---|
+| `npx @vnptnan/gate status` | Bản đang cài, bản mới nhất, chế độ, lịch cập nhật |
+| `npx @vnptnan/gate update` | Cập nhật ngay |
+| `npx @vnptnan/gate --audit` | Cố định chế độ chỉ ghi log trên máy này (mặc định theo `policy.json` của bản phát hành) |
+| `npx @vnptnan/gate uninstall` | Gỡ |
+
+Máy không có Node: tải `VNPTNAN_GATE-<ver>-setup.cmd` ở trang Releases, nhấp đúp.
+
+Máy chủ GitLab: tải `VNPTNAN_GATE-<ver>.zip` ở trang Releases, giải nén, rồi chạy `sudo bash installer/install-server.sh -mode audit`.
+
+## Dùng hằng ngày
+
+`vnptnan-gate scan` · `scan tree` · `scan range A B` · `deps` · `test "<dòng>"` · `report [ngày]` · `doctor` · `tools` · `install-hooks`
+
+Bị chặn nhầm thì khai ngoại lệ, không dùng `--no-verify`:
+- trên dòng: `gate-allow:<id> <lý do>`;
+- theo đường dẫn: `.vnptnan-gate/allow.rules`, qua merge request có người duyệt.
+
+## Phát triển và phát hành
+
+```bash
+bash tests/run-tests.sh      # 94 ca: rule, hook, pre-receive, prompt
+bash tools/lint-rules.sh
+```
+
+Mỗi push chạy GitHub Actions (`ci.yml`): kiểm thử trên Linux, rồi cài thật trên Windows và kiểm tra hook chặn secret. Phát hành bằng cách tăng `VERSION` rồi đẩy tag `vX.Y.Z`: `release.yml` chạy lại toàn bộ kiểm thử, `npm publish --provenance` và tạo GitHub Release. Chi tiết trong `npm/README.md`.
+
+Giấy phép MIT.

package/VERSION

@@ -0,0 +1 @@
+1.0.1

package/bin/cli.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+// VNPTNAN_GATE - cài đặt và tự cập nhật qua npm (mặc định npmjs.com; đổi kho bằng npm config @vnptnan:registry hoặc --registry).
+//   npx @vnptnan/gate                 cài hoặc cài lại (xin quyền admin qua UAC), đăng ký tự cập nhật hằng ngày
+//   npx @vnptnan/gate --audit|--enforce   cài và cố định chế độ trên máy này (mặc định: theo policy.json của gói)
+//   npx @vnptnan/gate status          phiên bản đang cài, bản mới nhất trên kho, chế độ, lịch cập nhật
+//   npx @vnptnan/gate update [--check]    cập nhật ngay (lịch tự chạy lệnh này bằng tài khoản SYSTEM)
+//   npx @vnptnan/gate uninstall       gỡ cổng và lịch cập nhật
+// Tuỳ chọn: --registry URL, --ca FILE (CA khi dùng kho nội bộ tự ký), --token T (khi kho cần đăng nhập).
+// Không phụ thuộc gói ngoài. Cổng chạy bằng bash như trước; Node chỉ dùng để tải, kiểm tra và cài.
+'use strict';
+const fs = require('fs'), path = require('path'), cp = require('child_process'), zlib = require('zlib');
+const crypto = require('crypto'), tls = require('tls'), https = require('https'), http = require('http');
+
+const ROOT = path.resolve(__dirname, '..');
+const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+const IS_WIN = process.platform === 'win32';
+const HOME = path.join(process.env.ProgramData || 'C:\\ProgramData', 'VNPTNAN_GATE');
+const CFG = path.join(HOME, 'update.json');
+const LOG = path.join(HOME, 'logs', 'update.log');
+const TASK = 'VNPTNAN_GATE Update';
+
+// ------------------------------------------------------------------ tham số
+const argv = process.argv.slice(2);
+const cmd = argv[0] && !argv[0].startsWith('-') ? argv.shift() : 'setup';
+const opt = {};
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--audit' || a === '--enforce') opt.mode = a.slice(2);
+  else if (a === '--check' || a === '--quiet' || a === '--elevated') opt[a.slice(2)] = true;
+  else if (['--registry', '--ca', '--token', '--stage-only'].includes(a)) opt[a.slice(2).replace('-o', 'O')] = argv[++i];
+  else die(`Tham số không hiểu: ${a}`);
+}
+
+function say(s) { if (!opt.quiet) console.log(s); log(s); }
+function log(s) { try { fs.mkdirSync(path.dirname(LOG), { recursive: true }); fs.appendFileSync(LOG, `${new Date().toISOString()}\t${s}\n`); } catch (_) { /* chưa có quyền ghi */ } }
+function die(s, code = 1) { console.error(`[VNPTNAN_GATE] ${s}`); log(`LOI\t${s}`); process.exit(code); }
+function readJson(p) { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return null; } }
+const cmpVer = (a, b) => { const x = a.split(/[.-]/).map(Number), y = b.split(/[.-]/).map(Number); for (let i = 0; i < 3; i++) if ((x[i] || 0) !== (y[i] || 0)) return (x[i] || 0) - (y[i] || 0); return 0; };
+
+// ------------------------------------------------------------------ cấu hình kho gói
+function npmConfig(key) { try { return cp.execSync(`npm config get ${key}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch (_) { return ''; } }
+function settings() {
+  const saved = readJson(CFG) || {};
+  const scope = PKG.name.split('/')[0];
+  let registry = opt.registry || saved.registry || npmConfig(`${scope}:registry`);
+  if (!registry || registry === 'undefined') registry = PKG.publishConfig && PKG.publishConfig.registry;
+  if (!registry) die('Chưa biết địa chỉ kho gói. Chạy lại với --registry <URL Package Registry của GitLab>.');
+  const ca = opt.ca || saved.ca || process.env.NODE_EXTRA_CA_CERTS || '';
+  return { name: PKG.name, registry: registry.replace(/\/?$/, '/'), ca, token: opt.token || saved.token || '', mode: opt.mode || saved.mode || '' };
+}
+
+// ------------------------------------------------------------------ HTTP (có CA nội bộ, theo redirect)
+function get(url, s, asJson, hops = 0) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url), lib = u.protocol === 'http:' ? http : https;
+    const o = { headers: { 'User-Agent': `vnptnan-gate/${PKG.version}`, Accept: asJson ? 'application/json' : '*/*' }, timeout: 30000 };
+    if (s.ca && fs.existsSync(s.ca)) o.ca = [...tls.rootCertificates, fs.readFileSync(s.ca, 'utf8')];
+    if (s.token && u.host === new URL(s.registry).host) o.headers.Authorization = `Bearer ${s.token}`;
+    const req = lib.get(u, o, (res) => {
+      if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location && hops < 5) {
+        res.resume(); return resolve(get(new URL(res.headers.location, u).href, s, asJson, hops + 1));
+      }
+      if (res.statusCode !== 200) { res.resume(); return reject(new Error(`HTTP ${res.statusCode} ${u.href}`)); }
+      const chunks = []; res.on('data', (c) => chunks.push(c));
+      res.on('end', () => { const b = Buffer.concat(chunks); try { resolve(asJson ? JSON.parse(b.toString('utf8')) : b); } catch (e) { reject(e); } });
+    });
+    req.on('timeout', () => req.destroy(new Error(`Hết thời gian chờ ${u.host}`))); req.on('error', reject);
+  });
+}
+async function latest(s) {
+  const meta = await get(s.registry + s.name.replace('/', '%2f'), s, true);
+  const ver = meta['dist-tags'] && meta['dist-tags'].latest;
+  if (!ver || !meta.versions || !meta.versions[ver]) throw new Error('Kho gói không có bản latest');
+  return { ver, dist: meta.versions[ver].dist };
+}
+
+// ------------------------------------------------------------------ tải, kiểm tra toàn vẹn, giải nén
+function untar(buf, dest) {
+  let o = 0, n = 0, longName = null, paxPath = null;
+  while (o + 512 <= buf.length) {
+    const h = buf.subarray(o, o + 512);
+    if (h.every((b) => b === 0)) break;
+    const str = (a, b) => h.subarray(a, b).toString('utf8').replace(/\0[\s\S]*$/, '');
+    const size = parseInt(str(124, 136).trim() || '0', 8), type = String.fromCharCode(h[156] || 48);
+    let name = str(345, 500) ? `${str(345, 500)}/${str(0, 100)}` : str(0, 100);
+    const data = buf.subarray(o + 512, o + 512 + size); o += 512 + Math.ceil(size / 512) * 512;
+    if (type === 'x') { const m = /\d+ path=([^\n]*)\n/.exec(data.toString('utf8')); if (m) paxPath = m[1]; continue; }
+    if (type === 'g') continue;
+    if (type === 'L') { longName = data.toString('utf8').replace(/\0[\s\S]*$/, ''); continue; }
+    if (paxPath) { name = paxPath; paxPath = null; } if (longName) { name = longName; longName = null; }
+    name = name.replace(/^package\//, '');
+    if (!name || path.isAbsolute(name) || name.split(/[\\/]/).includes('..')) continue;   // chặn ghi ra ngoài thư mục
+    const p = path.join(dest, name);
+    if (type === '5') { fs.mkdirSync(p, { recursive: true }); continue; }
+    if (type !== '0' && type !== '7') continue;                                              // bỏ link, thiết bị
+    fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, data); n++;
+  }
+  return n;
+}
+async function fetchTo(s, dist, dest) {
+  const tgz = await get(dist.tarball, s, false);
+  if (dist.integrity) {
+    const [alg, want] = dist.integrity.split(/-(.+)/);
+    const got = crypto.createHash(alg).update(tgz).digest('base64');
+    if (got !== want) throw new Error(`Sai mã toàn vẹn (${alg}): gói tải về khác gói trên kho, không cài`);
+  } else if (dist.shasum) {
+    if (crypto.createHash('sha1').update(tgz).digest('hex') !== dist.shasum) throw new Error('Sai shasum, không cài');
+  } else throw new Error('Kho gói không cung cấp mã toàn vẹn, không cài');
+  fs.rmSync(dest, { recursive: true, force: true }); fs.mkdirSync(dest, { recursive: true });
+  const n = untar(zlib.gunzipSync(tgz), dest);
+  for (const f of ['VERSION', 'installer/install.ps1', 'engine/gate-lib.sh', 'bin/cli.js']) {
+    if (!fs.existsSync(path.join(dest, f))) throw new Error(`Gói thiếu ${f}`);
+  }
+  return n;
+}
+
+// ------------------------------------------------------------------ Windows: quyền admin, cài, lịch
+function isAdmin() { try { cp.execSync('net session', { stdio: 'ignore' }); return true; } catch (_) { return false; } }
+// Windows PowerShell 5.1 gọi từ PowerShell 7 (pwsh) kế thừa PSModulePath của bản 7 và nạp nhầm module
+// (Get-Acl, Start-Process lỗi "module could not be loaded"). Bỏ biến này để 5.1 tự dựng lại đường dẫn mặc định.
+const PS_ENV = Object.fromEntries(Object.entries(process.env).filter(([k]) => k.toLowerCase() !== 'psmodulepath'));
+function ps(args) { return cp.spawnSync('powershell.exe', ['-NoProfile', '-ExecutionPolicy', 'Bypass', ...args], { stdio: opt.quiet ? 'ignore' : 'inherit', env: PS_ENV }).status; }
+function elevate(extra) {
+  if (opt.elevated) die('Đã chạy với quyền nâng nhưng vẫn không có quyền admin (net session lỗi). Mở terminal "Run as administrator" rồi chạy lại.');
+  const q = (x) => `'${String(x).replace(/'/g, "''")}'`;
+  const args = [__filename, cmd, ...extra, '--elevated'].map((x) => `'"${String(x).replace(/'/g, "''")}"'`).join(',');
+  say('Đang xin quyền quản trị (UAC)...');
+  const st = cp.spawnSync('powershell.exe', ['-NoProfile', '-Command',
+    `$p = Start-Process -FilePath ${q(process.execPath)} -ArgumentList @(${args}) -Verb RunAs -Wait -PassThru; exit $p.ExitCode`], { stdio: 'inherit', env: PS_ENV }).status;
+  try { const tail = fs.readFileSync(LOG, 'utf8').trim().split('\n').slice(-6).map((l) => l.split('\t').slice(1).join(' ')); console.log(tail.join('\n')); } catch (_) { /* không có log */ }
+  process.exit(st || 0);
+}
+function passArgs(s) {
+  const a = ['--registry', s.registry];
+  if (s.ca) a.push('--ca', path.resolve(s.ca));
+  if (s.token) a.push('--token', s.token);
+  if (opt.mode) a.push(`--${opt.mode}`);
+  return a;
+}
+function installFrom(dir, mode) {
+  const st = ps(['-File', path.join(dir, 'installer', 'install.ps1'), '-Mode', mode]);
+  if (st !== 0) throw new Error(`install.ps1 lỗi (mã ${st})`);
+}
+function modeFor(s, dir) {
+  if (s.mode) return s.mode;                                         // cố định trên máy này (--audit / --enforce)
+  const pol = readJson(path.join(dir, 'policy.json'));              // theo chính sách phát hành cùng gói
+  return pol && /^(audit|enforce)$/.test(pol.mode) ? pol.mode : 'enforce';
+}
+function saveConfig(s) {
+  let ca = '';
+  if (s.ca) { ca = path.join(HOME, 'gitlab-ca.crt'); if (path.resolve(s.ca) !== ca) fs.copyFileSync(s.ca, ca); }
+  fs.writeFileSync(CFG, JSON.stringify({ registry: s.registry, ca, token: s.token, mode: s.mode }, null, 2));
+}
+function schedule() {
+  const tr = `"${process.execPath}" "${path.join(HOME, 'current', 'bin', 'cli.js')}" update --quiet`;
+  for (const [suffix, sc] of [['', ['/SC', 'DAILY', '/ST', '10:17']], [' (khoi dong)', ['/SC', 'ONSTART', '/DELAY', '0010:00']]]) {
+    const st = cp.spawnSync('schtasks.exe', ['/Create', '/F', '/TN', TASK + suffix, '/RU', 'SYSTEM', '/RL', 'HIGHEST', '/TR', tr, ...sc], { stdio: 'ignore' }).status;
+    if (st !== 0) say(`Cảnh báo: không tạo được lịch "${TASK + suffix}" (mã ${st})`);
+  }
+}
+function installedVersion() { try { return fs.readFileSync(path.join(HOME, 'current', 'VERSION'), 'utf8').trim(); } catch (_) { return ''; } }
+
+// ------------------------------------------------------------------ lệnh
+async function setup() {
+  if (!IS_WIN) die('Lệnh cài này dành cho máy dev Windows. Máy chủ GitLab dùng installer/install-server.sh.');
+  const s = settings();
+  if (!isAdmin()) return elevate(passArgs(s));
+  const stage = path.join(HOME, 'staging', PKG.version);
+  fs.rmSync(stage, { recursive: true, force: true }); fs.mkdirSync(stage, { recursive: true });
+  fs.cpSync(ROOT, stage, { recursive: true, filter: (p) => !/[\\/]node_modules([\\/]|$)/.test(p) });
+  const mode = modeFor(s, stage);
+  installFrom(stage, mode);
+  fs.rmSync(stage, { recursive: true, force: true });
+  saveConfig(s); schedule();
+  say(`Đã cài VNPTNAN_GATE ${PKG.version} (MODE=${mode}); tự cập nhật hằng ngày từ ${s.registry}`);
+  say('Mở terminal mới và chạy: vnptnan-gate doctor');
+}
+
+async function update() {
+  const s = settings();
+  const cur = installedVersion();
+  const { ver, dist } = await latest(s);
+  if (opt.check) { console.log(`Đang cài: ${cur || '(chưa cài)'} · Trên kho: ${ver}${cur && cmpVer(ver, cur) > 0 ? ' · có bản mới' : ''}`); return; }
+  if (opt.stageOnly) { const n = await fetchTo(s, dist, path.resolve(opt.stageOnly)); console.log(`Đã tải ${ver}, kiểm tra toàn vẹn đạt, giải nén ${n} file vào ${opt.stageOnly}`); return; }
+  if (!IS_WIN) die('Cập nhật chỉ chạy trên máy dev Windows.');
+  if (!isAdmin()) return elevate(passArgs(s));
+  if (cur && cmpVer(ver, cur) <= 0) {
+    // Cùng phiên bản: chỉ đổi chế độ nếu chính sách gói khác chế độ đang chạy
+    const conf = (() => { try { return fs.readFileSync(path.join(HOME, 'current', 'gate.conf'), 'utf8'); } catch (_) { return ''; } })();
+    const want = modeFor(s, path.join(HOME, 'current')), now = (/^MODE=(\w+)/m.exec(conf) || [])[1];
+    if (now && want !== now) { installFrom(path.join(HOME, 'current'), want); say(`Đổi chế độ ${now} -> ${want}`); }
+    else say(`Đã là bản mới nhất ${cur}`);
+    return;
+  }
+  const stage = path.join(HOME, 'staging', ver);
+  const n = await fetchTo(s, dist, stage);
+  const mode = modeFor(s, stage);
+  installFrom(stage, mode);
+  fs.rmSync(stage, { recursive: true, force: true });
+  // Bản mới có thể sửa chính trình cập nhật: đăng ký lại lịch trỏ vào bản vừa cài
+  schedule();
+  say(`Đã cập nhật ${cur || '(chưa cài)'} -> ${ver} (${n} file, MODE=${mode})`);
+}
+
+async function status() {
+  const s = settings(), saved = readJson(CFG) || {};
+  console.log(`Đang cài   : ${installedVersion() || '(chưa cài)'}${IS_WIN ? ` tại ${path.join(HOME, 'current')}` : ''}`);
+  console.log(`Kho gói    : ${s.registry}${s.ca ? ` (CA: ${s.ca})` : ''}`);
+  console.log(`Chế độ     : ${saved.mode ? `${saved.mode} (cố định trên máy này)` : 'theo policy.json của gói'}`);
+  try { const { ver } = await latest(s); console.log(`Bản mới nhất: ${ver}`); } catch (e) { console.log(`Bản mới nhất: không đọc được (${e.message})`); }
+  if (IS_WIN) console.log(`Lịch cập nhật: ${cp.spawnSync('schtasks.exe', ['/Query', '/TN', TASK], { stdio: 'ignore' }).status === 0 ? 'có' : 'CHƯA CÓ'}`);
+}
+
+async function uninstall() {
+  if (!IS_WIN) die('Chỉ dùng trên máy dev Windows.');
+  if (!isAdmin()) return elevate([]);
+  for (const t of [TASK, `${TASK} (khoi dong)`]) cp.spawnSync('schtasks.exe', ['/Delete', '/F', '/TN', t], { stdio: 'ignore' });
+  const un = path.join(HOME, 'current', 'installer', 'uninstall.ps1');
+  if (fs.existsSync(un)) { const tmp = path.join(require('os').tmpdir(), `vnptnan-gate-uninstall-${process.pid}.ps1`); fs.copyFileSync(un, tmp); ps(['-File', tmp]); fs.rmSync(tmp, { force: true }); }
+  fs.rmSync(CFG, { force: true });
+  say('Đã gỡ VNPTNAN_GATE và lịch tự cập nhật.');
+}
+
+const cmds = { setup, update, status, uninstall, version: async () => console.log(PKG.version) };
+if (!cmds[cmd]) die(`Lệnh không có: ${cmd}. Dùng: setup | update [--check] | status | uninstall`);
+cmds[cmd]().catch((e) => die(e.message));

package/ci/.gitlab-ci.yml

@@ -0,0 +1,41 @@
+# Mẫu pipeline cho khi GitLab được nâng cấp và bật CI (Harness để "CI" ở mục Để sau; Gate chuẩn bị sẵn).
+# Thêm vào .gitlab-ci.yml của dự án:  include: { project: 'devops/vnptnan-gate', file: 'ci/.gitlab-ci.yml' }
+stages: [gate]
+
+vnptnan-gate:
+  stage: gate
+  image: alpine:3.20
+  variables:
+    GIT_DEPTH: "0"
+    GATE_MODE: enforce
+    GATE_DEPS: block
+    GATE_DEPS_AUDIT: "0"       # bật "1" khi runner có mạng tới registry
+  before_script:
+    - apk add --no-cache bash git grep sed gawk coreutils
+    - git clone --depth 1 "$CI_SERVER_URL/devops/vnptnan-gate.git" /opt/vnptnan-gate || cp -r "$CI_PROJECT_DIR/.vnptnan-gate-src" /opt/vnptnan-gate
+  script:
+    # Merge request: chỉ quét commit của nhánh. Nhánh thường: quét commit mới của lần push.
+    - |
+      if [ -n "$CI_MERGE_REQUEST_DIFF_BASE_SHA" ]; then
+        bash /opt/vnptnan-gate/engine/gate-scan.sh range "$CI_MERGE_REQUEST_DIFF_BASE_SHA" "$CI_COMMIT_SHA" "$CI_COMMIT_REF_NAME"
+      elif [ "$CI_COMMIT_BEFORE_SHA" != "0000000000000000000000000000000000000000" ]; then
+        bash /opt/vnptnan-gate/engine/gate-scan.sh range "$CI_COMMIT_BEFORE_SHA" "$CI_COMMIT_SHA" "$CI_COMMIT_REF_NAME"
+      else
+        bash /opt/vnptnan-gate/engine/gate-scan.sh tree .
+      fi
+  artifacts:
+    when: always
+    paths: [gate.log]
+    expire_in: 30 days
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH
+
+# Quét toàn bộ cây hằng đêm (schedule) để bắt vi phạm cũ và dependency có lỗ hổng mới công bố.
+vnptnan-gate-nightly:
+  extends: vnptnan-gate
+  variables: { GATE_DEPS_AUDIT: "1" }
+  script:
+    - bash /opt/vnptnan-gate/engine/gate-scan.sh tree .
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"

package/cli/vnptnan-gate

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# Lệnh vnptnan-gate: giao diện dòng lệnh của Cổng kiểm soát ATBMTT.
+set -u
+ROOT=${VNPTNAN_GATE_HOME:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}
+. "$ROOT/engine/gate-lib.sh"
+
+usage() {
+  cat <<EOF
+vnptnan-gate $GATE_VERSION — Cổng kiểm soát ATBMTT khi dùng AI trong phát triển phần mềm
+
+  vnptnan-gate scan                 quét thay đổi đã stage (như pre-commit)
+  vnptnan-gate scan tree [thư-mục]  quét toàn bộ repo (đánh giá repo cũ trước khi bật cổng)
+  vnptnan-gate scan range A B       quét các commit A..B (như pre-push)
+  vnptnan-gate deps [thư-mục]       kiểm dependency và giấy phép
+  vnptnan-gate test "<dòng>"        xem rule nào khớp một dòng nội dung hoặc một đường dẫn, không ghi log
+  vnptnan-gate report [số-ngày]     thống kê phát hiện trên máy này (mặc định 7 ngày)
+  vnptnan-gate doctor               kiểm tra cài đặt: hook, rule, log, cùng tồn tại với VNPTNAN_HARNESS
+  vnptnan-gate tools                in danh mục công cụ AI được phép
+  vnptnan-gate install-hooks        cài hook vào .git/hooks của repo hiện tại (khi không cài cấp máy)
+  vnptnan-gate version
+EOF
+}
+
+cmd=${1:-help}; shift || true
+case "$cmd" in
+  scan)
+    sub=${1:-staged}; shift || true
+    case "$sub" in
+      staged|"") exec bash "$ROOT/engine/gate-scan.sh" staged ;;
+      tree)      exec bash "$ROOT/engine/gate-scan.sh" tree "${1:-.}" ;;
+      range)     exec bash "$ROOT/engine/gate-scan.sh" range "$@" ;;
+      commit)    exec bash "$ROOT/engine/gate-scan.sh" commit "$@" ;;
+      *) usage; exit 2 ;;
+    esac ;;
+  deps) exec bash "$ROOT/engine/gate-scan.sh" deps "${1:-.}" ;;
+  test)
+    text=${1:-}; [ -n "$text" ] || { usage; exit 2; }
+    gate_load_conf ""; gate_load_rules || exit 2
+    GATE_LOG=/dev/null; GATE_QUIET=0
+    tmp=$(mktemp); printf '%s\n' "$text" > "$tmp"
+    echo "Xét như đường dẫn:"; gate_scan_file "$text" /dev/null /dev/null 0
+    echo "Xét như một dòng nội dung:"; gate_scan_file "test.txt" "$tmp" "$tmp" ${#text}
+    rm -f "$tmp"
+    [ "$GATE_N_BLOCK" = 0 ] && [ "$GATE_N_WARN" = 0 ] && echo "  không rule nào khớp"
+    exit 0 ;;
+  report)
+    days=${1:-7}; gate_load_conf ""
+    [ -f "$GATE_LOG" ] || { echo "Chưa có log tại $GATE_LOG"; exit 0; }
+    since=$(date -u -d "-$days days" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-"$days"d +%Y-%m-%dT%H:%M:%SZ)
+    echo "Phát hiện trong $days ngày (từ $since), log: $GATE_LOG"
+    awk -F'\t' -v s="$since" '$1 >= s' "$GATE_LOG" > "${TMPDIR:-/tmp}/gate-report.$$"
+    echo; echo "Theo quyết định:"; awk -F'\t' '{c[$7]++} END{for(k in c) printf "  %-16s %d\n", k, c[k]}' "${TMPDIR:-/tmp}/gate-report.$$"
+    echo; echo "Theo rule:";       awk -F'\t' '{c[$6" ("$7")"]++} END{for(k in c) printf "  %-40s %d\n", k, c[k]}' "${TMPDIR:-/tmp}/gate-report.$$" | sort -k2 -nr
+    echo; echo "Theo giai đoạn:";  awk -F'\t' '{c[$4]++} END{for(k in c) printf "  %-16s %d\n", k, c[k]}' "${TMPDIR:-/tmp}/gate-report.$$"
+    echo; echo "Theo repo:";       awk -F'\t' '{c[$8]++} END{for(k in c) printf "  %-30s %d\n", k, c[k]}' "${TMPDIR:-/tmp}/gate-report.$$"
+    rm -f "${TMPDIR:-/tmp}/gate-report.$$"; exit 0 ;;
+  doctor)
+    gate_load_conf ""; ok=1
+    echo "VNPTNAN_GATE $GATE_VERSION tại $ROOT"
+    echo "Chế độ: MODE=$GATE_MODE DEPS=$GATE_DEPS LOG=$GATE_LOG"
+    if gate_load_rules; then echo "  [ok] rule: ${#RULE_ID[@]} rule hợp lệ"; else echo "  [LOI] rule không nạp được"; ok=0; fi
+    for h in commit push; do
+      ev=$(git config --system --get "hook.vnptnan-gate-$h.event" 2>/dev/null || git config --global --get "hook.vnptnan-gate-$h.event" 2>/dev/null)
+      if [ -n "$ev" ]; then echo "  [ok] hook cấp máy: vnptnan-gate-$h -> $ev"
+      elif [ -x "$(git rev-parse --git-dir 2>/dev/null)/hooks/pre-$h" ] 2>/dev/null && grep -q vnptnan-gate "$(git rev-parse --git-dir)/hooks/pre-$h"; then echo "  [ok] hook của repo: pre-$h"
+      else echo "  [THIEU] hook pre-$h chưa cài (chạy installer/install.ps1 hoặc vnptnan-gate install-hooks)"; ok=0; fi
+    done
+    if git config --system --get hook.vnptnan-guard.event >/dev/null 2>&1; then
+      echo "  [ok] VNPTNAN_HARNESS pre-push guard có mặt; hai hook dùng tên khác nhau, chạy nối tiếp"
+    else echo "  [i]  VNPTNAN_HARNESS chưa cài trên máy này (không bắt buộc)"; fi
+    printf 'AKIAIOSFODNN7EXAMPLE\n' > "${TMPDIR:-/tmp}/gate-doctor.$$"
+    GATE_LOG=/dev/null GATE_QUIET=1 gate_scan_file probe.txt "${TMPDIR:-/tmp}/gate-doctor.$$" "${TMPDIR:-/tmp}/gate-doctor.$$" 21 2>/dev/null
+    rm -f "${TMPDIR:-/tmp}/gate-doctor.$$"
+    if [ "$GATE_N_BLOCK" -gt 0 ]; then echo "  [ok] engine phát hiện được secret mẫu"; else echo "  [LOI] engine không phát hiện được secret mẫu"; ok=0; fi
+    d=$(dirname "$GATE_LOG"); mkdir -p "$d" 2>/dev/null && touch "$GATE_LOG" 2>/dev/null && echo "  [ok] ghi log được" || { echo "  [LOI] không ghi được log $GATE_LOG"; ok=0; }
+    [ "$ok" = 1 ] && echo "all good" || { echo "có lỗi"; exit 1; } ;;
+  tools)
+    awk -F'\t' '!/^#/ && NF>=3 {printf "  %-28s %-8s %-6s %s\n", $1, $2, $4, $5}' "$ROOT/rules/ai-tools.rules" ;;
+  install-hooks)
+    gd=$(git rev-parse --git-dir 2>/dev/null) || { echo "Không ở trong repo git"; exit 2; }
+    for h in pre-commit pre-push commit-msg; do
+      if [ -f "$gd/hooks/$h" ] && ! grep -q vnptnan-gate "$gd/hooks/$h"; then mv "$gd/hooks/$h" "$gd/hooks/$h.local"; fi
+      { printf '#!/bin/sh\n# vnptnan-gate (cài bằng vnptnan-gate install-hooks)\n'
+        printf '[ -x "$0.local" ] && { "$0.local" "$@" || exit $?; }\n'
+        printf 'VNPTNAN_GATE_HOME="%s" exec sh "%s/hooks/%s" "$@"\n' "$ROOT" "$ROOT" "$h"; } > "$gd/hooks/$h"
+      chmod +x "$gd/hooks/$h"; echo "  đã cài $gd/hooks/$h"
+    done ;;
+  version|--version|-v) echo "VNPTNAN_GATE $GATE_VERSION" ;;
+  help|-h|--help|*) usage ;;
+esac

package/cli/vnptnan-gate.cmd

@@ -0,0 +1,9 @@
+@echo off
+rem Lệnh vnptnan-gate trên Windows: chạy bản bash qua Git Bash.
+setlocal
+set "ROOT=%~dp0.."
+set "BASH=%ProgramFiles%\Git\bin\bash.exe"
+if not exist "%BASH%" set "BASH=%LOCALAPPDATA%\Programs\Git\bin\bash.exe"
+if not exist "%BASH%" ( echo Can Git for Windows. & exit /b 2 )
+"%BASH%" "%ROOT%\cli\vnptnan-gate" %*
+exit /b %ERRORLEVEL%

package/engine/gate-deps.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# Kiểm tra thành phần bên thứ ba (dependency) và giấy phép, chạy offline trên máy dev.
+# Nguồn: package.json + node_modules (npm), *.csproj + cache NuGet (~/.nuget/packages). Rule: rules/packages.rules.
+# Được gate-scan.sh nạp (source), dùng các hàm của gate-lib.sh.
+
+PKG_TYPE=(); PKG_LEVEL=(); PKG_RE=(); PKG_MSG=()
+
+deps_load_rules() {
+  local file=$GATE_ROOT/rules/packages.rules line t l re msg
+  [ -f "$file" ] || return 0
+  while IFS= read -r line || [ -n "$line" ]; do
+    line=${line%$'\r'}
+    [ -z "$line" ] && continue
+    case "$line" in '#'*) continue ;; esac
+    IFS=$'\t' read -r t l re msg <<< "$line"
+    [ -n "$t" ] && [ -n "$l" ] && [ -n "$re" ] || continue
+    PKG_TYPE+=("$t"); PKG_LEVEL+=("$l"); PKG_RE+=("$re"); PKG_MSG+=("${msg:-}")
+  done < "$file"
+}
+
+deps_level() {
+  # Mức của rule, hạ xuống warn nếu GATE_DEPS=warn.
+  if [ "$GATE_DEPS" = warn ]; then echo warn; else echo "$1"; fi
+}
+
+deps_check_one() {
+  # $1 hệ (npm|nuget), $2 tên, $3 phiên bản, $4 giấy phép ("" nếu không rõ), $5 đường dẫn file khai báo
+  local eco=$1 name=$2 ver=$3 lic=$4 src=$5 i
+  for i in "${!PKG_TYPE[@]}"; do
+    case "${PKG_TYPE[$i]}" in
+      deny-package)
+        if printf '%s@%s' "$name" "$ver" | grep -qiE -- "${PKG_RE[$i]}" || printf '%s' "$name" | grep -qiE -- "${PKG_RE[$i]}"; then
+          gate_report_finding "$(deps_level "${PKG_LEVEL[$i]}")" "g-dep-package" "$src" "" "$eco $name@$ver" "${PKG_MSG[$i]}"
+        fi ;;
+      deny-license)
+        if printf '%s\n' "$lic" | grep -qiE -- "${PKG_RE[$i]}"; then
+          gate_report_finding "$(deps_level "${PKG_LEVEL[$i]}")" "g-dep-license" "$src" "" "$eco $name@$ver license=${lic:-?}" "${PKG_MSG[$i]}"
+        fi ;;
+    esac
+  done
+}
+
+deps_json_field() {
+  # Lấy giá trị chuỗi của khoá cấp 1 trong file JSON nhỏ (đủ cho package.json). $1 file, $2 khoá.
+  tr -d '\n\r' < "$1" | sed 's/[{},]/&\n/g' | sed -n 's/^[[:space:]]*"'"$2"'"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1
+}
+
+deps_npm() {
+  local dir=$1 pj name ver lic nm block
+  while IFS= read -r pj; do
+    [ -n "$pj" ] || continue
+    nm=$(dirname "$pj")/node_modules
+    # Lấy tên các dependency trực tiếp (dependencies + devDependencies): dòng dạng "ten": "ver" nằm giữa hai khối.
+    # Chuẩn hoá JSON về mỗi phần tử một dòng (package.json có thể nằm trên một dòng) rồi lấy khối dependencies.
+    block=$(tr -d '\n\r' < "$pj" | sed 's/[{},]/&\n/g' | awk '/"(dependencies|devDependencies|optionalDependencies)"[[:space:]]*:/{f=1;next} f&&/^[[:space:]]*}/{f=0} f')
+    while IFS= read -r line; do
+      name=$(printf '%s' "$line" | sed -n 's/^[[:space:]]*"\([^"]*\)".*/\1/p')
+      [ -n "$name" ] || continue
+      if [ -f "$nm/$name/package.json" ]; then
+        ver=$(deps_json_field "$nm/$name/package.json" version)
+        lic=$(deps_json_field "$nm/$name/package.json" license)
+        [ -z "$lic" ] && lic=$(tr -d '\n\r' < "$nm/$name/package.json" | sed -n 's/.*"license"[[:space:]]*:[[:space:]]*{[^}]*"type"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
+        deps_check_one npm "$name" "${ver:-?}" "$lic" "${pj#"$dir"/}"
+      else
+        ver=$(printf '%s' "$line" | sed -n 's/^[^:]*:[[:space:]]*"\([^"]*\)".*/\1/p')
+        deps_check_one npm "$name" "${ver:-?}" "" "${pj#"$dir"/}"
+        gate_report_finding "$(deps_level warn)" "g-dep-unresolved" "${pj#"$dir"/}" "" "npm $name@${ver:-?} chưa có trong node_modules" "Package chưa được cài: kiểm tra tên có thật trên registry (AI hay bịa tên package) rồi npm install trước khi push."
+      fi
+    done <<< "$block"
+    if [ "$GATE_DEPS_AUDIT" = 1 ] && command -v npm >/dev/null 2>&1 && [ -d "$nm" ]; then
+      if ! (cd "$(dirname "$pj")" && npm audit --audit-level=high >/dev/null 2>&1); then
+        gate_report_finding "$(deps_level block)" "g-dep-vulnerable" "${pj#"$dir"/}" "" "npm audit --audit-level=high" "Có lỗ hổng mức high/critical trong dependency npm."
+      fi
+    fi
+  done < <(find "$dir" -name package.json -not -path '*/node_modules/*' -not -path '*/.git/*' 2>/dev/null)
+}
+
+deps_nuget() {
+  local dir=$1 proj name ver lic cache lower nuspec
+  cache=${NUGET_PACKAGES:-${USERPROFILE:-$HOME}/.nuget/packages}
+  while IFS= read -r proj; do
+    [ -n "$proj" ] || continue
+    while IFS='|' read -r name ver; do
+      [ -n "$name" ] || continue
+      lower=$(printf '%s' "$name" | tr '[:upper:]' '[:lower:]')
+      lic=""
+      nuspec=$(ls "$cache/$lower/$ver/$lower.nuspec" 2>/dev/null | head -n1)
+      if [ -n "$nuspec" ]; then
+        lic=$(sed -n 's/.*<license[^>]*type="expression"[^>]*>\([^<]*\)<.*/\1/p' "$nuspec" | head -n1)
+        [ -z "$lic" ] && grep -q '<licenseUrl>' "$nuspec" && lic="SEE LICENSE"
+        deps_check_one nuget "$name" "$ver" "$lic" "${proj#"$dir"/}"
+      else
+        deps_check_one nuget "$name" "$ver" "" "${proj#"$dir"/}"
+        gate_report_finding "$(deps_level warn)" "g-dep-unresolved" "${proj#"$dir"/}" "" "nuget $name@$ver chưa có trong cache NuGet" "Package chưa được restore: kiểm tra tên có thật trên nuget.org (AI hay bịa tên package) rồi dotnet restore trước khi push."
+      fi
+    done < <(sed -n 's/.*<PackageReference[^>]*Include="\([^"]*\)"[^>]*Version="\([^"]*\)".*/\1|\2/p' "$proj")
+    if [ "$GATE_DEPS_AUDIT" = 1 ] && command -v dotnet >/dev/null 2>&1; then
+      if dotnet list "$proj" package --vulnerable --include-transitive 2>/dev/null | grep -qiE 'high|critical'; then
+        gate_report_finding "$(deps_level block)" "g-dep-vulnerable" "${proj#"$dir"/}" "" "dotnet list package --vulnerable" "Có lỗ hổng mức high/critical trong package NuGet."
+      fi
+    fi
+  done < <(find "$dir" -name '*.csproj' -not -path '*/.git/*' 2>/dev/null)
+}
+
+gate_deps_scan() {
+  local dir=${1:-.}
+  deps_load_rules
+  deps_npm "$dir"
+  deps_nuget "$dir"
+}