@pathbit/agentdevkit 0.0.9 → 0.0.11

package/.pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs

@@ -6,6 +6,7 @@ import { spawnSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
 import { projectRoot, requireNode, isMain } from '../lib/runtime.mjs';
+import { validateNativeDownload, nativeRelease, validateNativeRelease, installNative, checkNative, assertNativeVersion } from '../lib/native-release.mjs';
 
 const registry = 'https://registry.npmjs.org/';
 const versionPattern = /^\d+\.\d+\.\d+(?:-[\w.-]+)?$/;
@@ -29,9 +30,13 @@ export function validateToolConfig(name, value) {
   if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) || value?.name !== name) fail(`Nome de ferramenta invalido: ${name}`);
   if (typeof value.description !== 'string' || !value.description.trim() || value.description.includes('\0')) fail(`Descricao ausente ou invalida: ${name}`);
   const download = value.download;
-  if (download?.provider !== 'npm' || download.registry !== registry || download.channel !== 'latest') fail(`Download nao suportado: ${name}`);
-  if (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(download.package || '') || !/^[\w.-]+\/[\w.-]+$/.test(download.repository || '')) fail(`Origem invalida: ${name}`);
+  if (!['npm', 'github-release'].includes(download?.provider)) fail(`Download nao suportado: ${name}`);
+  if (download.provider === 'npm') {
+    if (download.registry !== registry || download.channel !== 'latest') fail(`Download nao suportado: ${name}`);
+    if (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(download.package || '') || !/^[\w.-]+\/[\w.-]+$/.test(download.repository || '')) fail(`Origem invalida: ${name}`);
+  }
   if (!/^[a-z][a-z0-9-]*$/.test(value.group || '') || !Array.isArray(value.platforms) || !value.platforms.length || new Set(value.platforms).size !== value.platforms.length || value.platforms.some(item => !/^(?:darwin|linux|win32)-(?:arm64|x64)$/.test(item))) fail(`Grupo/plataformas invalidos: ${name}`);
