slaunt 0.1.17 → 0.1.19

package/README.md

@@ -1,138 +1,33 @@
-# Slaunt Agent Access Audit
+# Slaunt native OAuth installer — development build
 
-See what Claude and Codex can do through their configured MCP servers.
+This package contains the client-side one-sign-in OAuth handoff for Codex and Claude Code. Each native client stores its own OAuth credentials; bootstrap credentials stay in CLI memory during setup. The Desktop vault is not used for the native OAuth handoff.
 
-```sh
-npx slaunt audit
-```
-
-No account or database configuration is required.
-
-Slaunt discovers local MCP configurations—including the active Claude Code project scope—requests each server's declared tool list, classifies those tools, and identifies risky permissions or combinations. It then writes a private HTML report on your machine.
-
-Every discovered server also receives a grounded explanation. The npm install
-includes a quantized Apache-2.0 TinyLlama 1.1B model through two pinned data
-dependencies and runs it locally through `node-llama-cpp` with a fixed
-evidence-only prompt containing the server's declared `tools/list` inventory.
-The model parts are reassembled into a user cache and SHA-256 verified before
-loading. Slaunt probes the selected native backend before generating; if a GPU
-backend is present but cannot create a context, it retries with a cached or
-locally built CPU backend. The first CPU recovery may take a little longer while
-`node-llama-cpp` builds its backend. If no usable runtime is available, the
-report still explains every server with a deterministic local fallback and marks
-that source explicitly. Generated text must pass a local completeness and
-evidence-grounding check; malformed model output is discarded rather than shown
-in the report. No server configuration values or audit data are sent to a
-remote model.
-
-Reports count actual client/scope bindings separately from unique server names,
-so the same server name configured for Claude and Codex is not silently merged.
-
-The audit-only release does not include `slaunt connect`.
-
-## What the audit checks
+The Codex hook configuration calls `tool_authorize_codex` through the configured remote Slaunt MCP server. It passes only session, turn, tool name and tool-use metadata. The companion Central development package contains the authenticated server-side decision. For the default Codex configuration no local command hook is required. Optional legacy chat-capture and the standalone command supervisor are separate development components.
 
-- Claude Code, Claude Desktop, Codex CLI, and Codex Desktop configurations
-- Claude Code user-level and active project-scoped MCP server entries
-- MCP servers declared in JSON or TOML
-- Tools exposed by each server
-- Sensitive capabilities such as shell execution, secret access, code changes, and production deployment
-- Risky combinations across servers and clients
-- Unknown tools that still need classification review
+**Not deployed or verified for production installation.** The CLI and persistent Claude broker are wired locally, but production setup remains disabled: the companion Central changes and migration 031 are not deployed, and the complete native OAuth and Keychain flow has not been verified on a clean Mac. OAuth retries use proof-bound receipts and recover interrupted Supabase refreshes under a database lease. Codex can continue a tool call when an MCP hook is unavailable or fails; users accepted that tradeoff for this flow. A managed Codex policy prevents disabling the hook through Codex's hook browser, subject to the organization's managed configuration and client support.
 
-Slaunt performs the MCP initialization handshake and `tools/list`. It never calls
-`tools/call` or any other MCP tool.
+`src/setup/managed-policy.js` can generate a Codex managed MCP policy with `createCodexManagedPolicy()`. It does not install or activate the policy. Claude policy generation still requires a separately deployed guard executable. Claude command guards use `onFailure: "block"` and require Claude Code 2.1.295 or later.
 
-Protected HTTP/SSE servers can be authorized through the MCP SDK's browser OAuth
-flow. The interactive audit asks once before opening sign-in pages; use
-`--authorize-http-servers` for an explicit non-interactive choice. Endpoint-scoped
-OAuth state is cached locally with restrictive file permissions so a later audit
-can reuse the authorized session without another sign-in.
+The local OAuth integration uses installed native clients in isolated temporary homes and a simulated identity provider. The direct authorization hook has server-side runtime tests; an actual Codex tool call against production and a real authenticated user has not been verified.
 
