@boyingliu01/xp-gate 0.18.4 → 0.19.0

package/skills/clipboard-vision/__tests__/clipboard-vision-distribution.test.cjs

@@ -0,0 +1,65 @@
+/**
+ * @test REQ-379 clipboard vision distribution
+ * @intent Verify every registry, mirror, and packed artifact includes the canonical skill
+ * @covers AC-379-07
+ */
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+let repoRoot = path.resolve(__dirname, '..');
+while (!fs.existsSync(path.join(repoRoot, 'src', 'npm-package', 'lib', 'install-skill.js'))) {
+  const parent = path.dirname(repoRoot);
+  if (parent === repoRoot) throw new Error('Unable to locate xp-gate repository root');
+  repoRoot = parent;
+}
+
+describe('clipboard-vision distribution', () => {
+  it.each([
+    'scripts/build-plugin.mjs',
+    'scripts/build-plugin.sh',
+    'scripts/test-plugins.mjs',
+    'scripts/test-plugins.sh',
+    'src/npm-package/scripts/sync-package-content.js',
+    'plugins/opencode/scripts/prepack.cjs',
+    'src/npm-package/plugins/opencode/scripts/prepack.cjs',
+    'src/npm-package/lib/install-skill.js',
+  ])('registers clipboard-vision in %s', (relativePath) => {
+    expect(fs.readFileSync(path.join(repoRoot, relativePath), 'utf8')).toContain('clipboard-vision');
+  });
+
+  it.each([
+    'src/npm-package/skills/clipboard-vision',
+    'plugins/claude-code/skills/clipboard-vision',
+    'plugins/opencode/skills/clipboard-vision',
+    'plugins/qoder/skills/clipboard-vision',
+    'src/npm-package/plugins/claude-code/skills/clipboard-vision',
+    'src/npm-package/plugins/opencode/skills/clipboard-vision',
+    'src/npm-package/plugins/qoder/skills/clipboard-vision',
+  ])('matches canonical files in %s', (relativePath) => {
+    for (const file of ['SKILL.md', 'scripts/clipboard-vision.sh', 'scripts/clipboard-vision.ps1']) {
+      const canonical = fs.readFileSync(path.join(repoRoot, 'skills', 'clipboard-vision', file));
+      expect(fs.readFileSync(path.join(repoRoot, relativePath, file)).equals(canonical)).toBe(true);
+    }
+  });
+
+  it('includes canonical and plugin paths in the npm tarball', () => {
+    const result = spawnSync('npm', ['pack', '--dry-run', '--json', '--ignore-scripts'], {
+      cwd: path.join(repoRoot, 'src', 'npm-package'), encoding: 'utf8',
+    });
+    expect(result.status, result.stderr).toBe(0);
+    const files = JSON.parse(result.stdout)[0].files.map((entry) => entry.path);
+    for (const file of [
+      'skills/clipboard-vision/SKILL.md',
+      'plugins/claude-code/skills/clipboard-vision/SKILL.md',
+      'plugins/opencode/skills/clipboard-vision/SKILL.md',
+      'plugins/qoder/skills/clipboard-vision/SKILL.md',
+    ]) expect(files).toContain(file);
+  });
+
+  it('requires clipboard-vision in the independent sync test registry', () => {
+    const content = fs.readFileSync(path.join(repoRoot, 'src/npm-package/scripts/__tests__/sync-package-content.test.js'), 'utf8');
+    const start = content.indexOf('const CORE_SKILLS = [');
+    expect(content.slice(start, content.indexOf('];', start))).toContain("'clipboard-vision'");
+  });
+});

package/skills/clipboard-vision/__tests__/clipboard-vision-security.test.cjs