+  if (download.provider === 'github-release') validateNativeDownload(download, value.platforms);
   if (!Array.isArray(value.probe) || !value.probe.length || value.probe.some(item => typeof item !== 'string' || item.includes('\0')) || (value.probeInput !== undefined && (typeof value.probeInput !== 'string' || value.probeInput.includes('\0')))) fail(`Verificacao invalida: ${name}`);
   if (value.binary !== undefined && (typeof value.binary !== 'string' || !/^[\w.-]+$/.test(value.binary))) fail(`Executavel invalido: ${name}`);
   if (value.executables !== undefined) {
@@ -72,7 +77,7 @@ export function toolActions(name, entry) {
   validateToolConfig(name, entry);
   const descriptions = {
     install: 'Instala ou reutiliza uma instalacao saudavel.',
-    update: 'Consulta latest e atualiza com rollback em caso de falha.',
+    update: entry.download.provider === 'github-release' ? 'Aplica a versao revisada do catalogo com rollback.' : 'Consulta latest e atualiza com rollback em caso de falha.',
     check: 'Executa o probe local sem instalar nem consultar latest.',
     info: 'Mostra configuracao, plataforma, runtime e versao registrada.',
     run: 'Executa o CLI instalado com os argumentos informados.',
@@ -128,7 +133,8 @@ export function loadCatalog(root = projectRoot) {
   return catalog;
 }
 
-export function validateRelease(name, entry, release) {
+export function validateRelease(name, entry, release, platform = platformKey()) {
+  if (entry.download.provider === 'github-release') return validateNativeRelease(entry, release, platform);
   const expected = entry.download.package;
   const repository = typeof release.repository === 'string' ? release.repository : release.repository?.url;
   if (release.name !== expected || !versionPattern.test(release.version || '')) fail(`Nome/versao invalido no registro: ${name}`);
@@ -165,6 +171,9 @@ export function binaryInvocation(prefix, name, args = [], binaryName = name.spli
 
 export function toolEnvironment(entry, local, runtime) {
   const environment = Object.assign(Object.create(null), process.env);
+  if (entry.download?.provider === 'github-release') {
+    for (const key of Object.keys(environment)) if (/token|secret|password|(?:^|_)auth(?:_|$)|^(?:semgrep|opengrep)_/i.test(key)) delete environment[key];
+  }
   const set = (key, value) => {
     if (process.platform === 'win32') for (const existing of Object.keys(environment)) if (existing.toUpperCase() === key.toUpperCase()) delete environment[existing];
     environment[key] = value;
@@ -184,10 +193,13 @@ export function toolEnvironment(entry, local, runtime) {
 }
 
 function execute(prefix, entry, args, capture = false, input, environment, runtime) {
-  const [file, options] = binaryInvocation(prefix, entry.download.package, args, entry.binary || entry.name, runtime.file);
+  const native = entry.download.provider === 'github-release';
+  const [file, options] = native ? [checkNative(prefix, entry, runtime.platform || platformKey()).file, args]
+    : binaryInvocation(prefix, entry.download.package, args, entry.binary || entry.name, runtime.file);
   const result = spawnSync(file, options, { stdio: capture ? 'pipe' : 'inherit', cwd: capture ? prefix : undefined, input, env: environment, encoding: 'utf8', timeout: capture ? 30000 : undefined, windowsHide: true });
   if (result.error) throw result.error;
   if (capture && result.status !== 0) fail(`${entry.name}: ${result.stderr?.trim().slice(0, 400) || result.stdout?.trim().slice(0, 400) || `falha ${result.status}`}`, result.status ?? 1);
+  if (capture && native) assertNativeVersion(`${result.stdout || ''}\n${result.stderr || ''}`, entry.download.version);
   return result.status ?? 1;
 }
 
@@ -215,11 +227,13 @@ export class ToolManager {
     this.catalog = catalog ?? loadCatalog(this.root);
     for (const [name, entry] of Object.entries(this.catalog)) validateToolConfig(name, entry);
     this.fetchRelease = fetchRelease || (async (name, entry) => {
+      if (entry.download.provider === 'github-release') return nativeRelease(entry, this.target);
       const response = await fetch(`${entry.download.registry}${encodeURIComponent(entry.download.package)}/${entry.download.channel}`, { signal: AbortSignal.timeout(20000) });
       if (!response.ok) fail(`Registro indisponivel: HTTP ${response.status}`);
       return response.json();
     });
-    this.installPackage = install || ((prefix, packageName, version, entry, runtime) => {
+    this.installPackage = install || (async (prefix, packageName, version, entry, runtime) => {
+      if (entry.download.provider === 'github-release') return installNative(prefix, entry, this.target);
       const environment = toolEnvironment(entry, this.local(entry.name), runtime);
       const result = spawnSync(runtime.file, [this.npm(runtime, environment), 'install', '--prefix', prefix, '--cache', join(this.home, '.cache/npm'), '--registry', entry.download.registry, '--ignore-scripts', '--omit=dev', '--no-audit', '--no-fund', '--save-exact', `${packageName}@${version}`], {
         cwd: prefix, encoding: 'utf8', timeout: 180000,
@@ -236,7 +250,7 @@ export class ToolManager {
     const entry = this.entry(name);
     if (!entry.platforms.includes(this.target)) fail(`Plataforma nao suportada por ${name}: ${this.target}`);
     requireNode(24, this.nodeVersion);
-    return { file: process.execPath, version: process.version };
+    return { file: process.execPath, version: process.version, platform: this.target };
   }
   preflight(names) {
     const issues = [];
@@ -298,8 +312,13 @@ export class ToolManager {
   }
   check(name) {
     const entry = this.entry(name); const runtime = this.runtime(name); const info = this.current(name);
-    const pkg = json(join(info.prefix, 'node_modules', entry.download.package, 'package.json'));
-    if (pkg.name !== entry.download.package || pkg.version !== info.version) fail(`Versao local divergente: ${name}`);
+    if (entry.download.provider === 'github-release') {
+      const receipt = checkNative(info.prefix, entry, this.target);
+      if (receipt.version !== info.version || receipt.binarySha256 !== info.binarySha256) fail(`Versao local divergente: ${name}`);
+    } else {
+      const pkg = json(join(info.prefix, 'node_modules', entry.download.package, 'package.json'));
+      if (pkg.name !== entry.download.package || pkg.version !== info.version) fail(`Versao local divergente: ${name}`);
+    }
     execute(info.prefix, entry, entry.probe, true, entry.probeInput, toolEnvironment(entry, this.local(name), runtime), runtime);
     return info;
   }
@@ -399,7 +418,7 @@ export class ToolManager {
     renameSync(storagePath(this.root, temporary, 'file'), storagePath(this.root, join(local, 'CURRENT.json'), 'file'));
   }
   async updateLocked(name) {
-    const entry = this.entry(name); const runtime = this.runtime(name); const release = validateRelease(name, entry, await this.fetchRelease(name, entry));
+    const entry = this.entry(name); const runtime = this.runtime(name); const release = validateRelease(name, entry, await this.fetchRelease(name, entry), this.target);
     const { local } = this.storage(name);
     const target = storagePath(this.root, join(local, 'versions', `${release.version}-${this.target}`), 'directory');
     let installed;
@@ -409,14 +428,21 @@ export class ToolManager {
     const stage = mkdtempSync(join(local, '.stage-'));
     const temporary = storagePath(this.root, join(local, `CURRENT.${randomUUID()}.json`), 'file'); let previous; let moved = false;
     try {
-      this.installPackage(stage, entry.download.package, release.version, entry, runtime);
+      if (entry.download.provider === 'github-release') {
+        for (const location of Object.values(entry.envPaths || {})) mkdirSync(storagePath(this.root, join(local, location), 'directory'), { recursive: true });
+      }
+      await this.installPackage(stage, entry.download.package, release.version, entry, runtime);
       this.storage(name); storagePath(this.root, stage, 'directory');
-      const pkg = json(join(stage, 'node_modules', entry.download.package, 'package.json')); const lock = json(join(stage, 'package-lock.json'));
-      if (pkg.name !== entry.download.package || pkg.version !== release.version || lock.packages?.[`node_modules/${entry.download.package}`]?.integrity !== release.dist.integrity) fail('Pacote instalado nao corresponde ao registro.');
-      prepareExecutables(stage, entry, this.target);
+      let receipt;
+      if (entry.download.provider === 'github-release') receipt = checkNative(stage, entry, this.target);
+      else {
+        const pkg = json(join(stage, 'node_modules', entry.download.package, 'package.json')); const lock = json(join(stage, 'package-lock.json'));
+        if (pkg.name !== entry.download.package || pkg.version !== release.version || lock.packages?.[`node_modules/${entry.download.package}`]?.integrity !== release.dist.integrity) fail('Pacote instalado nao corresponde ao registro.');
+        prepareExecutables(stage, entry, this.target);
+      }
       execute(stage, entry, entry.probe, true, entry.probeInput, toolEnvironment(entry, local, runtime), runtime);
       this.storage(name); storagePath(this.root, target, 'directory');
-      const info = { name, package: entry.download.package, version: release.version, platform: this.target, node: runtime.version, nodePath: runtime.file, source: entry.source, tarball: release.dist.tarball, integrity: release.dist.integrity, checkedAt: new Date().toISOString() };
+      const info = { name, ...(receipt ? { provider: 'github-release', binarySha256: receipt.binarySha256, archiveSha256: receipt.archiveSha256 } : { package: entry.download.package }), version: release.version, platform: this.target, node: runtime.version, nodePath: runtime.file, source: entry.source, tarball: receipt ? release.url : release.dist.tarball, integrity: receipt ? `sha256-${Buffer.from(receipt.archiveSha256, 'hex').toString('base64')}` : release.dist.integrity, checkedAt: new Date().toISOString() };
       writeFileSync(storagePath(this.root, temporary, 'file'), `${JSON.stringify(info, null, 2)}\n`, { flag: 'wx' });
       this.launchers(name);
       if (existsSync(target)) { previous = storagePath(this.root, `${target}.previous-${randomUUID()}`, 'directory'); renameSync(storagePath(this.root, target, 'directory'), previous); }
@@ -425,7 +451,11 @@ export class ToolManager {
       return { ...info, layout: 'local', prefix: target, changed: true };
     } finally { rmSync(storagePath(this.root, stage, 'directory'), { recursive: true, force: true }); rmSync(storagePath(this.root, temporary, 'file'), { force: true }); }
   }
-  run(name, args) { const entry = this.entry(name); const runtime = this.runtime(name); return execute(this.current(name).prefix, entry, args, false, undefined, toolEnvironment(entry, this.local(name), runtime), runtime); }
+  run(name, args) {
+    const entry = this.entry(name), runtime = this.runtime(name), current = this.current(name);
+    if (entry.download.provider === 'github-release' && checkNative(current.prefix, entry, this.target).binarySha256 !== current.binarySha256) fail(`Recibo local divergente: ${name}`);
+    return execute(current.prefix, entry, args, false, undefined, toolEnvironment(entry, this.local(name), runtime), runtime);
+  }
 }
 
 const help = 'Uso: setup [all|grupo|nome]; [install|update|check|info] [base|all|grupo|nome]; list; unlock <nome>; run <nome> [argumentos]; --tool <nome> <acao> [argumentos].';

package/.pbai4devs/scripts/preparar-ferramentas/tests/TEST.mjs

@@ -8,6 +8,7 @@ import { hostname } from 'node:os';
 import { ToolManager, platformKey, validateRelease, validateToolConfig, loadCatalog, main, toolEnvironment, binaryInvocation, toolActions, toolWrapper } from '../SCRIPT.mjs';
 import { requireNode } from '../../lib/runtime.mjs';
 import './bootstrap.test.mjs';
+import './native-release.test.mjs';
 
 const project = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
 const tool = (name = 'test-tool', group = 'base') => ({ name, description: 'Ferramenta da fixture.', group, source: `https://github.com/owner/${name}`, download: { provider: 'npm', package: name, registry: 'https://registry.npmjs.org/', repository: `owner/${name}`, channel: 'latest' }, platforms: [platformKey()], scripts: { entry: 'SCRIPT.mjs' }, probe: ['--version'] });
@@ -44,6 +45,7 @@ function fixture(t, catalog = { 'test-tool': tool() }, options = {}) {
   copyFileSync(join(project, '.pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs'), join(common, 'SCRIPT.mjs'));
   mkdirSync(join(root, '.pbai4devs/scripts/lib'), { recursive: true });
   copyFileSync(join(project, '.pbai4devs/scripts/lib/runtime.mjs'), join(root, '.pbai4devs/scripts/lib/runtime.mjs'));
+  copyFileSync(join(project, '.pbai4devs/scripts/lib/native-release.mjs'), join(root, '.pbai4devs/scripts/lib/native-release.mjs'));
   const state = { version: '1.0.0', installs: 0, fetches: 0, fail: false, tamper: false, broken: false, noBin: false };
   const manager = new ToolManager({ root, catalog, fetchRelease: async name => { state.fetches++; return release(state.version, name); }, install(prefix, name, version) { state.installs++; if (state.fail) throw new Error('download de prova falhou'); packageFiles(prefix, name, version, state); }, ...options });
   return { root, manager, state, local: join(root, '.pbai4devs/tools/test-tool/.local') };

package/.pbai4devs/scripts/preparar-ferramentas/tests/native-release.test.mjs

@@ -0,0 +1,103 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { gzipSync, deflateRawSync } from 'node:zlib';
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, rmSync, symlinkSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { nativeHash, nativeRelease, validateNativeDownload, validateNativeRelease, downloadNative, extractNative, installNative, checkNative, assertNativeVersion } from '../../lib/native-release.mjs';
+import { ToolManager, platformKey, toolEnvironment } from '../SCRIPT.mjs';
+
+const project = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
+function fixture(t) { const dir = join(project, '.agent-tests'); mkdirSync(dir, { recursive: true }); const root = mkdtempSync(join(dir, 'native tools ')); t.after(() => rmSync(root, { recursive: true, force: true })); return root; }
+function config(bytes = Buffer.from('#!/bin/sh\necho 1.2.3\n'), version = '1.2.3') {
+  return { name: 'native-test', description: 'Native fixture.', group: 'security', source: 'https://github.com/owner/repo',
+    platforms: [platformKey()], scripts: { entry: 'SCRIPT.mjs' }, probe: ['--version'],
+    download: { provider: 'github-release', repository: 'owner/repo', channel: 'reviewed', version, tag: `v${version}`,
+      assets: { [platformKey()]: { file: 'tool.bin', format: 'raw', binary: 'tool', sha256: nativeHash(bytes) } } } };
+}
+function tar(entries) {
+  const chunks = [];
+  for (const { name, bytes = Buffer.from('binary'), type = '0' } of entries) {
+    const header = Buffer.alloc(512); header.write(name, 0, 100); header.write('0000755\0', 100); header.write('0000000\0', 108); header.write('0000000\0', 116);
+    header.write(bytes.length.toString(8).padStart(11, '0') + '\0', 124); header.write('00000000000\0', 136); header.fill(32, 148, 156); header.write(type, 156); header.write('ustar\0', 257);
+    header.write([...header].reduce((a, b) => a + b, 0).toString(8).padStart(6, '0') + '\0 ', 148);
+    chunks.push(header, bytes, Buffer.alloc((512 - bytes.length % 512) % 512));
+  }
+  return gzipSync(Buffer.concat([...chunks, Buffer.alloc(1024)]));
+}
+function crc32(bytes) { let crc = 0xffffffff; for (const b of bytes) { crc ^= b; for (let i = 0; i < 8; i++) crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1)); } return (crc ^ 0xffffffff) >>> 0; }
+function zip(entries) {
+  const locals = [], centrals = []; let cursor = 0;
+  for (const { name, bytes = Buffer.from('binary'), mode = 0o100755, method = 8 } of entries) {
+    const filename = Buffer.from(name), compressed = method === 8 ? deflateRawSync(bytes) : bytes, crc = crc32(bytes);
+    const local = Buffer.alloc(30); local.writeUInt32LE(0x04034b50); local.writeUInt16LE(20, 4); local.writeUInt16LE(method, 8); local.writeUInt32LE(crc, 14); local.writeUInt32LE(compressed.length, 18); local.writeUInt32LE(bytes.length, 22); local.writeUInt16LE(filename.length, 26);
+    const central = Buffer.alloc(46); central.writeUInt32LE(0x02014b50); central.writeUInt16LE(3 << 8 | 20, 4); central.writeUInt16LE(20, 6); central.writeUInt16LE(method, 10); central.writeUInt32LE(crc, 16); central.writeUInt32LE(compressed.length, 20); central.writeUInt32LE(bytes.length, 24); central.writeUInt16LE(filename.length, 28); central.writeUInt32LE((mode << 16) >>> 0, 38); central.writeUInt32LE(cursor, 42);
+    locals.push(local, filename, compressed); centrals.push(central, filename); cursor += local.length + filename.length + compressed.length;
+  }
+  const central = Buffer.concat(centrals), end = Buffer.alloc(22); end.writeUInt32LE(0x06054b50); end.writeUInt16LE(entries.length, 8); end.writeUInt16LE(entries.length, 10); end.writeUInt32LE(central.length, 12); end.writeUInt32LE(cursor, 16);
+  return Buffer.concat([...locals, central, end]);
+}
+const asset = (bytes, format, binary = 'tool') => ({ format, binary, sha256: nativeHash(bytes) });
+
+test('native release requires reviewed pins and exact platform assets', () => {
+  const entry = config(); assert.equal(validateNativeDownload(entry.download, entry.platforms), entry.download);
+  const release = nativeRelease(entry, platformKey()); assert.equal(validateNativeRelease(entry, release, platformKey()), release);
+  for (const change of [{ channel: 'latest' }, { tag: 'master' }, { version: '1.2.3-rc.1' }, { repository: '../evil' }, { assets: {} }]) assert.throws(() => validateNativeDownload({ ...entry.download, ...change }, entry.platforms));
+  assert.throws(() => validateNativeRelease(entry, { ...release, url: 'https://evil.example/tool' }, platformKey()));
+  const invalid = config(); invalid.download.assets[platformKey()].binary = '../escape'; assert.throws(() => validateNativeDownload(invalid.download, invalid.platforms));
+  assert.throws(() => assertNativeVersion('version 1.2.30', '1.2.3')); assert.throws(() => assertNativeVersion('version 1.2.3-rc.1', '1.2.3')); assertNativeVersion('Tool v1.2.3\n', '1.2.3');
+});
+
+test('native download follows only anonymous official asset hosts with limits', async () => {
+  const seen = [];
+  const fetcher = async (url, options) => { seen.push({ url, options }); return seen.length === 1 ? new Response(null, { status: 302, headers: { location: 'https://release-assets.githubusercontent.com/file?signature=x' } }) : new Response('data'); };
+  assert.equal((await downloadNative('https://github.com/owner/repo/releases/download/v1/tool', { fetcher })).toString(), 'data');
+  assert.ok(seen.every(({ options }) => !Object.keys(options.headers).some(key => /authorization|token/i.test(key))));
+  await assert.rejects(downloadNative('http://github.com/file', { fetcher }), /Host/);
+  await assert.rejects(downloadNative('https://evil.example/file', { fetcher }), /GitHub/);
+  await assert.rejects(downloadNative('https://github.com/file', { fetcher: async () => new Response(null, { status: 302, headers: { location: 'https://evil.example/file' } }) }), /Host/);
+  await assert.rejects(downloadNative('https://github.com/file', { maxBytes: 2, fetcher: async () => new Response('four') }), /limite/);
+  await assert.rejects(downloadNative('https://github.com/file', { fetcher: async () => new Response('missing', { status: 404 }) }), /404/);
+});
+
+test('native extraction accepts exact raw/tar/zip executable and rejects traversal and links', () => {
+  const raw = Buffer.from('raw binary'); assert.deepEqual(extractNative(raw, asset(raw, 'raw')), raw);
+  for (const format of ['tar.gz', 'zip']) {
+    const pack = format === 'tar.gz' ? tar : zip;
+    const archive = pack([{ name: 'LICENSE', bytes: Buffer.from('license') }, { name: 'tool', bytes: raw }]);
+    assert.deepEqual(extractNative(archive, asset(archive, format)), raw);
+    for (const name of ['../escape', '/absolute', 'C:/drive', 'folder\\escape']) {
+      const bad = pack([{ name }, { name: 'tool' }]); assert.throws(() => extractNative(bad, asset(bad, format)), /Caminho/);
+    }
+    const duplicate = pack([{ name: 'tool' }, { name: 'TOOL' }]); assert.throws(() => extractNative(duplicate, asset(duplicate, format)), /duplicada/);
+    const link = pack([{ name: 'link', type: '2', mode: 0o120777 }, { name: 'tool' }]); assert.throws(() => extractNative(link, asset(link, format)), /Links|Link/);
+    assert.throws(() => extractNative(archive, { ...asset(archive, format), sha256: '0'.repeat(64) }), /SHA-256/);
+    assert.throws(() => extractNative(archive, asset(archive, format, 'absent')), /ausente/);
+  }
+});
+
+test('native receipts reject tampering and symbolic files without following them', async t => {
+  const root = fixture(t), bytes = Buffer.from('binary'), entry = config(bytes); const prefix = join(root, 'stage'); mkdirSync(prefix);
+  const receipt = await installNative(prefix, entry, platformKey(), { download: async () => bytes }); assert.equal(checkNative(prefix, entry, platformKey()).binarySha256, receipt.binarySha256);
+  const executable = join(prefix, receipt.executable); writeFileSync(executable, 'tampered'); assert.throws(() => checkNative(prefix, entry, platformKey()), /alterado/);
+  writeFileSync(executable, bytes); const outside = join(root, 'outside'); writeFileSync(outside, 'preserve'); rmSync(executable);
+  try { symlinkSync(outside, executable); } catch (error) { if (['EPERM', 'EACCES'].includes(error.code)) return; throw error; }
+  assert.throws(() => checkNative(prefix, entry, platformKey()), /simbolico/); assert.equal(readFileSync(outside, 'utf8'), 'preserve');
+});
+
+test('native manager installs, reuses without network, updates reviewed pins and rolls back', { skip: process.platform === 'win32' }, async t => {
+  const root = fixture(t); let bytes = Buffer.from('#!/bin/sh\nif [ "$1" = "exit" ]; then exit 37; fi\necho 1.2.3\n'), installs = 0, fail = false;
+  let entry = config(bytes); const manager = new ToolManager({ root, catalog: { 'native-test': entry }, install: async prefix => { installs++; if (fail) throw Error('download failed'); await installNative(prefix, entry, platformKey(), { download: async () => bytes }); } });
+  const installed = await manager.install(entry.name); assert.equal(installed.version, '1.2.3'); assert.equal(manager.check(entry.name).version, '1.2.3'); assert.equal(manager.run(entry.name, ['exit']), 37);
+  manager.fetchRelease = async () => { throw Error('unexpected network'); }; assert.equal((await manager.install(entry.name)).changed, false); assert.equal(installs, 1);
+  const old = readFileSync(join(manager.local(entry.name), 'CURRENT.json'));
+  bytes = Buffer.from('#!/bin/sh\necho 2.0.0\n'); entry = config(bytes, '2.0.0'); manager.catalog[entry.name] = entry; manager.fetchRelease = async () => nativeRelease(entry, platformKey()); fail = true;
+  await assert.rejects(manager.update(entry.name), /download failed/); assert.deepEqual(readFileSync(join(manager.local(entry.name), 'CURRENT.json')), old);
+  fail = false; assert.equal((await manager.update(entry.name)).version, '2.0.0'); assert.equal(manager.check(entry.name).version, '2.0.0');
+  assert.ok(!existsSync(join(manager.local(entry.name), '.update-lock')));
+});
+
+test('native environment removes unrelated credentials while preserving host settings', () => {
+  const saved = process.env.NATIVE_TEST_TOKEN; process.env.NATIVE_TEST_TOKEN = 'secret';
+  try { assert.equal(toolEnvironment(config(), '/tmp/local').NATIVE_TEST_TOKEN, undefined); } finally { if (saved === undefined) delete process.env.NATIVE_TEST_TOKEN; else process.env.NATIVE_TEST_TOKEN = saved; }
+});

package/.pbai4devs/skills/README.md

@@ -4,13 +4,19 @@ description: Finalidade e criação de skills compartilhadas.
 
 # Skills
 
-São procedimentos reutilizáveis, organizados em `git`, `projeto`, `produto` e
-`specs`. Cada skill usa `<grupo>/<nome>/SKILL.md` com nome e descrição no YAML.
+São procedimentos reutilizáveis, organizados por assunto. Cada skill usa
+`<grupo>/<nome>/SKILL.md` com nome e descrição no YAML. A skill orienta decisões;
+o agente responsável pode acionar comandos, scripts e outros perfis conforme
+as capacidades do cliente.
 
 - `git`: operações de versionamento.
 - `projeto`: configuração, criação e manutenção dos recursos.
 - `produto`: PRD, experiência e design técnico.
 - `specs`: especificações, roadmap e implementação.
+- `seguranca`: [revisão](seguranca/revisar-seguranca/SKILL.md),
+  [autorização](seguranca/revisar-autorizacao/SKILL.md),
+  [ameaças](seguranca/modelar-ameacas/SKILL.md) e
+  [correção](seguranca/corrigir-vulnerabilidade/SKILL.md).
 
 Use `criar-skill` quando uma tarefa recorrente precisar de decisões próprias;
 use `criar-recurso` para encontrar um fluxo existente antes de criar outro.
@@ -21,4 +27,6 @@ Use [proximos-passos](projeto/proximos-passos/SKILL.md) para orientar a
 continuidade conforme a fase e as pendências reais.
 
 O [guia compartilhado](../INSTRUCTIONS.md) orienta o uso das skills.
+As skills de segurança integram a instalação do kit; os scanners exigem
+[preparo explícito](../commands/preparar-seguranca/COMMAND.md).
 Ao alterar o inventário, sincronize os índices e apontamentos locais.

package/.pbai4devs/skills/projeto/preparar-ferramentas/SKILL.md

@@ -24,7 +24,8 @@ instalador compartilhado.
 No preparo inicial, execute `preparar-ferramentas setup` pelo seletor:
 instala e verifica todas as ferramentas compatíveis, sem atualizar as saudáveis.
 Aceita seleção por nome/grupo; relate falhas e itens não aplicáveis.
-Para buscar versões novas, `update` consulta `latest` oficial.
+Para npm, `update` consulta `latest` oficial; ferramentas nativas de segurança
+seguem o pin revisado em `TOOL.json`, sem atualização silenciosa para outro binário.
 `install` reutiliza uma instalação saudável; `check` verifica sem rede;
 `info` mostra a configuração; `run <nome> [argumentos]` executa sem instalar.
 Sem ação, mostre ajuda. Não interprete ausência de argumentos como instalação.
@@ -41,6 +42,9 @@ Em `skills`, use `find` ou `add <origem> --list`; incorporações passam por
 O shell virtual não substitui testes reais. Só ative proxy, certificados,
 serviços ou gravação quando necessários à tarefa e com dependências preparadas.
 
+Para segurança, use [preparar-seguranca](../../../commands/preparar-seguranca/COMMAND.md).
+Preparar o CLI e atualizar bases são operações separadas da análise offline.
+
 Antes de usar agent-desktop, leia `skills get desktop` e `skills get platform`
 da versão instalada e confira `status`. Para agent-browser, leia
 `skills get core` e `--help` da versão instalada e

package/.pbai4devs/skills/seguranca/REFERENCE.md

@@ -0,0 +1,104 @@
+---
+description: Segurança com scanners locais, triagem e provas de controles.
+---
+
+# Segurança local
+
+A instalação do kit inclui skills, regras, comandos e perfis de segurança.
+Os scanners são preparados por uma ação explícita; os arquivos de instrução
+não iniciam auditorias, serviços ou downloads em segundo plano.
+
+## Como os componentes trabalham juntos
+
+O comando [auditar-seguranca][audit] organiza o trabalho. A
+[skill de revisão][review] define como analisar e o [auditor][auditor] faz a
+triagem contextual. O script executa ferramentas e produz evidências; as
+[regras][rules] orientam todas as etapas. Veja o [catálogo de comandos](../../commands/README.md).
+
+| Ferramenta | Pergunta que ajuda a responder |
+| --- | --- |
+| [Gitleaks][gitleaks] | Há indícios de segredos nos arquivos analisados? |
+| [OSV-Scanner][osv] | A base local conhece falhas nas versões das dependências? |
+| [Opengrep][opengrep] | O código corresponde aos padrões das regras locais? |
+
+As ferramentas executam localmente e não exigem conta ou assinatura.
+Versões revisadas e suas origens ficam nos `TOOL.json`. Downloads públicos de
+binários e bases são separados da análise. A política do cliente/modelo de IA
+continua sendo própria; não coloque valores secretos no contexto da conversa.
+
+## Preparar e executar
+
+Use Node.js 24+ e o projeto autorizado. O fluxo de
+[preparar-seguranca][prepare] instala os scanners e confere seu funcionamento:
+
+```console
+node .pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs setup security
+```
+
+Para dependências, baixe a base dos ecossistemas realmente utilizados. Exemplo
+para npm; substitua por `Go` ou pela seleção suportada que corresponda ao projeto:
+
+```console
+node .pbai4devs/scripts/auditar-seguranca/SCRIPT.mjs update-data --ecosystems npm
+node .pbai4devs/scripts/auditar-seguranca/SCRIPT.mjs check
+node .pbai4devs/scripts/auditar-seguranca/SCRIPT.mjs run
+```
+
+`run` usa os três checks: `secrets`, `dependencies` e `sast`. Para limitar,
+use [verificar-segredos][secrets] ou [verificar-dependencias][dependencies].
+A análise usa dados locais; base ausente não autoriza enviar o projeto a uma API.
+Confira no relatório a versão da ferramenta, a base e o escopo efetivamente lido.
+
+## O que ainda precisa ser provado
+
+O [artigo sobre falhas recorrentes][article] motiva os temas abaixo. As
+verificações dependem da arquitetura e não equivalem a uma certificação.
+
+| Tema | Prova necessária no projeto |
+| --- | --- |
+| Autorização no servidor | API direta recusa visitante e papel insuficiente. |
+| Acesso por identificador | Usuário A não lê ou altera o recurso de B. |
+| Isolamento dos dados | Policies/RLS ou Security Rules restringem o acesso. |
+| Segredos | Credenciais privadas não chegam a fontes, bundles ou logs. |
+| Entradas e abuso | Testes de validação, saída, upload e limites do fluxo. |
+
+RLS é um controle de PostgreSQL usado pelo Supabase; Firebase tem Security Rules.
+SDKs privilegiados podem atravessar esses controles e precisam de autorização
+no servidor. Esconder um botão de administrador não protege a API.
+
+Use [revisar-autorizacao][authorization] com identidades sintéticas distintas,
+testes negativos e dados locais. Para entradas, prefira consultas parametrizadas,
+codificação de saída por contexto e limites de upload; sanitização genérica não
+resolve todos os casos. Teste a interface no navegador quando ela existir.
+Sem aplicação executável, registre essas provas como **não verificadas**.
+
+## Interpretar e corrigir
+
+O runner retorna `0` sem achados, `1` com achados e `2` em falha ou verificação
+incompleta. Leia o estado de cada check: não aplicável e não executado não
+significam aprovado. Regras locais e formatos suportados limitam a cobertura.
+
+O relatório fica em `.agent-tests/security/<execucao>/report.json`, sem valores
+secretos. O auditor distingue suspeitas, falhas confirmadas e falsos positivos.
+Use [modelar-ameacas][threats] para novos fluxos e
+[corrigir-vulnerabilidade][fix] para reparar a causa com teste de regressão.
+Uma credencial real exposta precisa de revogação pelo responsável; não a teste
+contra serviços externos. Feche a entrega com [revisão independente][gate].
+
+[Skills](../README.md) · [Ferramentas](../../tools/README.md)
+
+[audit]: ../../commands/auditar-seguranca/COMMAND.md
+[review]: ../../skills/seguranca/revisar-seguranca/SKILL.md
+[auditor]: ../../agents/auditor-seguranca/AGENT.md
+[rules]: ../../rules/seguranca/RULE.md
+[gitleaks]: ../../tools/gitleaks/README.md
+[osv]: ../../tools/osv-scanner/README.md
+[opengrep]: ../../tools/opengrep/README.md
+[prepare]: ../../commands/preparar-seguranca/COMMAND.md
+[secrets]: ../../commands/verificar-segredos/COMMAND.md
+[dependencies]: ../../commands/verificar-dependencias/COMMAND.md
+[authorization]: ../../skills/seguranca/revisar-autorizacao/SKILL.md
+[threats]: ../../skills/seguranca/modelar-ameacas/SKILL.md
+[fix]: ../../skills/seguranca/corrigir-vulnerabilidade/SKILL.md
+[gate]: ../../commands/revisar-entrega/COMMAND.md
+[article]: https://manodeyvin.com.br/p/5-vacilacoes-de-seguranca-que-a-ia

package/.pbai4devs/skills/seguranca/corrigir-vulnerabilidade/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: corrigir-vulnerabilidade
+description: Corrige um achado validado e prova que a causa foi removida.
+---
+
+# Corrigir vulnerabilidade
+
+Receba o achado e sua evidência de [revisar-seguranca](../revisar-seguranca/SKILL.md).
+Confirme o caminho de abuso e o escopo autorizado. Esclareça dúvidas e apresente
+o plano antes de editar, respeitando aprovações já dadas.
+
+Corrija a causa, preserve o contrato legítimo e acrescente um teste de regressão
+que falhe antes e passe depois. Não silencie regra ou exclua arquivo apenas
+para deixar o scanner verde; documente falsos positivos com justificativa.
+
+Use [implementar-spec](../../specs/implementar-spec/SKILL.md) quando houver spec
+e [verificar-trabalho](../../projeto/verificar-trabalho/SKILL.md) para as provas.
+Repita o scanner relevante e o cenário original. Mudanças web exigem navegador;
+autorização exige a matriz de [permissões](../revisar-autorizacao/SKILL.md).
+
+Se houver segredo real, não o reproduza. Informe o responsável para revogação
+e rotação pelo canal apropriado; remover do código não invalida a credencial.
+Não altere contas, histórico Git ou serviços externos sem escopo explícito.
+
+Saída: correção, teste, risco residual e documentação atualizada. Feche com
+[revisar-entrega](../../../commands/revisar-entrega/COMMAND.md), incluindo
+revisão independente e evidências ignoradas em `.agent-tests/security/`.

package/.pbai4devs/skills/seguranca/modelar-ameacas/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: modelar-ameacas
+description: Identifica ativos, fronteiras de confiança e ameaças do escopo aprovado.
+---
+
+# Modelar ameaças
+
+Leia produto, design e código relacionados. Reúna primeiro as dúvidas sobre
+dados, atores, operações privilegiadas e limites do ambiente. Registre o que
+é fato, hipótese ou informação ausente; não invente arquitetura.
+
+Mapeie os ativos, entradas, fluxos e fronteiras de confiança. Para cada ameaça,
+descreva pré-condição, caminho de abuso, impacto, controle e teste observável.
+Priorize o que o desenho realmente permite: acesso entre usuários, elevação
+de privilégio, vazamento, injeção e abuso de recursos.
+
+Use o [modelo de revisão](../../../templates/revisao-seguranca/TEMPLATE.md)
+como apoio e o [auditor](../../../agents/auditor-seguranca/AGENT.md) para revisão.
+Se o projeto precisar de um documento permanente, combine seu destino com o
+usuário e siga [atualizar-documentacao](../../projeto/atualizar-documentacao/SKILL.md).
+Rascunhos e evidências ficam em `.agent-tests/security/`.
+
+Saída: ameaças priorizadas, controles existentes, lacunas e critérios de teste.
+O modelo orienta [revisar-seguranca](../revisar-seguranca/SKILL.md); não comprova
+que os controles foram implementados ou testados.

package/.pbai4devs/skills/seguranca/revisar-autorizacao/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: revisar-autorizacao
+description: Verifica identidade, permissões por recurso e isolamento entre usuários.
+---
+
+# Revisar autorização
+
+Identifique sujeitos, papéis, recursos e operações permitidas. Leia rotas,
+middleware, políticas de dados e testes; não deduza autorização pela interface.
+Se o contrato não existir, reúna as dúvidas antes de propor mudanças.
+
+Confira autenticação e autorização no servidor em cada operação sensível,
+incluindo IDs manipuláveis, operações em lote e ações administrativas.
+Em PostgreSQL/Supabase, revise RLS, policies, papéis e acessos privilegiados.
+Em Firebase, revise Security Rules e SDKs privilegiados; são controles distintos.
+
+Com contas sintéticas no ambiente local autorizado, prove no mínimo:
+
+- Visitante não autenticado recebe a recusa prevista.
+- Usuário A acessa seu recurso e não acessa o de B trocando o identificador.
+- Usuário comum não obtém a ação administrativa pela API direta.
+- Listagens, alterações e exclusões obedecem ao mesmo isolamento.
+
+Use testes de API e, quando houver interface, navegador conforme
+[verificar-trabalho](../../projeto/verificar-trabalho/SKILL.md).
+Não crie contas reais nem use dados de produção para essa prova.
+Sem aplicação executável ou identidades de teste, registre **não verificado**.
+Entregue matriz de permissões, resultados e achados sem segredos em
+`.agent-tests/security/`, usando o [modelo](../../../templates/revisao-seguranca/TEMPLATE.md).

package/.pbai4devs/skills/seguranca/revisar-seguranca/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: revisar-seguranca
+description: Revisa riscos de segurança com análise local, contexto e provas.
+---
+
+# Revisar segurança
+
+Defina o escopo: mudança ou projeto, dados sensíveis, stack e ambiente autorizado.
+Leia as regras de [segurança](../../../rules/seguranca/RULE.md) e
+[execução local](../../../rules/execucao-local/RULE.md). Não amplie o alvo.
+
+Use [auditar-seguranca](../../../commands/auditar-seguranca/COMMAND.md) para
+os scanners disponíveis e o [auditor](../../../agents/auditor-seguranca/AGENT.md)
+para interpretar os resultados. Uma ferramenta ausente ou base indisponível
+gera pendência; resultado vazio não substitui análise de contexto.
+
+Revise também autenticação, autorização por recurso, isolamento de dados,
+segredos e entradas conforme o [guia](../REFERENCE.md).
+Use [revisar-autorizacao](../revisar-autorizacao/SKILL.md) para permissões e
+[modelar-ameacas](../modelar-ameacas/SKILL.md) quando houver novas fronteiras.
+
+Registre achado, evidência, impacto, confiança e estado da triagem, sem valores
+secretos. Diferencie vulnerabilidade confirmada, suspeita e falso positivo.
+Prove cenários de API pelo terminal e fluxos web no navegador local autorizado,
+seguindo [verificar-trabalho](../../projeto/verificar-trabalho/SKILL.md).
+Salve o relatório em `.agent-tests/security/`; não declare o produto seguro
+com base apenas em scanners. Encaminhe correções à skill correspondente.

package/.pbai4devs/templates/README.md

@@ -28,6 +28,7 @@ enquanto o usuário estiver preparando somente a estrutura dos agentes.
 | [Revisão de entrega][revisao] | Implementação | Antes de commit/merge. |
 | [Release][release], [CHANGELOG][changelog] | Primeira entrega | Publicar. |
 | [SECURITY][security] | Suporte público | Política/suporte mudar. |
+| [Revisão de segurança][security-review] | Análise autorizada | Ameaças e provas. |
 | [Comando][comando] | Recurso agêntico | Entrada ou fluxo mudar. |
 
 Antes, inventarie e leia os documentos existentes com `atualizar-documentacao`.
@@ -65,4 +66,5 @@ Modelos, configurações e relatórios não são espelhados nas pastas dos agent
 [release]: release/TEMPLATE.md
 [changelog]: changelog/TEMPLATE.md
 [security]: seguranca/TEMPLATE.md
+[security-review]: revisao-seguranca/TEMPLATE.md
 [comando]: comando/TEMPLATE.md

package/.pbai4devs/templates/revisao-seguranca/TEMPLATE.md

@@ -0,0 +1,33 @@
+---
+description: Modelo de contexto, ameaças, achados e provas de segurança.
+status: modelo
+---
+
+# Revisão de segurança
+
+Preencha com fatos do escopo autorizado. Resultados e rascunhos ficam em
+`.agent-tests/security/`; combine o destino de documentação permanente.
+Este modelo complementa o relatório JSON dos scanners, sem substituir suas provas.
+
+## Contexto
+
+Alvo, alteração, ambiente, ativos, atores, operações e fronteiras de confiança.
+Registre fontes, hipóteses e dúvidas; não preencha lacunas com suposições.
+
+## Ameaças e controles
+
+| Ameaça | Pré-condição | Impacto | Controle existente | Teste necessário |
+| --- | --- | --- | --- | --- |
+| A definir | A confirmar | A confirmar | Evidência | Resultado esperado |
+
+## Achados
+
+| ID | Local | Evidência sem segredo | Confiança | Estado | Próxima ação |
+| --- | --- | --- | --- | --- | --- |
+| SEC-001 | Arquivo/linha | Evidência | A avaliar | A triar | Responsável |
+
+## Validação
+
+Critério, comando ou cenário, resultado, caminho da prova e limitações.
+Separe o que passou, falhou, não se aplica e não foi executado.
+Registre revisão independente e risco residual antes de concluir.