-## Run modes
+Requirements for local tests: Node.js 20 or newer; Python 3 and both native client CLIs for the native integration test.
 
 ```sh
-# Normal interactive audit
-npx slaunt audit
-
-# Inspect configuration without starting local MCP processes
-npx slaunt audit --no-server-starts
-
-# Run non-interactively and allow declared tool-list requests
-npx slaunt audit --yes
-
-# Explicitly authorize protected HTTP/SSE servers for tools/list
-npx slaunt audit --authorize-http-servers --quick
-
-# Skip the paced terminal presentation
-npx slaunt audit --quick
-
-# Use only the bundled classification rules
-npx slaunt audit --offline
-
-# Produce redacted JSON without a report
-npx slaunt audit --json --no-report --no-server-starts
-```
-
-The interactive terminal view is a compact graphical evidence dashboard: one
-posture panel, one client/server access map, and one wrapped explanation stream.
-Inventory gaps are grouped once, and long explanations wrap across lines rather
-than being repeated in separate warning panels. Use `--quick` when a
-non-animated report is easier to scan.
-
-Run `npx slaunt audit --help` for all options. Node.js 20.17 or newer is required.
-
-## Privacy and consent
-
-- Tool names, descriptions, schemas, configuration values, findings, and reports stay local.
-- Slaunt downloads approved classification rules from a read-only Supabase catalog. It does not upload audit data.
-- Starting a configured stdio server requires interactive consent or `--allow-server-starts`.
-- Protected HTTP/SSE inventory requires the interactive browser prompt or explicit `--authorize-http-servers`.
-- OAuth client state and tokens, when authorized, stay in a local endpoint-scoped cache with 0700/0600 permissions.
-- Stdio starts receive configured variables and the MCP SDK's safe defaults; the full parent environment is passed only with explicit `--inherit-parent-env`.
-- Slaunt MCP installation happens only with `--install-slaunt`.
-- The HTML report opens only with `--open-report`.
-- Environment variables and HTTP header values are redacted from JSON and reports.
-
-If the remote catalog is unavailable, Slaunt uses a seven-day local cache and then its bundled rules. `--offline` disables the refresh entirely.
-
-The bundled model is the default. To use an already-running local Ollama
-model instead, set `SLAUNT_AUDIT_LLM_URL` (it must resolve to `localhost`,
-`127.0.0.1`, or `::1`) and optionally `SLAUNT_AUDIT_LLM_MODEL`.
-`SLAUNT_AUDIT_LLM_TIMEOUT_MS` controls either local path. The model manifest
-and attribution are in `models/`; `npm run verify:model` checks the pinned
-size and SHA-256 before publication.
-
-## How classification works
-
-Approved database rules and bundled rules map tool declarations to capabilities and risk levels. Matching happens locally. Slaunt then checks direct authority and cross-server attack paths, such as a client that can execute shell commands and read secrets.
-
-Unknown does not mean malicious. It means no approved rule matched the tool, so Slaunt treats it as potentially sensitive until reviewed.
-
-## Optional Slaunt MCP installation
-
-```sh
-npx slaunt audit --install-slaunt
+npm ci --ignore-scripts
+npm test
+npm run test:integration
 ```
 
-Installation is explicit, idempotent, backed up, atomic, permission-preserving, and symlink-safe. The default audit never edits client configuration.
+## Interactive setup
 
-## Audit limits
+Run `node bin/slaunt-hooks.js install` in an interactive terminal for a centered full-screen setup with an animated splash, logo, selection and progress. The layout adapts to terminal size. The original terminal screen is restored on exit, with the result printed afterward. Choose Codex, Claude Code, or both with the arrow keys or j/k. The recommended default is both clients. Pass `--client codex`, `--client claude`, or `--client both` to skip the picker. Escape, Ctrl-C, or Ctrl-D cancels the picker. The installer displays its current availability and exits without changing settings while the production integration remains gated.
 