@@ -0,0 +1,185 @@
+/**
+ * @test REQ-379 clipboard vision security hardening
+ * @intent Verify credential transport, endpoint-bound consent, literal loopback trust, and output no-follow behavior
+ * @covers AC-379-02, AC-379-03, AC-379-04, AC-379-06
+ */
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+const SCRIPT = path.join(ROOT, 'scripts', 'clipboard-vision.sh');
+const POWERSHELL_SCRIPT = path.join(ROOT, 'scripts', 'clipboard-vision.ps1');
+const DOC = path.join(ROOT, 'SKILL.md');
+const SECRET = 'argv-secret-must-not-leak';
+
+function canonicalDestination(base) {
+  const url = new URL(base);
+  const scheme = url.protocol.slice(0, -1).toLowerCase();
+  const hostname = url.hostname.toLowerCase();
+  const port = url.port || (scheme === 'https' ? '443' : '80');
+  const basePath = url.pathname.replace(/\/+$/, '') || '';
+  const host = hostname.includes(':') ? `[${hostname}]` : hostname;
+  return `${scheme}://${host}:${port}${basePath}/chat/completions`;
+}
+
+function token(base, model = 'fixture-model') {
+  return crypto.createHash('sha256').update(`${canonicalDestination(base)}\n${model}`).digest('hex');
+}
+
+function fixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'clipboard-security-'));
+  const bin = path.join(root, 'bin');
+  const temp = path.join(root, 'temp');
+  fs.mkdirSync(bin);
+  fs.mkdirSync(temp);
+  const image = path.join(root, 'image.png');
+  fs.writeFileSync(image, Buffer.from('89504e470d0a1a0a', 'hex'));
+  const argv = path.join(root, 'curl-argv');
+  const authMode = path.join(root, 'auth-mode');
+  const clipboard = path.join(root, 'clipboard-count');
+  const network = path.join(root, 'network-count');
+  fs.writeFileSync(path.join(bin, 'pngpaste'), `#!/usr/bin/env bash
+printf x >> "${clipboard}"
+cp "${image}" "$1"
+`, { mode: 0o755 });
+  fs.writeFileSync(path.join(bin, 'curl'), `#!/usr/bin/env bash
+printf x >> "${network}"
+printf '%s\n' "$@" > "${argv}"
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = '--header' ] && [[ "$2" = @* ]]; then stat -c '%a' "\${2#@}" > "${authMode}"; shift 2; continue; fi
+  if [ "$1" = '--output' ]; then out="$2"; shift 2; continue; fi
+  if [ "$1" = '--write-out' ]; then shift 2; continue; fi
+  shift
+done
+printf '%s' '{"choices":[{"message":{"content":"secure result"}}]}' > "$out"
+printf 200
+`, { mode: 0o755 });
+  return { root, bin, temp, argv, authMode, clipboard, network };
+}
+
+function run(state, base, args = [], env = {}) {
+  return spawnSync('bash', [SCRIPT, ...args], {
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      PATH: `${state.bin}:${process.env.PATH}`,
+      TMPDIR: state.temp,
+      CLIPBOARD_VISION_API_BASE: base,
+      CLIPBOARD_VISION_MODEL: 'fixture-model',
+      CLIPBOARD_VISION_API_KEY: SECRET,
+      ...env,
+    },
+  });
+}
+
+function count(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf8').length : 0;
+}
+
+describe('clipboard-vision security boundaries', () => {
+  let state;
+  beforeEach(() => { state = fixture(); });
+  afterEach(() => { fs.rmSync(state.root, { recursive: true, force: true }); });
+
+  it('keeps API credentials out of curl argv and cleans restrictive auth files', () => {
+    const result = run(state, 'http://127.0.0.1:11434/v1');
+
+    expect(result.status, `${result.stdout}${result.stderr}`).toBe(0);
+    expect(fs.readFileSync(state.argv, 'utf8')).not.toContain(SECRET);
+    expect(fs.readFileSync(state.authMode, 'utf8').trim()).toBe('600');
+    expect(fs.readdirSync(state.temp)).toEqual([]);
+  });
+
+  it.each([
+    ['scheme', 'http://vision.example.test/v1'],
+    ['port', 'https://vision.example.test:8443/v1'],
+    ['path', 'https://vision.example.test/other'],
+  ])('rejects a token after %s changes before clipboard or network', (_field, changedBase) => {
+    const stale = token('https://vision.example.test/v1');
+    const result = run(state, changedBase, ['--allow-remote', '--confirm-remote', stale]);
+
+    expect(result.status).not.toBe(0);
+    expect(count(state.clipboard)).toBe(0);
+    expect(count(state.network)).toBe(0);
+  });
+
+  it('rejects query and fragment components before clipboard or network', () => {
+    for (const base of ['https://vision.example.test/v1?tenant=a', 'https://vision.example.test/v1#fragment']) {
+      const result = run(state, base, ['--allow-remote', '--confirm-remote', token('https://vision.example.test/v1')]);
+      expect(result.status).not.toBe(0);
+    }
+    expect(count(state.clipboard)).toBe(0);
+    expect(count(state.network)).toBe(0);
+  });
+
+  it('treats localhost as remote and literal IPv4 and IPv6 loopback as local', () => {
+    const localhost = run(state, 'http://localhost:11434/v1');
+    const ipv4 = run(state, 'http://127.9.8.7:11434/v1');
+    const ipv6 = run(state, 'http://[::1]:11434/v1');
+
+    expect(localhost.status).not.toBe(0);
+    expect(ipv4.status, ipv4.stderr).toBe(0);
+    expect(ipv6.status, ipv6.stderr).toBe(0);
+  });
+
+  it('reuses a stable token only for the same canonical endpoint and exact model', () => {
+    const base = 'https://VISION.example.test/v1/';
+    const confirmation = token(base);
+    const first = run(state, base, ['--allow-remote', '--confirm-remote', confirmation]);
+    const second = run(state, base, ['--allow-remote', '--confirm-remote', confirmation]);
+    const changedModel = run(state, base, ['--allow-remote', '--confirm-remote', confirmation], { CLIPBOARD_VISION_MODEL: 'other-model' });
+
+    expect(first.status).toBe(0);
+    expect(second.status).toBe(0);
+    expect(changedModel.status).not.toBe(0);
+  });
+
+  it('rejects --output and never writes a user-selected path', () => {
+    const outputPath = path.join(state.root, 'output.txt');
+    const result = run(state, 'http://127.0.0.1:11434/v1', ['--output', outputPath]);
+
+    expect(result.status).not.toBe(0);
+    expect(fs.existsSync(outputPath)).toBe(false);
+  });
+
+  it('documents stable consent artifact and no-follow output behavior', () => {
+    const content = fs.readFileSync(DOC, 'utf8');
+    expect(content).toContain('consent artifact');
+    expect(content).toContain('canonical endpoint');
+    expect(content).toContain('stdout-only');
+    expect(content).toContain('not persisted');
+  });
+
+  it('documents the ephemeral mode-600 auth-header file and cleanup accurately', () => {
+    const content = fs.readFileSync(DOC, 'utf8');
+    expect(content).toContain('mode 600');
+    expect(content).toContain('ephemeral auth-header file');
+    expect(content).toContain('removed during cleanup');
+    expect(content).not.toContain('Never put secrets in arguments, files, logs, or errors');
+  });
+
+  it('requires PowerShell behavior cases through the executable script seams', () => {
+    const script = fs.readFileSync(POWERSHELL_SCRIPT, 'utf8');
+    const harness = fs.readFileSync(path.join(ROOT, '__tests__', 'clipboard-vision.Tests.ps1'), 'utf8');
+    expect(harness).toMatch(/Describe\s+['"]clipboard-vision PowerShell behavior['"]\s+\{/);
+    expect(harness.match(/\bIt\s+['"]/g)?.length).toBeGreaterThanOrEqual(8);
+    expect(script).not.toMatch(/\$Output|Set-Content.*Result/);
+    expect(script).not.toMatch(/\[string\]\$ConfirmRemote,\s*\)/);
+    expect(harness).toContain('No output parameter');
+    for (const marker of [
+      'CV_TEST_MALFORMED_JSON',
+      'CV_TEST_NON_STRING',
+      'CV_TEST_HTTP_FAILURE',
+      'CLIPBOARD_VISION_MAX_BYTES',
+      'No output parameter',
+      'http://localhost:',
+      'http://[::1]:',
+      'https://vision.example.test:8443/',
+    ]) {
+      expect(harness).toContain(marker);
+    }
+  });
+});

package/skills/clipboard-vision/__tests__/clipboard-vision.Tests.ps1

@@ -0,0 +1,138 @@
+# @test REQ-379 Windows privacy-safe clipboard vision
+# @intent Verify bound remote consent and redirect blocking on Windows CI
+# @covers AC-379-02, AC-379-03, AC-379-06
+
+Describe 'clipboard-vision PowerShell behavior' {
+    BeforeAll {
+        $ScriptPath = Join-Path $PSScriptRoot '..\scripts\clipboard-vision.ps1'
+        $Fixture = Join-Path ([IO.Path]::GetTempPath()) ("clipboard-vision-pester-" + [Guid]::NewGuid())
+        $ImagePath = Join-Path $Fixture 'clipboard.png'
+        $CapturePath = Join-Path $Fixture 'request.json'
+        New-Item -ItemType Directory -Path $Fixture | Out-Null
+        [IO.File]::WriteAllBytes($ImagePath, [byte[]](137, 80, 78, 71, 13, 10, 26, 10))
+        $env:CLIPBOARD_VISION_TEST_IMAGE = $ImagePath
+        $env:CLIPBOARD_VISION_TEST_HTTP_CAPTURE = $CapturePath
+        $env:CLIPBOARD_VISION_MODEL = 'windows-fixture-model'
+
+        $ConsentBytes = [Text.Encoding]::UTF8.GetBytes("https://vision.example.test:443/v1/chat/completions`nwindows-fixture-model")
+        $Hasher = [Security.Cryptography.SHA256]::Create()
+        try {
+            $Token = ([BitConverter]::ToString($Hasher.ComputeHash($ConsentBytes))).Replace('-', '').ToLowerInvariant()
+        } finally {
+            $Hasher.Dispose()
+        }
+    }
+
+    BeforeEach {
+        Remove-Item -LiteralPath $CapturePath -ErrorAction SilentlyContinue
+        Remove-Item Env:CLIPBOARD_VISION_MAX_BYTES -ErrorAction SilentlyContinue
+        Remove-Item Env:CV_TEST_MALFORMED_JSON -ErrorAction SilentlyContinue
+        Remove-Item Env:CV_TEST_NON_STRING -ErrorAction SilentlyContinue
+        Remove-Item Env:CV_TEST_HTTP_FAILURE -ErrorAction SilentlyContinue
+        $env:CLIPBOARD_VISION_API_BASE = 'https://VISION.Example.Test/v1'
+    }
+
+    AfterAll {
+        Remove-Item Env:CLIPBOARD_VISION_TEST_IMAGE -ErrorAction SilentlyContinue
+        Remove-Item Env:CLIPBOARD_VISION_TEST_HTTP_CAPTURE -ErrorAction SilentlyContinue
+        Remove-Item Env:CLIPBOARD_VISION_API_BASE -ErrorAction SilentlyContinue
+        Remove-Item Env:CLIPBOARD_VISION_MODEL -ErrorAction SilentlyContinue
+        Remove-Item Env:CLIPBOARD_VISION_MAX_BYTES -ErrorAction SilentlyContinue
+        Remove-Item Env:CV_TEST_MALFORMED_JSON -ErrorAction SilentlyContinue
+        Remove-Item Env:CV_TEST_NON_STRING -ErrorAction SilentlyContinue
+        Remove-Item Env:CV_TEST_HTTP_FAILURE -ErrorAction SilentlyContinue
+        Remove-Item -LiteralPath $Fixture -Recurse -Force -ErrorAction SilentlyContinue
+    }
+
+    It 'rejects invalid endpoints before disclosure or HTTP capture' {
+        foreach ($InvalidBase in @(
+            'relative/path',
+            'ftp://vision.example.test/v1',
+            'file:///tmp/vision',
+            'https://user:secret@vision.example.test/v1'
+        )) {
+            $env:CLIPBOARD_VISION_API_BASE = $InvalidBase
+            $Disclosure = { & $ScriptPath -AllowRemote -ConfirmRemote 'unused' 2>&1 | Out-String }
+            $Disclosure | Should -Throw
+            Test-Path $CapturePath | Should -BeFalse
+            try { & $Disclosure | Out-Null } catch { $_.Exception.Message | Should -Not -Match 'Remote disclosure' }
+        }
+    }
+
+    It 'rejects stale consent after endpoint scheme port or path changes' {
+        foreach ($ChangedBase in @(
+            'http://vision.example.test/v1',
+            'https://vision.example.test:8443/v1',
+            'https://vision.example.test/other'
+        )) {
+            $env:CLIPBOARD_VISION_API_BASE = $ChangedBase
+            { & $ScriptPath -AllowRemote -ConfirmRemote $Token 2>$null } | Should -Throw
+            Test-Path $CapturePath | Should -BeFalse
+        }
+    }
+
+    It 'rejects an unrelated stale confirmation token' {
+        { & $ScriptPath -AllowRemote -ConfirmRemote 'stale-token' 2>$null } | Should -Throw
+        Test-Path $CapturePath | Should -BeFalse
+    }
+
+    It 'returns the successful response and captures one request' {
+        $Result = & $ScriptPath -AllowRemote -ConfirmRemote $Token 2>$null
+
+        $Result | Should -BeExactly 'test description'
+        Test-Path $CapturePath | Should -BeTrue
+        (Get-Content -LiteralPath $CapturePath -Raw) | Should -Match 'windows-fixture-model'
+    }
+
+    It 'rejects malformed and non-string responses' {
+        $env:CV_TEST_MALFORMED_JSON = '1'
+        { & $ScriptPath -AllowRemote -ConfirmRemote $Token 2>$null } | Should -Throw
+        Remove-Item Env:CV_TEST_MALFORMED_JSON
+
+        $env:CV_TEST_NON_STRING = '1'
+        { & $ScriptPath -AllowRemote -ConfirmRemote $Token 2>$null } | Should -Throw '*redacted*'
+    }
+
+    It 'redacts HTTP failures without exposing the secret response body' {
+        $env:CV_TEST_HTTP_FAILURE = '1'
+        $Failure = { & $ScriptPath -AllowRemote -ConfirmRemote $Token 2>&1 }
+
+        $Failure | Should -Throw '*redacted*'
+        try { & $Failure | Out-Null } catch {
+            $_.Exception.Message | Should -Not -Match 'secret'
+        }
+    }
+
+    It 'rejects an oversized image' {
+        $env:CLIPBOARD_VISION_MAX_BYTES = '4'
+
+        { & $ScriptPath -AllowRemote -ConfirmRemote $Token 2>$null } | Should -Throw '*exceeds*'
+    }
+
+    It 'enforces No output parameter support without writing a file' {
+        $OutputPath = Join-Path $Fixture 'result.txt'
+
+        { & $ScriptPath -AllowRemote -ConfirmRemote $Token -Output $OutputPath 2>$null } | Should -Throw
+        Test-Path $OutputPath | Should -BeFalse
+    }
+
+    It 'treats localhost as remote and literal IPv4 and IPv6 loopback as local' {
+        $env:CLIPBOARD_VISION_API_BASE = 'http://localhost:11434/v1'
+        { & $ScriptPath 2>$null } | Should -Throw
+
+        foreach ($LoopbackBase in @('http://127.9.8.7:11434/v1', 'http://[::1]:11434/v1')) {
+            $env:CLIPBOARD_VISION_API_BASE = $LoopbackBase
+            & $ScriptPath 2>$null | Should -BeExactly 'test description'
+        }
+    }
+
+    It 'keeps redirect blocking and executable test seams in the production script' {
+        $Content = Get-Content -LiteralPath $ScriptPath -Raw
+
+        $Content | Should -Match 'MaximumRedirection\s+0'
+        $Content | Should -Match 'SHA256'
+        $Content | Should -Match 'CLIPBOARD_VISION_TEST_IMAGE'
+        $Content | Should -Match 'CLIPBOARD_VISION_TEST_HTTP_CAPTURE'
+        $Content | Should -Not -Match '\$Output|Set-Content.*Result'
+    }
+}

package/skills/clipboard-vision/__tests__/clipboard-vision.test.cjs

@@ -0,0 +1,273 @@
+/**
+ * @test REQ-379 privacy-safe clipboard vision
+ * @intent Verify one-shot clipboard image analysis enforces local-first privacy boundaries
+ * @covers AC-379-01, AC-379-02, AC-379-03, AC-379-04, AC-379-05, AC-379-06
+ */
+const fs = require('fs');
+const crypto = require('crypto');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+const BASH_SCRIPT = path.join(ROOT, 'scripts', 'clipboard-vision.sh');
+const POWERSHELL_SCRIPT = path.join(ROOT, 'scripts', 'clipboard-vision.ps1');
+const SECRET = 'cv-secret-must-never-leak';
+
+function writeExecutable(file, content) {
+  fs.writeFileSync(file, content, { mode: 0o755 });
+}
+
+function createFixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'clipboard-vision-test-'));
+  const bin = path.join(root, 'bin');
+  const temp = path.join(root, 'temp');
+  fs.mkdirSync(bin);
+  fs.mkdirSync(temp);
+  const image = path.join(root, 'clipboard.png');
+  fs.writeFileSync(image, Buffer.from('89504e470d0a1a0a', 'hex'));
+  const clipboardCount = path.join(root, 'clipboard-count');
+  const curlCount = path.join(root, 'curl-count');
+  const curlArgs = path.join(root, 'curl-args');
+  const curlBody = path.join(root, 'curl-body');
+
+  writeExecutable(path.join(bin, 'pngpaste'), `#!/usr/bin/env bash
+set -euo pipefail
+printf x >> "${clipboardCount}"
+cp "${image}" "$1"
+`);
+  writeExecutable(path.join(bin, 'curl'), `#!/usr/bin/env bash
+set -euo pipefail
+printf x >> "${curlCount}"
+printf '%s\n' "$@" > "${curlArgs}"
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = '--data-binary' ]; then cp "\${2#@}" "${curlBody}"; shift 2; continue; fi
+  if [ "$1" = '--output' ]; then output="$2"; shift 2; continue; fi
+  if [ "$1" = '--write-out' ]; then shift 2; continue; fi
+  shift
+done
+if [ -n "\${CV_FAKE_RESPONSE:-}" ]; then
+  printf '%s' "$CV_FAKE_RESPONSE" > "$output"
+else
+  printf '%s' '{"choices":[{"message":{"content":"described safely"}}]}' > "$output"
+fi
+printf '%s' "\${CV_FAKE_STATUS:-200}"
+`);
+
+  return { root, bin, temp, image, clipboardCount, curlCount, curlArgs, curlBody };
+}
+
+function run(fixture, args = [], env = {}) {
+  return spawnSync('bash', [BASH_SCRIPT, ...args], {
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      PATH: `${fixture.bin}:${process.env.PATH}`,
+      TMPDIR: fixture.temp,
+      CLIPBOARD_VISION_MODEL: 'fixture-model',
+      CLIPBOARD_VISION_API_KEY: SECRET,
+      ...env,
+    },
+  });
+}
+
+function combined(result) {
+  return `${result.stdout}${result.stderr}`;
+}
+
+function count(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf8').length : 0;
+}
+
+function consentToken(hostname, model, base = `https://${hostname}/v1`) {
+  const url = new URL(base);
+  const scheme = url.protocol.slice(0, -1).toLowerCase();
+  const normalizedHost = url.hostname.toLowerCase();
+  const port = url.port || (scheme === 'https' ? '443' : '80');
+  const displayHost = normalizedHost.includes(':') ? `[${normalizedHost}]` : normalizedHost;
+  const endpoint = `${scheme}://${displayHost}:${port}${url.pathname.replace(/\/+$/, '')}/chat/completions`;
+  return crypto.createHash('sha256').update(`${endpoint}\n${model}`, 'utf8').digest('hex');
+}
+
+function assertNoTempFiles(fixture) {
+  expect(fs.readdirSync(fixture.temp)).toEqual([]);
+}
+
+describe('clipboard-vision Bash client', () => {
+  let fixture;
+
+  beforeEach(() => {
+    fixture = createFixture();
+  });
+
+  afterEach(() => {
+    fs.rmSync(fixture.root, { recursive: true, force: true });
+  });
+
+  it('fails without model configuration before reading clipboard or calling network', () => {
+    const result = run(fixture, [], { CLIPBOARD_VISION_MODEL: '' });
+
+    expect(result.status).not.toBe(0);
+    expect(count(fixture.clipboardCount)).toBe(0);
+    expect(count(fixture.curlCount)).toBe(0);
+  });
+
+  it('rejects a non-loopback endpoint in local mode before reading clipboard', () => {
+    const result = run(fixture, [], { CLIPBOARD_VISION_API_BASE: 'https://vision.example.test/v1' });
+
+    expect(result.status).not.toBe(0);
+    expect(count(fixture.clipboardCount)).toBe(0);
+    expect(count(fixture.curlCount)).toBe(0);
+  });
+
+  it('requires both remote opt-in and destination-bound confirmation', () => {
+    const endpoint = { CLIPBOARD_VISION_API_BASE: 'https://vision.example.test/v1' };
+    const optInOnly = run(fixture, ['--allow-remote'], endpoint);
+    const confirmationOnly = run(fixture, ['--confirm-remote', consentToken('vision.example.test', 'fixture-model')], endpoint);
+
+    expect(optInOnly.status).not.toBe(0);
+    expect(confirmationOnly.status).not.toBe(0);
+    expect(count(fixture.clipboardCount)).toBe(0);
+    expect(count(fixture.curlCount)).toBe(0);
+  });
+
+  it('prints disclosure and expected token before rejecting missing confirmation', () => {
+    const result = run(fixture, ['--allow-remote'], {
+      CLIPBOARD_VISION_API_BASE: 'https://vision.example.test/v1',
+    });
+
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toContain('vision.example.test');
+    expect(result.stderr).toContain('fixture-model');
+    expect(result.stderr.toLowerCase()).toContain('image');
+    expect(result.stderr).toContain(consentToken('vision.example.test', 'fixture-model'));
+    expect(count(fixture.clipboardCount)).toBe(0);
+    expect(count(fixture.curlCount)).toBe(0);
+  });
+
+  it('accepts the confirmation token bound to normalized hostname and exact model', () => {
+    const token = consentToken('vision.example.test', 'fixture-model');
+    const result = run(fixture, ['--allow-remote', '--confirm-remote', token], {
+      CLIPBOARD_VISION_API_BASE: 'https://VISION.Example.Test/v1',
+    });
+
+    expect(result.status, combined(result)).toBe(0);
+    expect(count(fixture.clipboardCount)).toBe(1);
+    expect(count(fixture.curlCount)).toBe(1);
+  });
+
+  it('rejects a token for a changed destination before clipboard or network', () => {
+    const staleToken = consentToken('old.example.test', 'fixture-model');
+    const result = run(fixture, ['--allow-remote', '--confirm-remote', staleToken], {
+      CLIPBOARD_VISION_API_BASE: 'https://vision.example.test/v1',
+    });
+
+    expect(result.status).not.toBe(0);
+    expect(count(fixture.clipboardCount)).toBe(0);
+    expect(count(fixture.curlCount)).toBe(0);
+  });
+
+  it('rejects a token for a changed model before clipboard or network', () => {
+    const staleToken = consentToken('vision.example.test', 'old-model');
+    const result = run(fixture, ['--allow-remote', '--confirm-remote', staleToken], {
+      CLIPBOARD_VISION_API_BASE: 'https://vision.example.test/v1',
+    });
+
+    expect(result.status).not.toBe(0);
+    expect(count(fixture.clipboardCount)).toBe(0);
+    expect(count(fixture.curlCount)).toBe(0);
+  });
+
+  it('never exposes the API key in output or request JSON', () => {
+    const result = run(fixture);
+
+    expect(result.status, combined(result)).toBe(0);
+    expect(combined(result)).not.toContain(SECRET);
+    expect(fs.readFileSync(fixture.curlBody, 'utf8')).not.toContain(SECRET);
+  });
+
+  it('rejects oversized clipboard images before network access', () => {
+    fs.writeFileSync(fixture.image, Buffer.alloc(33));
+    const result = run(fixture, [], { CLIPBOARD_VISION_MAX_BYTES: '32' });
+
+    expect(result.status).not.toBe(0);
+    expect(count(fixture.curlCount)).toBe(0);
+    assertNoTempFiles(fixture);
+  });
+
+  it('removes temporary files after success', () => {
+    const result = run(fixture);
+
+    expect(result.status, combined(result)).toBe(0);
+    expect(result.stdout.trim()).toBe('described safely');
+    assertNoTempFiles(fixture);
+  });
+
+  it('redacts API failure bodies and removes temporary files after failure', () => {
+    const response = `upstream body contains ${SECRET}`;
+    const result = run(fixture, [], { CV_FAKE_STATUS: '500', CV_FAKE_RESPONSE: response });
+
+    expect(result.status).not.toBe(0);
+    expect(combined(result)).not.toContain(response);
+    expect(combined(result)).not.toContain(SECRET);
+    assertNoTempFiles(fixture);
+  });
+
+  it('performs exactly one clipboard read and one request per explicit invocation', () => {
+    const result = run(fixture);
+
+    expect(result.status, combined(result)).toBe(0);
+    expect(count(fixture.clipboardCount)).toBe(1);
+    expect(count(fixture.curlCount)).toBe(1);
+  });
+});
+
+describe('clipboard-vision PowerShell contract', () => {
+  it('keeps credentials in the environment and enforces bound consent, bounds, and cleanup', () => {
+    const content = fs.readFileSync(POWERSHELL_SCRIPT, 'utf8');
+
+    expect(content).toMatch(/\$env:CLIPBOARD_VISION_API_KEY/);
+    expect(content).toMatch(/AllowRemote/);
+    expect(content).toMatch(/ConfirmRemote/);
+    expect(content).toMatch(/SHA256/i);
+    expect(content).toMatch(/CLIPBOARD_VISION_MAX_BYTES/);
+    expect(content).toMatch(/finally\s*\{/i);
+    expect(content).toMatch(/Remove-Item/);
+    expect(content).not.toMatch(/https:\/\/(?!127\.0\.0\.1|localhost|\[::1\])/);
+  });
+
+  it('disables HTTP redirects so loopback cannot forward the clipboard body remotely', () => {
+    const content = fs.readFileSync(POWERSHELL_SCRIPT, 'utf8');
+
+    expect(content).toMatch(/MaximumRedirection\s+0/);
+  });
+
+  it('validates an absolute HTTP(S) URI without credentials before disclosure or seams', () => {
+    const content = fs.readFileSync(POWERSHELL_SCRIPT, 'utf8');
+    const validationPosition = content.indexOf('IsAbsoluteUri');
+    const disclosurePosition = content.indexOf('Remote disclosure');
+    const clipboardPosition = content.indexOf('CLIPBOARD_VISION_TEST_IMAGE');
+
+    expect(validationPosition).toBeGreaterThan(0);
+    expect(content).toMatch(/Scheme[^\n]+https?/i);
+    expect(content).toMatch(/UserInfo/);
+    expect(validationPosition).toBeLessThan(disclosurePosition);
+    expect(validationPosition).toBeLessThan(clipboardPosition);
+  });
+
+  it('ships a discoverable Windows-CI executable behavior harness', () => {
+    expect(fs.existsSync(path.join(ROOT, '__tests__', 'clipboard-vision.Tests.ps1'))).toBe(true);
+  });
+
+  it('wires the discoverable PowerShell harness into windows-latest CI', () => {
+    let repoRoot = ROOT;
+    while (!fs.existsSync(path.join(repoRoot, '.github', 'workflows', 'cross-platform-ci.yml'))) {
+      repoRoot = path.dirname(repoRoot);
+    }
+    const workflow = fs.readFileSync(path.join(repoRoot, '.github', 'workflows', 'cross-platform-ci.yml'), 'utf8');
+
+    expect(workflow).toContain('windows-latest');
+    expect(workflow).toContain('clipboard-vision.Tests.ps1');
+    expect(workflow).toMatch(/shell:\s*pwsh/);
+  });
+});