-This is a declared-access audit. It does not inspect prompts, file contents,
-credentials, non-MCP agents, hidden provider scopes, client approval policy, or
-whether a tool has been used. It performs `initialize` and `tools/list` only.
-If a server cannot be inspected, its tool inventory remains unavailable; Slaunt
-does not treat that server as safe.
+Set `SLAUNT_REDUCED_MOTION=1` to disable animation, or set `NO_COLOR` to disable color. Small terminals use a compact terminal-cell rendering of the workspace Neue Haas wordmark; the ASCII logo remains on larger screens. Noninteractive and `TERM=dumb` terminals receive plain output and select both clients by default; CI skips interactive prompts and animation.
 
-## Development
+## Packaged KillBar helper
 
-```sh
-npm ci
-npm run check
-npm test
-```
+The development npm package includes an ad hoc-signed Apple Silicon helper as `release/SlauntKillBar.zip`. The installer checks the archive SHA-256, extracts it to an owner-only temporary directory, verifies its code signature and pinned code-directory hash, and verifies the installed copy before registering a launch agent. The archive and manifest are in the same package: their hashes detect accidental or partial modification but do not authenticate the publisher if an attacker can replace the entire package. Distribution must use a trusted npm release and account.
 
-The Supabase schema is in [`supabase/migrations`](supabase/migrations). Public clients receive only approved, active rules through column-scoped `SELECT`, forced Row Level Security, and no public mutation policy. Never ship or expose a Supabase secret key.
+The helper is not Developer ID signed or notarized. A local extraction and bridge-version test passed, but this does not establish Gatekeeper behavior for every download method, enrollment, Keychain access, or startup after login on another Mac. Intel Macs are unsupported by this artifact. The package remains private and has not been published.
 
-See [SECURITY.md](SECURITY.md) for the complete security boundary and vulnerability-reporting process.
+The setup flow checks the authenticated workspace when enrolling the helper, stores a separate guard grant in the helper's Keychain item, and registers per-user launch agents for KillBar and the Claude broker. The broker maintains separate Central connections for Claude sessions and denies guarded calls when authorization is unavailable. Existing installations are not replaced. Live production enrollment, Keychain access, background health, restart, and command delivery have not been verified.

package/bin/slaunt-hooks.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+'use strict';
+const {spawn}=require('node:child_process');
+const {ISSUER}=require('../src/setup-flow');
+const {readJson}=require('../src/read-json');
+const {createTerminal}=require('../src/tui');
+const {installFlow}=require('../src/install-flow');
+
+const MACOS_CODEX_APP = '/Applications/ChatGPT.app/Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS/codex';
+function probeExecutable(command, {signal, env}) {
+  if (signal?.aborted) return Promise.resolve('aborted');
+  return new Promise(resolve=>{
+    let child;try {child=spawn(command,['--version'],{stdio:'ignore',env});}catch{return resolve('failed');}
+    let finished=false;const finish=value=>{if(finished)return;finished=true;clearTimeout(timer);signal?.removeEventListener('abort',abort);resolve(value);};
+    const abort=()=>{child.kill('SIGKILL');finish('aborted');};
+    const timer=setTimeout(abort,10000);
+    signal?.addEventListener('abort',abort,{once:true});
+    if(signal?.aborted)abort();
+    child.once('error',error=>finish(error.code==='ENOENT'?'missing':'failed'));
+    child.once('close',code=>finish(code===0?'found':'failed'));
+  });
+}
+async function resolveClient(command, {signal, env=process.env, platform=process.platform, appCodexPath=MACOS_CODEX_APP} = {}) {
+  const result=await probeExecutable(command,{signal,env});
+  if(result==='found') return command;
+  // The macOS app bundles Codex without adding it to other terminal sessions' PATH.
+  if(result==='missing' && command==='codex' && platform==='darwin' && !signal?.aborted)
+    return await probeExecutable(appCodexPath,{signal,env})==='found' ? appCodexPath : null;
+  return null;
+}
+async function checkClient(command, options) { return Boolean(await resolveClient(command, options)); }
+
+async function main(args=process.argv.slice(2),dependencies={}) {
+  const terminal=dependencies.terminal||createTerminal();
+  const output=dependencies.output||process.stdout;
+  const env=dependencies.env||process.env;
+  const fetchImpl=dependencies.fetch||fetch;
+  const probe=dependencies.probe||resolveClient;
+  if(args.length===0||args[0]==='--help'){output.write('Usage: slaunt-hooks install [--client codex|claude|both]\nChecks setup availability for Codex and Claude Code.\n');return 0;}
+  if(args[0]!=='install'||(args.length!==1&&!(args.length===3&&args[1]==='--client'&&['codex','claude','both'].includes(args[2])))){terminal.fail('Invalid arguments.','Run slaunt-hooks --help.');return 2;}
+  const controller=new AbortController();
+  const probes=new Map();
+  const probeOnce=client=>{
+    if(!probes.has(client)) probes.set(client,Promise.resolve().then(()=>probe(client,{signal:controller.signal,env})));
+    return probes.get(client);
+  };
+  try {
+    await terminal.enter?.();
+    terminal.banner();
+    if(env.CODEX_HOME||env.CLAUDE_CONFIG_DIR){terminal.fail('Custom client directories are not supported.','No client settings were changed.');return 1;}
+    if(!args[2] && terminal.interactive && terminal.setClientAvailability){
+      for(const client of ['codex','claude']){
+        terminal.setClientAvailability(client,'checking');
+        void probeOnce(client).then(found=>{if(!controller.signal.aborted)terminal.setClientAvailability(client,found?'installed':'missing');},()=>{if(!controller.signal.aborted)terminal.setClientAvailability(client,'missing');});
+      }
+    }
+    const selection=args[2]||await terminal.selectClients();
+    if(!selection){terminal.fail('Setup cancelled.','No client settings were changed.');return 130;}
+    terminal.setSelection?.(selection);
+    const clients=selection==='both'?['codex','claude']:[selection];
+    const executablePaths={};
+    for(const client of clients){const label=client==='codex'?'Codex':'Claude Code';terminal.progress(`Checking ${label}`);const found=await probeOnce(client);if(!found){terminal.fail(`${label} could not be found or started.`,'Check that the client is installed and available in this terminal, then try again. No settings were changed.');return 1;}executablePaths[client]=typeof found==='string'?found:client;terminal.done(`${label} found`);}
+    terminal.progress('Checking Slaunt setup');
+    let metadata;try {const res=await fetchImpl(new URL('/.well-known/oauth-authorization-server',ISSUER),{redirect:'error',signal:AbortSignal.timeout(10000)});if(!res.ok)throw new Error();metadata=await readJson(res,32768);}catch{terminal.fail('Could not reach Slaunt setup.','Check your connection and try again. No settings were changed.');return 1;}
+    if(metadata.issuer!==ISSUER||metadata.slaunt_cli_setup_supported!==true){terminal.fail('Setup is not yet enabled on Slaunt.','No client settings were changed.');return 1;}
+    terminal.done('Slaunt setup available');
+    try {
+      const result=await (dependencies.installFlow||installFlow)({clients,executablePaths,terminal,fetchImpl});
+      if(result?.installed!==true)throw new Error('setup-incomplete');
+      terminal.success?.('Setup complete.','Selected clients and KillBar are connected.');
+      return 0;
+    } catch(error) {
+      const messages={'killbar-release-missing':'KillBar is missing from this installer.','killbar-release-unavailable':'KillBar release metadata is invalid.','killbar-release-untrusted':'KillBar could not be verified.','killbar-platform-unsupported':'This KillBar package requires an Apple Silicon Mac.','killbar-helper-unavailable':'KillBar could not be verified.','killbar-helper-untrusted':'KillBar could not be verified.','claude-guard-unavailable':'Claude authorization is not available in this installer.'};
+      const clientLabel=error?.setupClient==='codex'?'Codex':error?.setupClient==='claude'?'Claude Code':null;
+      if(clientLabel && error?.message==='client-configuration-conflict') messages[error.message]=`${clientLabel} already has a conflicting Slaunt configuration.`;
+      if(clientLabel && error?.message==='client-configuration-failed') messages[error.message]=`${clientLabel} configuration could not be updated.`;
+      if(error?.message==='cohort-failed') {
+        if(error.setupStage==='native-login' && clientLabel) {
+          const nativeMessages={launch:'could not be started',request:'did not provide a valid authorization request', 'waiting-approval':'exited while waiting for authorization', callback:'could not complete the authorization handoff', 'client-exit':'did not complete authorization after the callback'};
+          messages[error.message]=`${clientLabel} ${nativeMessages[error.nativeStage] || 'could not complete its Slaunt authorization'}.`;
+        }
+        else if(error.setupStage==='authorization') {
+          const details={'sign-in':'Slaunt sign-in could not be completed.','workspace':'Slaunt workspace identity could not be verified.','enrollment':'KillBar enrollment could not be completed.','client-grants':'Slaunt could not issue client authorization grants.'};
+          messages[error.message]=details[error.setupDetail] || 'Slaunt authorization or enrollment could not be completed.';
+        }
+        else if(error.setupStage==='timeout') messages[error.message]='Slaunt authorization timed out.';
+      }
+      terminal.fail(messages[error?.message]||'Setup could not be completed.',error?.setupMayHaveChanged?'Some settings may have changed; review them before retrying.':'No client settings were changed.');return 1;
+    }
+  } finally {controller.abort();terminal.stop?.();terminal.close?.();}
+}
+if(require.main===module) {
+  const terminal=createTerminal();
+  const onInterrupt=()=>{terminal.close();process.exit(130);};
+  const onTerminate=()=>{terminal.close();process.exit(143);};
+  process.once('SIGINT',onInterrupt);process.once('SIGTERM',onTerminate);
+  void main(process.argv.slice(2),{terminal}).then(code=>{process.exitCode=code;},()=>{terminal.close();console.error('Setup failed. Review client settings before retrying.');process.exitCode=1;}).finally(()=>{process.removeListener('SIGINT',onInterrupt);process.removeListener('SIGTERM',onTerminate);});
+}
+module.exports={main,checkClient,resolveClient};

package/package.json

@@ -1,70 +1,20 @@
 {
   "name": "slaunt",
-  "version": "0.1.17",
-  "description": "Privacy-first MCP agent access auditor for Claude and Codex",
-  "type": "module",
+  "version": "0.1.19",
   "bin": {
-    "slaunt": "dist/cli.js"
+    "slaunt": "bin/slaunt-hooks.js",
+    "slaunt-hooks": "bin/slaunt-hooks.js"
   },
-  "files": [
-    "dist",
-    "models/MODEL.json",
-    "models/NOTICE.md",
-    "models/APACHE-2.0.txt",
-    "README.md",
-    "LICENSE"
-  ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "check": "tsc --noEmit",
-    "test": "npm run build && vitest run",
-    "test:watch": "vitest",
-    "audit:demo": "npm run build && node dist/cli.js audit --demo",
-    "verify:model": "node scripts/verify-model.mjs",
-    "fetch:model": "node scripts/fetch-model.mjs",
-    "prepublishOnly": "npm run check && npm test && npm run verify:model"
+    "test": "node --test test/*.test.js",
+    "test:integration": "node test/native-integration.cjs"
   },
   "engines": {
-    "node": ">=20.17.0"
+    "node": ">=20"
   },
-  "keywords": [
-    "mcp",
-    "security",
-    "audit",
-    "claude",
-    "codex",
-    "agent"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/kerodem/slaunt-audit.git"
-  },
-  "bugs": {
-    "url": "https://github.com/kerodem/slaunt-audit/issues"
-  },
-  "homepage": "https://github.com/kerodem/slaunt-audit#readme",
-  "license": "MIT",
   "dependencies": {
-    "@inquirer/prompts": "8.5.2",
-    "@modelcontextprotocol/sdk": "1.30.0",
-    "chalk": "6.0.0",
-    "node-llama-cpp": "3.21.1",
-    "open": "11.0.0",
-    "ora": "9.4.1",
-    "slaunt-model-tinyllama-1b-part1": "0.1.0",
-    "slaunt-model-tinyllama-1b-part2": "0.1.0",
-    "smol-toml": "1.7.1",
-    "zod": "4.4.3"
-  },
-  "devDependencies": {
-    "@types/node": "24.10.1",
-    "typescript": "7.0.2",
-    "vitest": "4.1.10"
-  },
-  "overrides": {
-    "fast-uri": "3.1.6",
-    "hono": "4.13.5",
-    "@hono/node-server": "2.1.1",
-    "qs": "6.16.0"
+    "@electron/asar": "3.4.1",
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "smol-toml": "1.9.1"
   }
 }

package/release/manifest.json

@@ -0,0 +1,7 @@
+{
+  "format": 1,
+  "arch": "arm64",
+  "signing": "adhoc",
+  "sha256": "07890842d715bf1e322e13347b5b162774ccfb301b44595037fff97a2a2c147c",
+  "cdhash": "f2d067398109958d17e4c3b6bd6000eb02df0d99"
+}

package/scripts/killbar-portability-check.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+'use strict';
+// Cross-machine acceptance probe. Never starts a persistent agent or enrolls a device.
+const fs=require('node:fs');
+const os=require('node:os');
+const path=require('node:path');
+const {spawnSync}=require('node:child_process');
+
+function run(command,args,options={}) {
+  const result=spawnSync(command,args,{encoding:'utf8',timeout:30000,maxBuffer:1024*1024,...options});
+  if(result.error || result.status!==0) throw new Error('command failed');
+  return result.stdout.trim();
+}
+function parseArgs(args) {
+  if(args.length!==4 || args[0]!=='--app' || args[2]!=='--team' || !path.isAbsolute(args[1]) || !/^[A-Z0-9]{10}$/.test(args[3])) throw new Error('Usage: node scripts/killbar-portability-check.js --app /absolute/path/SlauntKillBar.app --team TRUSTED_TEAM_ID');
+  return {app:args[1],team:args[3]};
+}
+function test({app,team},{platform=process.platform,runCommand=run,tempRoot=os.tmpdir(),write=console.log}={}) {
+  const checks=[];
+  function check(name,fn){try{fn();checks.push({name,result:'PASS'});}catch{checks.push({name,result:'FAIL'});}}
+  function pending(name){checks.push({name,result:'NOT VERIFIED'});}
+  if(platform!=='darwin') {checks.push({name:'macOS platform',result:'FAIL'});return checks;}
+  let tmp;
+  try {
+    tmp=fs.mkdtempSync(path.join(tempRoot,'slaunt-other-mac-'));
+    const pkg=path.join(tmp,'package'),dest=path.join(tmp,'install'),extract=path.join(tmp,'extract');
+    fs.mkdirSync(pkg);fs.mkdirSync(dest);fs.mkdirSync(extract);
+    let packed=false,installed=false,unpacked=false,verified=false,bridge=false;
+    const archive=path.join(pkg,'killbar.zip');
+    const requirement=`=identifier "ai.slaunt.killbar" and anchor apple generic and certificate leaf[subject.OU] = "${team}"`;
+    check('Source signature matches trusted team',()=>runCommand('/usr/bin/codesign',['--verify','--deep','--strict','-R',requirement,app]));
+    if(checks.at(-1).result==='PASS') check('Create npm delivery fixture',()=>{
+      runCommand('/usr/bin/ditto',['-c','-k','--sequesterRsrc','--keepParent',app,archive]);
+      fs.writeFileSync(path.join(pkg,'package.json'),JSON.stringify({name:'slaunt-killbar-acceptance-fixture',version:'1.0.0',private:true,files:['killbar.zip']}));
+      runCommand('npm',['pack',pkg,'--pack-destination',tmp,'--offline','--ignore-scripts','--cache',path.join(tmp,'cache'),'--silent']);packed=true;
+    }); else pending('Create npm delivery fixture');
+    if(packed) check('Install npm fixture',()=>{
+      runCommand('npm',['install',path.join(tmp,'slaunt-killbar-acceptance-fixture-1.0.0.tgz'),'--prefix',dest,'--cache',path.join(tmp,'cache'),'--offline','--ignore-scripts','--no-audit','--no-fund','--silent']);installed=true;
+    }); else pending('Install npm fixture');
+    const copied=path.join(extract,'SlauntKillBar.app');
+    if(installed) check('Extract helper',()=>{runCommand('/usr/bin/ditto',['-x','-k',path.join(dest,'node_modules/slaunt-killbar-acceptance-fixture/killbar.zip'),extract]);unpacked=true;}); else pending('Extract helper');
+    if(unpacked) check('Extracted signature matches trusted team',()=>{runCommand('/usr/bin/codesign',['--verify','--deep','--strict','-R',requirement,copied]);verified=true;}); else pending('Extracted signature matches trusted team');
+    if(verified) check('Gatekeeper distribution assessment',()=>runCommand('/usr/sbin/spctl',['--assess','--type','execute',copied])); else pending('Gatekeeper distribution assessment');
+    const bin=path.join(copied,'Contents/MacOS/SlauntKillBar');
+    if(verified) check('Helper executes from npm fixture',()=>{const v=JSON.parse(runCommand(bin,['--desktop-bridge-version']));if(v.protocol_version!==1)throw new Error();bridge=true;}); else pending('Helper executes from npm fixture');
+    if(bridge) check('Local status protocol responds',()=>{const status=JSON.parse(runCommand(bin,['--desktop-control-status']));if(status.protocol_version!==1 || typeof status.enrolled!=='boolean' || status.requires_restart===true) throw new Error();}); else pending('Local status protocol responds');
+    pending('Clean-device enrollment and Keychain access');
+    // The installer and an observable service health protocol do not exist yet.
+    // A running process or a launchd entry alone cannot prove login restart or command processing.
+    pending('Clean macOS VM or independent machine');
+    pending('Actual published npm package');
+    pending('Background service starts and stays healthy');
+    pending('Service starts after logout/login or restart');
+    pending('Server command delivery and acknowledgement');
+  } catch {checks.push({name:'Test setup',result:'FAIL'});}
+  finally {if(tmp)fs.rmSync(tmp,{recursive:true,force:true});}
+  return checks;
+}
+function main(args=process.argv.slice(2)) {
+ let options;try{options=parseArgs(args);}catch(e){console.error(e.message);return 2;}
+ const checks=test(options);for(const c of checks) console.log(`${c.result.padEnd(12)} ${c.name}`);
+ const failed=checks.some(c=>c.result==='FAIL'),pending=checks.some(c=>c.result==='NOT VERIFIED');
+ console.log(failed?'Result: FAIL':pending?'Result: INCOMPLETE':'Result: PASS');
+ return failed?1:pending?2:0;
+}
+if(require.main===module)process.exitCode=main();
+module.exports={test,parseArgs,main};

package/scripts/package-killbar-macos.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# Stage an already signed and notarized KillBar app for the npm release.
+set -euo pipefail
+if [ "$#" -ne 3 ]; then
+  echo 'Usage: package-killbar-macos.sh <signed-app> <expected-team-id> <output-zip>' >&2
+  exit 2
+fi
+app=$1
+team=$2
+output=$3
+if [[ ! "$team" =~ ^[A-Z0-9]{10}$ ]] || [[ "$app" != /* ]] || [[ "$output" != /* ]]; then
+  echo 'Use absolute paths and the expected 10-character Apple team ID.' >&2
+  exit 2
+fi
+if [ ! -d "$app" ] || [ -e "$output" ]; then
+  echo 'The source app must exist and the output must not already exist.' >&2
+  exit 1
+fi
+requirement="=identifier \"ai.slaunt.killbar\" and anchor apple generic and certificate leaf[subject.OU] = \"$team\""
+/usr/bin/codesign --verify --deep --strict -R "$requirement" "$app"
+/usr/sbin/spctl --assess --type execute "$app"
+/usr/bin/xcrun stapler validate "$app"
+tmp=$(/usr/bin/mktemp -d "${TMPDIR:-/tmp}/slaunt-killbar-release.XXXXXXXX")
+trap 'rm -rf "$tmp"' EXIT
+/usr/bin/codesign -d --entitlements :- "$app" > "$tmp/entitlements.plist" 2>/dev/null
+expected="$team.ai.slaunt.killbar"
+actual=$(/usr/libexec/PlistBuddy -c 'Print :com.apple.application-identifier' "$tmp/entitlements.plist")
+group=$(/usr/libexec/PlistBuddy -c 'Print :keychain-access-groups:0' "$tmp/entitlements.plist")
+if [ "$actual" != "$expected" ] || [ "$group" != "$expected" ]; then
+  echo 'The signed application identifier or Keychain access group does not match.' >&2
+  exit 1
+fi
+/usr/bin/ditto "$app" "$tmp/SlauntKillBar.app"
+/usr/bin/codesign --verify --deep --strict -R "$requirement" "$tmp/SlauntKillBar.app"
+/usr/bin/ditto -c -k --sequesterRsrc --keepParent "$tmp/SlauntKillBar.app" "$tmp/SlauntKillBar.zip"
+# Exclusive creation prevents overwriting an existing release artifact.
+( set -o noclobber; cat "$tmp/SlauntKillBar.zip" > "$output" )
+echo 'Verified KillBar archive created.'

package/src/approval-manager.js

@@ -0,0 +1,53 @@
+'use strict';
+const crypto = require('node:crypto');
+const { validateRequest, validateCallback } = require('./hidden-oauth');
+const hash = value => crypto.createHash('sha256').update(value).digest();
+const secret = () => crypto.randomBytes(32).toString('base64url');
+const equal = (digest, value) => typeof value === 'string' && value.length <= 128 && crypto.timingSafeEqual(digest, hash(value));
+// Prototype only: in-memory state is intentionally not suitable for deployment.
+// validateClient must check the server's actual registered client and redirect.
+// issueCallback must create independent refreshable grants for each request.
+function createApprovalManager({ issuer, validateClient, issueCallback, now = Date.now, ttlMs = 120000, maxPending = 1000 }) {
+  if (typeof validateClient !== 'function' || typeof issueCallback !== 'function') throw new Error('approval-dependencies-required');
+  const entries = new Map();
+  function clearExpired() { for (const [id, entry] of entries) if (entry.expiresAt <= now()) entries.delete(id); }
+  async function create(requests) {
+    clearExpired();
+    if (!Array.isArray(requests) || requests.length < 1 || requests.length > 2 || entries.size >= maxPending) throw new Error('invalid-approval-request');
+    const clients = new Set();
+    const validated = [];
+    for (const item of requests) {
+      if (!['codex','claude'].includes(item?.client) || clients.has(item.client) || typeof item.authorizationUrl !== 'string' || item.authorizationUrl.length > 8192) throw new Error('invalid-approval-request');
+      clients.add(item.client);
+      const request = validateRequest(item.authorizationUrl, issuer);
+      if (!await validateClient({client:item.client, request:request.url})) throw new Error('unregistered-client');
+      validated.push({ client:item.client, request });
+    }
+    const id=secret(), approveSecret=secret(), redeemSecret=secret();
+    entries.set(id,{requests:validated, approveHash:hash(approveSecret), redeemHash:hash(redeemSecret), expiresAt:now()+ttlMs, state:'pending'});
+    return { id, approveSecret, redeemSecret, expiresAt:now()+ttlMs };
+  }
+  function approve({id, approveSecret, principal, accepted}) {
+    clearExpired();
+    const entry=entries.get(id);
+    if (!entry || entry.state !== 'pending' || !equal(entry.approveHash, approveSecret) || !principal || typeof principal !== 'string') throw new Error('invalid-approval');
+    if (accepted !== true) { entries.delete(id); return { approved:false }; }
+    entry.principal=principal; entry.state='approved'; entry.approveHash=null;
+    return { approved:true, clients:entry.requests.map(x=>x.client) };
+  }
+  async function redeem({id, redeemSecret}) {
+    clearExpired();
+    const entry=entries.get(id);
+    if (!entry || entry.state !== 'approved' || !equal(entry.redeemHash, redeemSecret)) throw new Error('invalid-redemption');
+    // Claim before awaiting external code; retries must start a new approval.
+    entry.state='consumed'; entries.delete(id);
+    const callbacks = {};
+    for (const item of entry.requests) {
+      const result = await issueCallback({ client:item.client, request:item.request.url, principal:entry.principal });
+      callbacks[item.client] = validateCallback(result, item.request);
+    }
+    return callbacks;
+  }
+  return {create,approve,redeem};
+}
+module.exports = {createApprovalManager};