@adrouter/agent 0.1.0-beta.10

package/LICENSE

@@ -0,0 +1,182 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the
+copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other
+entities that control, are controlled by, or are under common control with
+that entity. For the purposes of this definition, "control" means (i) the
+power, direct or indirect, to cause the direction or management of such
+entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+(50%) or more of the outstanding shares, or (iii) beneficial ownership of
+such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation source, and
+configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation
+or translation of a Source form, including but not limited to compiled object
+code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form,
+that is based on (or derived from) the Work and for which the editorial
+revisions, annotations, elaborations, or other modifications represent, as a
+whole, an original work of authorship. For the purposes of this License,
+Derivative Works shall not include works that remain separable from, or merely
+link (or bind by name) to the interfaces of, the Work and Derivative Works
+thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner. For the purposes
+of this definition, "submitted" means any form of electronic, verbal, or
+written communication sent to the Licensor or its representatives, including
+but not limited to communication on electronic mailing lists, source code
+control systems, and issue tracking systems that are managed by, or on behalf
+of, the Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise designated
+in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on
+behalf of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work, where such license applies only to those
+patent claims licensable by such Contributor that are necessarily infringed by
+their Contribution(s) alone or by combination of their Contribution(s) with
+the Work to which such Contribution(s) was submitted. If You institute patent
+litigation against any entity (including a cross-claim or counterclaim in a
+lawsuit) alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent
+licenses granted to You under this License for that Work shall terminate as of
+the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy
+of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any
+part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution,
+then any Derivative Works that You distribute must include a readable copy of
+the attribution notices contained within such NOTICE file, excluding those
+notices that do not pertain to any part of the Derivative Works, in at least
+one of the following places: within a NOTICE text file distributed as part of
+the Derivative Works; within the Source form or documentation, if provided
+along with the Derivative Works; or, within a display generated by the
+Derivative Works, if and wherever such third-party notices normally appear.
+The contents of the NOTICE file are for informational purposes only and do not
+modify the License. You may add Your own attribution notices within Derivative
+Works that You distribute, alongside or as an addendum to the NOTICE text from
+the Work, provided that such additional attribution notices cannot be
+construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction,
+or distribution of Your modifications, or for any such Derivative Works as a
+whole, provided Your use, reproduction, and distribution of the Work otherwise
+complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein
+shall supersede or modify the terms of any separate license agreement you may
+have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability to
+use the Work (including but not limited to damages for loss of goodwill, work
+stoppage, computer failure or malfunction, or any and all other commercial
+damages or losses), even if such Contributor has been advised of the
+possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work
+or Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree
+to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification
+within third-party archives.
+
+Copyright 2026 AdRouter Agent contributors
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at http://www.apache.org/licenses/LICENSE-2.0.
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,34 @@
+# `@adrouter/agent`
+
+This dependency-free package installs and launches the matching AdRouter Agent
+portable application from the canonical GitHub release. The desktop binaries
+are not duplicated in the npm tarball.
+
+```bash
+npm install --global @adrouter/agent@beta
+adrouter-agent doctor --json
+adrouter-agent
+```
+
+Supported targets are macOS 12+ arm64/x64, Ubuntu Desktop 24.04 LTS x64, and
+Windows 11 x64 with Node.js 22.19 or newer. The launcher accepts no alternate
+download URL or checksum. It validates the embedded schema-3 manifest, bounded
+download, SHA-256 digest, archive paths, executable, managed receipt, and
+staged-update rollback before activation.
+
+macOS is ad-hoc signed but not notarized. Linux and Windows portable beta
+artifacts are unsigned. Run `adrouter-agent doctor --json` for the platform
+install path, artifact key, verification result, sandbox readiness, and static
+setup guidance. The launcher never disables host security or auto-elevates.
+
+Commands:
+
+- `adrouter-agent` or `adrouter-agent launch`: install if needed, then launch.
+- `adrouter-agent install`: install and verify without launching.
+- `adrouter-agent doctor --json`: report installation, integrity, and sandbox
+  status without credentials.
+- `adrouter-agent --version`: print the package/release version without a
+  network request.
+
+See the repository's platform-setup guide for Ubuntu dependencies, Windows
+one-time sandbox provisioning, and staging bearer-token onboarding.

package/bin/adrouter-agent.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { runCli } from '../lib/cli.mjs';
+
+runCli(process.argv.slice(2)).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`adrouter-agent: ${message}\n`);
+  process.exitCode = 1;
+});

package/lib/cli.mjs

@@ -0,0 +1,50 @@
+import { inspectInstallation, install, launch } from './installer.mjs';
+import { readManifest, selectArtifact } from './manifest.mjs';
+
+const USAGE = `Usage: adrouter-agent [launch|install|doctor [--json]|--version]
+
+  launch       Install if needed, then launch (default)
+  install      Download, verify, and cache without launching
+  doctor       Report installation and security status
+  --version    Print the release version without downloading
+`;
+
+export async function runCli(args, io = process) {
+  const manifest = await readManifest();
+  if (args.includes('--version') || args.includes('-v')) {
+    io.stdout.write(`${manifest.releaseVersion}\n`);
+    return;
+  }
+  if (args.includes('--help') || args.includes('-h')) {
+    io.stdout.write(USAGE);
+    return;
+  }
+  const positional = args.filter((argument) => !argument.startsWith('-'));
+  const command = positional[0] ?? 'launch';
+  const unknownOptions = args.filter(
+    (argument) => argument.startsWith('-') && argument !== '--json'
+  );
+  if (unknownOptions.length > 0 || positional.length > 1) throw new Error(USAGE.trim());
+
+  if (command === 'doctor') {
+    const report = await inspectInstallation(manifest);
+    if (args.includes('--json')) io.stdout.write(`${JSON.stringify(report)}\n`);
+    else {
+      for (const [key, value] of Object.entries(report)) io.stdout.write(`${key}: ${value}\n`);
+    }
+    return;
+  }
+  if (args.includes('--json')) throw new Error('--json is supported only by doctor.');
+  if (command === 'install') {
+    const appPath = await install(manifest);
+    io.stdout.write(`Installed and verified ${appPath}\n`);
+    const report = await inspectInstallation(manifest);
+    if (report.warning) io.stderr.write(`Warning: ${report.warning}\n`);
+    return;
+  }
+  if (command !== 'launch') throw new Error(`Unknown command ${command}.\n${USAGE}`);
+  const appPath = await install(manifest);
+  const report = await inspectInstallation(manifest);
+  if (report.warning) io.stderr.write(`Warning: ${report.warning}\n`);
+  await launch(appPath, { artifact: selectArtifact(manifest) });
+}

package/lib/installer.mjs

@@ -0,0 +1,629 @@
+import { execFile, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  access,
+  constants as fsConstants,
+  lstat,
+  mkdir,
+  mkdtemp,
+  open,
+  readdir,
+  readFile,
+  readlink,
+  realpath,
+  rename,
+  rm,
+} from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join, posix, relative, sep } from 'node:path';
+import { promisify } from 'node:util';
+import { selectArtifact } from './manifest.mjs';
+
+const execFileAsync = promisify(execFile);
+const RECEIPT_OWNER = '@adrouter/agent';
+const MAX_DOWNLOAD_BYTES = 512 * 1024 * 1024;
+const MAX_REDIRECTS = 5;
+const WINDOWS_SANDBOX_SETUP = 'npx @anthropic-ai/sandbox-runtime@0.0.65 windows-install';
+const MAC_WARNING =
+  'This credential-free beta is not Developer ID signed or notarized. If macOS blocks it, open System Settings > Privacy & Security and choose Open Anyway.';
+const PORTABLE_WARNING =
+  'This portable beta is unsigned. Install only from the canonical release and retain checksum verification.';
+const ALLOWED_HOSTS = new Set([
+  'github.com',
+  'objects.githubusercontent.com',
+  'release-assets.githubusercontent.com',
+]);
+
+export function assertSupportedPlatform(platform = process.platform, arch = process.arch) {
+  selectArtifact(
+    {
+      artifacts: [{ key: 'darwin-universal' }, { key: 'linux-x64' }, { key: 'win32-x64' }],
+    },
+    platform,
+    arch
+  );
+}
+
+export function assertSupportedMacOsVersion(version) {
+  const major = Number.parseInt(String(version).split('.')[0] ?? '', 10);
+  if (!Number.isSafeInteger(major) || major < 12) {
+    throw new Error(`Unsupported macOS version ${version}; macOS 12 or newer is required.`);
+  }
+}
+
+export function assertNonRoot(uid = process.getuid?.()) {
+  if (uid === 0) {
+    throw new Error(
+      'Do not run adrouter-agent with sudo or as root; install it as the logged-in user.'
+    );
+  }
+}
+
+export function assertAllowedDownloadUrl(input) {
+  const url = input instanceof URL ? input : new URL(input);
+  if (url.protocol !== 'https:' || !ALLOWED_HOSTS.has(url.hostname)) {
+    throw new Error(`Refusing non-canonical download URL: ${url.origin}`);
+  }
+  if (url.username || url.password || url.port) {
+    throw new Error('Refusing a download URL containing credentials or a non-default port.');
+  }
+  return url;
+}
+
+export function assertSafeArchiveEntries(entries, archiveRoot = 'AdRouter Agent.app') {
+  if (!Array.isArray(entries) || entries.length === 0) {
+    throw new Error('The release ZIP is empty.');
+  }
+  for (const entry of entries) {
+    if (
+      typeof entry !== 'string' ||
+      entry.includes('\0') ||
+      entry.startsWith('/') ||
+      /^[A-Za-z]:/.test(entry) ||
+      entry.startsWith('\\') ||
+      entry.split(/[\\/]/).includes('..')
+    ) {
+      throw new Error(`Unsafe ZIP entry: ${JSON.stringify(entry)}`);
+    }
+    const normalized = entry.replaceAll('\\', '/').replace(/\/$/, '');
+    if (!normalized || normalized.split('/').some((segment) => segment === '' || segment === '.')) {
+      throw new Error(`Unsafe ZIP entry: ${JSON.stringify(entry)}`);
+    }
+    if (
+      archiveRoot !== '.' &&
+      normalized !== archiveRoot &&
+      !normalized.startsWith(`${archiveRoot}/`)
+    ) {
+      throw new Error(`Unexpected ZIP layout entry: ${entry}`);
+    }
+  }
+}
+
+export function assertSafeArchiveSymlink(entry, target, archiveRoot = 'AdRouter Agent.app') {
+  assertSafeArchiveEntries([entry], archiveRoot);
+  if (
+    typeof target !== 'string' ||
+    target.length === 0 ||
+    target.includes('\0') ||
+    target.startsWith('/') ||
+    target.startsWith('\\') ||
+    target.includes('\\')
+  ) {
+    throw new Error(`Unsafe ZIP symbolic link target: ${JSON.stringify(target)}`);
+  }
+  const root = archiveRoot === '.' ? '/_archive' : `/${archiveRoot}`;
+  const relativeEntry =
+    archiveRoot === '.'
+      ? entry.split(String.fromCodePoint(92)).join('/')
+      : entry
+          .split(String.fromCodePoint(92))
+          .join('/')
+          .slice(archiveRoot.length + 1);
+  const resolved = posix.resolve(root, posix.dirname(relativeEntry), target);
+  if (resolved !== root && !resolved.startsWith(`${root}/`)) {
+    throw new Error(`ZIP symbolic link escapes ${archiveRoot}: ${entry} -> ${target}`);
+  }
+}
+
+export function releasePaths(
+  _manifest,
+  homeDirectory = homedir(),
+  platform = process.platform,
+  options = {}
+) {
+  if (platform === 'darwin') {
+    const applicationsDirectory = join(homeDirectory, 'Applications');
+    const supportDirectory = join(
+      homeDirectory,
+      'Library',
+      'Application Support',
+      'adrouter-agent-launcher'
+    );
+    return {
+      applicationsDirectory,
+      supportDirectory,
+      appPath: join(applicationsDirectory, 'AdRouter Agent.app'),
+      receiptPath: join(supportDirectory, 'receipt.json'),
+    };
+  }
+  if (platform === 'linux') {
+    const dataDirectory =
+      options.xdgDataHome ?? process.env.XDG_DATA_HOME ?? join(homeDirectory, '.local', 'share');
+    const applicationsDirectory = join(dataDirectory, 'adrouter-agent');
+    const supportDirectory = join(dataDirectory, 'adrouter-agent-launcher');
+    return {
+      applicationsDirectory,
+      supportDirectory,
+      appPath: join(applicationsDirectory, 'app'),
+      receiptPath: join(supportDirectory, 'receipt.json'),
+    };
+  }
+  const localAppData =
+    options.localAppData ?? process.env.LOCALAPPDATA ?? join(homeDirectory, 'AppData', 'Local');
+  const applicationsDirectory = join(localAppData, 'Programs');
+  const supportDirectory = join(localAppData, 'adrouter-agent-launcher');
+  return {
+    applicationsDirectory,
+    supportDirectory,
+    appPath: join(applicationsDirectory, 'AdRouter Agent'),
+    receiptPath: join(supportDirectory, 'receipt.json'),
+  };
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function execute(file, args, options = {}) {
+  return execFileAsync(file, args, {
+    encoding: 'utf8',
+    maxBuffer: 16 * 1024 * 1024,
+    ...options,
+  });
+}
+
+async function plistValue(appPath, key, executeImpl) {
+  const plist = join(appPath, 'Contents', 'Info.plist');
+  const { stdout } = await executeImpl('/usr/libexec/PlistBuddy', ['-c', `Print :${key}`, plist]);
+  return stdout.trim();
+}
+
+async function verifyMacApp(appPath, manifest, executeImpl) {
+  await executeImpl('/usr/bin/codesign', ['--verify', '--deep', '--strict', appPath]);
+  const signatureResult = await executeImpl('/usr/bin/codesign', ['-dv', '--verbose=4', appPath]);
+  const signatureDetails = `${signatureResult.stdout ?? ''}${signatureResult.stderr ?? ''}`;
+  if (
+    !signatureDetails.includes('Signature=adhoc') ||
+    !signatureDetails.includes('TeamIdentifier=not set')
+  ) {
+    throw new Error('The application is not the expected credential-free ad-hoc build.');
+  }
+  if (
+    (await plistValue(appPath, 'CFBundleIdentifier', executeImpl)) !== manifest.bundleIdentifier
+  ) {
+    throw new Error('The installed app bundle identifier does not match the release manifest.');
+  }
+  if (
+    (await plistValue(appPath, 'CFBundleShortVersionString', executeImpl)) !==
+    manifest.bundleShortVersion
+  ) {
+    throw new Error('The installed app short bundle version does not match the release manifest.');
+  }
+  if ((await plistValue(appPath, 'CFBundleVersion', executeImpl)) !== manifest.bundleVersion) {
+    throw new Error('The installed app build version does not match the release manifest.');
+  }
+  const executable = join(appPath, 'Contents', 'MacOS', 'AdRouter Agent');
+  const { stdout: architectures } = await executeImpl('/usr/bin/lipo', ['-archs', executable]);
+  if (!architectures.includes('arm64') || !architectures.includes('x86_64')) {
+    throw new Error('The installed app is not a universal arm64+x86_64 build.');
+  }
+}
+
+async function verifyPortableApp(appPath, artifact) {
+  const executable = join(appPath, ...artifact.executablePath.split('/'));
+  const stat = await lstat(executable);
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new Error('The portable application executable is missing or unsafe.');
+  }
+  if (artifact.platform === 'linux') await access(executable, fsConstants.X_OK);
+}
+
+async function verifyApp(appPath, manifest, artifact, executeImpl = execute) {
+  if (artifact.verificationMode === 'macos-adhoc') {
+    await verifyMacApp(appPath, manifest, executeImpl);
+  } else {
+    await verifyPortableApp(appPath, artifact);
+  }
+}
+
+async function assessGatekeeper(appPath, executeImpl = execute) {
+  try {
+    await executeImpl('/usr/sbin/spctl', ['--assess', '--type', 'execute', appPath]);
+    return 'accepted';
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') return 'unavailable';
+    return 'rejected';
+  }
+}
+
+async function verifyExtractedTree(root, appPath, archiveRoot) {
+  const canonicalRoot = `${await realpath(root)}${sep}`;
+  async function visit(path) {
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink()) {
+      const entry = relative(root, path).split(sep).join('/');
+      assertSafeArchiveSymlink(entry, await readlink(path), archiveRoot);
+    }
+    const canonical = await realpath(path);
+    if (canonical !== canonicalRoot.slice(0, -1) && !canonical.startsWith(canonicalRoot)) {
+      throw new Error('Release archive escaped its extraction directory.');
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) return;
+    for (const entry of await readdir(path)) await visit(join(path, entry));
+  }
+  const topLevel = await readdir(root);
+  if (archiveRoot === '.' && topLevel.length === 0) {
+    throw new Error('Release archive is empty after extraction.');
+  }
+  if (archiveRoot !== '.' && (topLevel.length !== 1 || topLevel[0] !== archiveRoot)) {
+    throw new Error(`Release archive must contain exactly ${archiveRoot}.`);
+  }
+  await visit(appPath);
+}
+
+async function download(manifest, artifact, destination, fetchImpl = fetch) {
+  let current = assertAllowedDownloadUrl(artifact.assetUrl);
+  for (let redirect = 0; redirect <= MAX_REDIRECTS; redirect += 1) {
+    const response = await fetchImpl(current, {
+      redirect: 'manual',
+      headers: { 'user-agent': `@adrouter/agent/${manifest.releaseVersion}` },
+      signal: AbortSignal.timeout(5 * 60 * 1000),
+    });
+    if ([301, 302, 303, 307, 308].includes(response.status)) {
+      const location = response.headers.get('location');
+      if (!location) throw new Error('Download redirect did not include a Location header.');
+      current = assertAllowedDownloadUrl(new URL(location, current));
+      continue;
+    }
+    if (!response.ok || !response.body) {
+      throw new Error(`Release download failed with HTTP ${response.status}.`);
+    }
+    const contentLength = response.headers.get('content-length');
+    const declaredSize = contentLength === null ? null : Number(contentLength);
+    if (
+      declaredSize !== null &&
+      (!Number.isSafeInteger(declaredSize) || declaredSize < 0 || declaredSize > MAX_DOWNLOAD_BYTES)
+    ) {
+      throw new Error('Release download exceeds the maximum permitted size.');
+    }
+    const handle = await open(destination, 'wx', 0o600);
+    let received = 0;
+    const digest = createHash('sha256');
+    const reader = response.body.getReader();
+    try {
+      while (true) {
+        const { done, value: chunk } = await reader.read();
+        if (done) break;
+        received += chunk.byteLength;
+        if (received > MAX_DOWNLOAD_BYTES) {
+          throw new Error('Release download exceeds the maximum permitted size.');
+        }
+        digest.update(chunk);
+        await handle.write(chunk);
+      }
+    } finally {
+      reader.releaseLock();
+      await handle.close();
+    }
+    if (declaredSize !== null && received !== declaredSize) {
+      throw new Error('Release download ended before the declared content length.');
+    }
+    const actual = digest.digest('hex');
+    if (actual !== artifact.sha256) throw new Error('Release ZIP checksum verification failed.');
+    return { bytes: received, sha256: actual, finalUrl: current.href };
+  }
+  throw new Error('Release download exceeded the redirect limit.');
+}
+
+async function archiveEntries(zipPath, artifact, executeImpl = execute) {
+  if (artifact.platform === 'win32') {
+    const script =
+      '& { param([string]$zipPath) ' +
+      'Add-Type -AssemblyName System.IO.Compression.FileSystem; ' +
+      '$z=[IO.Compression.ZipFile]::OpenRead($zipPath); ' +
+      'try {$z.Entries.FullName} finally {$z.Dispose()} }';
+    const { stdout } = await executeImpl('powershell.exe', [
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      script,
+      zipPath,
+    ]);
+    const entries = stdout.split(/\r?\n/).filter(Boolean);
+    assertSafeArchiveEntries(entries, artifact.archiveRoot);
+    return entries;
+  }
+  const { stdout } = await executeImpl('/usr/bin/unzip', ['-Z1', zipPath]);
+  const entries = stdout.split('\n').filter(Boolean);
+  assertSafeArchiveEntries(entries, artifact.archiveRoot);
+  const { stdout: listing } = await executeImpl('/usr/bin/zipinfo', ['-l', zipPath]);
+  for (const line of listing.split('\n').filter((value) => /^l[rwx-]{9}\s/.test(value))) {
+    const match = line.match(/^l[rwx-]{9}\s+\S+\s+\S+\s+\d+\s+\S+\s+\d+\s+\S+\s+\S+\s+\S+\s+(.+)$/);
+    if (!match) throw new Error('Unable to validate a ZIP symbolic link entry.');
+    const entry = match[1];
+    const { stdout: target } = await executeImpl('/usr/bin/unzip', ['-p', zipPath, entry]);
+    assertSafeArchiveSymlink(entry, target, artifact.archiveRoot);
+  }
+  return entries;
+}
+
+async function extractArchive(archive, extracted, artifact, executeImpl) {
+  if (artifact.platform === 'darwin') {
+    await executeImpl('/usr/bin/ditto', ['-x', '-k', archive, extracted]);
+  } else if (artifact.platform === 'linux') {
+    await executeImpl('/usr/bin/unzip', ['-q', archive, '-d', extracted]);
+  } else {
+    const script =
+      '& { param([string]$archive, [string]$destination) ' +
+      'Expand-Archive -LiteralPath $archive -DestinationPath $destination -Force }';
+    await executeImpl('powershell.exe', [
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      script,
+      archive,
+      extracted,
+    ]);
+  }
+}
+
+async function readReceipt(receiptPath, appPath, platform) {
+  try {
+    const receipt = JSON.parse(await readFile(receiptPath, 'utf8'));
+    const current = receipt.schema === 3;
+    const legacyMac = platform === 'darwin' && receipt.schema === 2;
+    const owned =
+      (current || legacyMac) &&
+      receipt.owner === RECEIPT_OWNER &&
+      receipt.applicationPath === appPath;
+    return { receipt, owned, legacyMac };
+  } catch {
+    return { receipt: null, owned: false, legacyMac: false };
+  }
+}
+
+function receiptMatchesManifest(receipt, manifest, artifact) {
+  return (
+    receipt?.releaseVersion === manifest.releaseVersion &&
+    receipt?.sha256 === artifact.sha256 &&
+    receipt?.releaseTag === manifest.releaseTag &&
+    (receipt.schema === 2 || receipt.artifactKey === artifact.key)
+  );
+}
+
+async function appIsRunning(appPath, artifact, executeImpl = execute) {
+  const executable = join(appPath, ...artifact.executablePath.split('/'));
+  if (artifact.platform === 'win32') return false;
+  const { stdout } = await executeImpl('/bin/ps', ['-axo', 'command=']);
+  return stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .some((line) => line === executable || line.startsWith(`${executable} `));
+}
+
+function sandboxReport(platform, override) {
+  if (override) return override;
+  if (platform === 'win32') {
+    return {
+      status: 'setup-required',
+      detail: 'Run the one-time elevated Windows sandbox setup before command tools are enabled.',
+      setupCommands: [WINDOWS_SANDBOX_SETUP],
+    };
+  }
+  if (platform === 'linux') {
+    return {
+      status: 'setup-required',
+      detail: 'Verify Bubblewrap, socat, ripgrep, and the Ubuntu AppArmor userns profile.',
+      setupCommands: ['sudo apt-get install bubblewrap socat ripgrep'],
+    };
+  }
+  return {
+    status: 'ready',
+    detail: 'Seatbelt command sandboxing is built into macOS.',
+    setupCommands: [],
+  };
+}
+
+export async function inspectInstallation(manifest, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const architecture = options.arch ?? process.arch;
+  const artifact = selectArtifact(manifest, platform, architecture);
+  const paths = releasePaths(manifest, options.homeDirectory, platform, options);
+  const report = {
+    schema: 3,
+    distributionMode: manifest.distributionMode,
+    platform,
+    architecture,
+    artifactKey: artifact.key,
+    verificationMode: artifact.verificationMode,
+    operatingSystemVersion: null,
+    supported: false,
+    releaseVersion: manifest.releaseVersion,
+    releaseTag: manifest.releaseTag,
+    applicationPath: paths.appPath,
+    installed: false,
+    receiptMatches: false,
+    bundleIntegrity: false,
+    signatureType: 'missing',
+    gatekeeperAssessment: platform === 'darwin' ? 'unavailable' : 'not-applicable',
+    sandbox: sandboxReport(platform, options.sandbox),
+    authenticationInspection: 'application-only',
+    authenticationState: 'unknown',
+    storageClassification: 'unknown',
+    signedRequestSupport: false,
+    refreshHealth: 'unknown',
+    pendingEnrollment: 'unknown',
+    originClass: 'unknown',
+    reconnectNeed: 'unknown',
+    warning: platform === 'darwin' ? MAC_WARNING : PORTABLE_WARNING,
+  };
+  try {
+    assertSupportedPlatform(platform, architecture);
+    if (platform === 'darwin') {
+      const versionResult =
+        options.macOsVersion === undefined
+          ? await (options.executeImpl ?? execute)('/usr/bin/sw_vers', ['-productVersion'])
+          : { stdout: options.macOsVersion };
+      report.operatingSystemVersion = versionResult.stdout.trim();
+      assertSupportedMacOsVersion(report.operatingSystemVersion);
+    }
+    report.supported = true;
+  } catch (error) {
+    report.error = error instanceof Error ? error.message : String(error);
+    return report;
+  }
+  report.installed = await exists(paths.appPath);
+  if (!report.installed) return report;
+  const receiptStatus = await readReceipt(paths.receiptPath, paths.appPath, platform);
+  report.receiptMatches =
+    receiptStatus.owned && receiptMatchesManifest(receiptStatus.receipt, manifest, artifact);
+  try {
+    await verifyApp(paths.appPath, manifest, artifact, options.executeImpl);
+    report.bundleIntegrity = true;
+    report.signedRequestSupport = true;
+    report.signatureType = platform === 'darwin' ? 'adhoc' : 'unsigned-portable';
+  } catch (error) {
+    report.signatureType = 'invalid';
+    report.error = error instanceof Error ? error.message : String(error);
+  }
+  if (platform === 'darwin') {
+    report.gatekeeperAssessment = await assessGatekeeper(paths.appPath, options.executeImpl);
+    if (report.gatekeeperAssessment === 'accepted') report.warning = null;
+  }
+  return report;
+}
+
+export async function install(manifest, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const architecture = options.arch ?? process.arch;
+  const artifact = selectArtifact(manifest, platform, architecture);
+  assertNonRoot(options.uid ?? process.getuid?.());
+  const paths = releasePaths(manifest, options.homeDirectory, platform, options);
+  const executeImpl = options.executeImpl ?? execute;
+  const existing = await inspectInstallation(manifest, options);
+  if (!existing.supported)
+    throw new Error(existing.error ?? 'This operating system is not supported.');
+  const receiptStatus = await readReceipt(paths.receiptPath, paths.appPath, platform);
+  if (existing.installed && existing.receiptMatches && existing.bundleIntegrity) {
+    if (receiptStatus.legacyMac) {
+      await (options.writeReceiptImpl ?? writeReceipt)(paths.receiptPath, {
+        ...receiptStatus.receipt,
+        schema: 3,
+        distributionMode: manifest.distributionMode,
+        artifactKey: artifact.key,
+        migratedAt: new Date().toISOString(),
+      });
+    }
+    return paths.appPath;
+  }
+  if (existing.installed && !receiptStatus.owned) {
+    throw new Error(
+      `${paths.appPath} already exists and is not managed by @adrouter/agent; move or remove it before installing.`
+    );
+  }
+  if (existing.installed && (await appIsRunning(paths.appPath, artifact, executeImpl))) {
+    throw new Error('Quit AdRouter Agent before installing or updating it.');
+  }
+
+  await mkdir(paths.applicationsDirectory, { recursive: true, mode: 0o755 });
+  await mkdir(paths.supportDirectory, { recursive: true, mode: 0o700 });
+  const staging = await mkdtemp(join(paths.applicationsDirectory, '.adrouter-agent-staging-'));
+  const archive = join(staging, basename(artifact.assetName));
+  const extracted = join(staging, 'extracted');
+  const stagedApp =
+    artifact.archiveRoot === '.' ? extracted : join(extracted, artifact.archiveRoot);
+  const backupPath = join(
+    paths.applicationsDirectory,
+    `.adrouter-agent-backup-${process.pid}-${Date.now()}`
+  );
+  let backedUp = false;
+  let activated = false;
+  try {
+    const receipt = await download(manifest, artifact, archive, options.fetchImpl);
+    await archiveEntries(archive, artifact, executeImpl);
+    await mkdir(extracted, { mode: 0o700 });
+    await extractArchive(archive, extracted, artifact, executeImpl);
+    await verifyExtractedTree(extracted, stagedApp, artifact.archiveRoot);
+    await verifyApp(stagedApp, manifest, artifact, executeImpl);
+    if (existing.installed) {
+      await rename(paths.appPath, backupPath);
+      backedUp = true;
+    }
+    await rename(stagedApp, paths.appPath);
+    activated = true;
+    await (options.writeReceiptImpl ?? writeReceipt)(paths.receiptPath, {
+      schema: 3,
+      owner: RECEIPT_OWNER,
+      distributionMode: manifest.distributionMode,
+      artifactKey: artifact.key,
+      releaseVersion: manifest.releaseVersion,
+      releaseTag: manifest.releaseTag,
+      sha256: receipt.sha256,
+      bytes: receipt.bytes,
+      finalUrl: receipt.finalUrl,
+      applicationPath: paths.appPath,
+      installedAt: new Date().toISOString(),
+    });
+    if (backedUp) await rm(backupPath, { recursive: true, force: true });
+    return paths.appPath;
+  } catch (error) {
+    if (activated) await rm(paths.appPath, { recursive: true, force: true });
+    if (backedUp && (await exists(backupPath))) await rename(backupPath, paths.appPath);
+    throw error;
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+}
+
+async function writeReceipt(path, receipt) {
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+      await handle.writeFile(`${JSON.stringify(receipt, null, 2)}\n`, 'utf8');
+    } finally {
+      await handle.close();
+    }
+    await rename(temporary, path);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+export async function launch(appPath, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const artifact = options.artifact ?? {
+    executablePath:
+      platform === 'darwin'
+        ? 'Contents/MacOS/AdRouter Agent'
+        : platform === 'win32'
+          ? 'AdRouter Agent.exe'
+          : 'AdRouter Agent',
+  };
+  const spawnImpl = options.spawnImpl ?? spawn;
+  const executable =
+    platform === 'darwin' ? '/usr/bin/open' : join(appPath, ...artifact.executablePath.split('/'));
+  const args = platform === 'darwin' ? [appPath] : [];
+  await new Promise((resolvePromise, reject) => {
+    const child = spawnImpl(executable, args, { detached: true, stdio: 'ignore' });
+    child.once('error', reject);
+    child.once('spawn', resolvePromise);
+    child.unref();
+  });
+}

package/lib/manifest.mjs

@@ -0,0 +1,153 @@
+import { readFile } from 'node:fs/promises';
+
+const SHA256_PATTERN = /^[a-f0-9]{64}$/;
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-beta\.\d+)?$/;
+const ARTIFACTS = Object.freeze({
+  'darwin-universal': {
+    platform: 'darwin',
+    architectures: ['arm64', 'x64'],
+    archiveRoot: 'AdRouter Agent.app',
+    executablePath: 'Contents/MacOS/AdRouter Agent',
+    verificationMode: 'macos-adhoc',
+    suffix: 'darwin-universal',
+  },
+  'linux-x64': {
+    platform: 'linux',
+    architectures: ['x64'],
+    archiveRoot: 'AdRouter Agent-linux-x64',
+    executablePath: 'AdRouter Agent',
+    verificationMode: 'portable-checksum',
+    suffix: 'linux-x64',
+  },
+  'win32-x64': {
+    platform: 'win32',
+    architectures: ['x64'],
+    archiveRoot: '.',
+    executablePath: 'AdRouter Agent.exe',
+    verificationMode: 'portable-checksum',
+    suffix: 'win32-x64',
+  },
+});
+
+export function artifactKey(platform = process.platform, arch = process.arch) {
+  if (platform === 'darwin' && (arch === 'arm64' || arch === 'x64')) {
+    return 'darwin-universal';
+  }
+  if (platform === 'linux' && arch === 'x64') return 'linux-x64';
+  if (platform === 'win32' && arch === 'x64') return 'win32-x64';
+  throw new Error(`Unsupported operating system/architecture combination: ${platform}/${arch}.`);
+}
+
+export function selectArtifact(manifest, platform = process.platform, arch = process.arch) {
+  const key = artifactKey(platform, arch);
+  const artifact = manifest.artifacts.find((candidate) => candidate.key === key);
+  if (!artifact) throw new Error(`The release manifest does not contain ${key}.`);
+  return artifact;
+}
+
+export function validateManifest(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('The embedded release manifest is not an object.');
+  }
+  for (const key of [
+    'releaseVersion',
+    'releaseTag',
+    'repository',
+    'distributionMode',
+    'bundleIdentifier',
+    'bundleShortVersion',
+    'bundleVersion',
+  ]) {
+    if (typeof value[key] !== 'string' || value[key].length === 0) {
+      throw new Error(`The embedded release manifest has an invalid ${key}.`);
+    }
+  }
+  if (value.schema !== 3) throw new Error('Unsupported release manifest schema.');
+  if (value.distributionMode !== 'credential-free-portable') {
+    throw new Error('The embedded release distribution mode is not supported.');
+  }
+  if (!VERSION_PATTERN.test(value.releaseVersion)) {
+    throw new Error('The embedded release version is not a supported SemVer.');
+  }
+  if (value.releaseTag !== `v${value.releaseVersion}`) {
+    throw new Error('The embedded release tag does not match the version.');
+  }
+  if (value.repository !== 'adrouter/adrouterAgent') {
+    throw new Error('The embedded repository is not canonical.');
+  }
+  if (value.bundleIdentifier !== 'com.adrouter.agent') {
+    throw new Error('The embedded bundle identifier is not canonical.');
+  }
+  if (!/^\d+\.\d+\.\d+$/.test(value.bundleShortVersion)) {
+    throw new Error('The embedded short bundle version is invalid.');
+  }
+  if (!/^\d+(?:\.\d+){0,2}$/.test(value.bundleVersion)) {
+    throw new Error('The embedded numeric bundle version is invalid.');
+  }
+  if (
+    value.authentication?.fixture !== 'tests/fixtures/platform-auth-v1.json' ||
+    value.authentication?.fixtureSha256 !==
+      '93a8ec8d4eba38f9165179aa0cdfe3316f8134a882bd0426bd83339af55d17f8' ||
+    value.authentication?.acceptanceAsset !== 'authentication-acceptance.json'
+  ) {
+    throw new Error('The embedded platform authentication metadata is not canonical.');
+  }
+  if (!Array.isArray(value.artifacts) || value.artifacts.length !== 3) {
+    throw new Error('The embedded release manifest must contain exactly three artifacts.');
+  }
+  const seen = new Set();
+  for (const artifact of value.artifacts) {
+    const expected = ARTIFACTS[artifact?.key];
+    if (!expected || seen.has(artifact.key)) {
+      throw new Error(
+        `The embedded release manifest has an invalid artifact key: ${artifact?.key}.`
+      );
+    }
+    seen.add(artifact.key);
+    for (const field of [
+      'platform',
+      'assetName',
+      'assetUrl',
+      'sha256',
+      'archiveRoot',
+      'executablePath',
+      'verificationMode',
+    ]) {
+      if (typeof artifact[field] !== 'string' || artifact[field].length === 0) {
+        throw new Error(`Artifact ${artifact.key} has an invalid ${field}.`);
+      }
+    }
+    if (
+      artifact.platform !== expected.platform ||
+      JSON.stringify(artifact.architectures) !== JSON.stringify(expected.architectures) ||
+      artifact.archiveRoot !== expected.archiveRoot ||
+      artifact.executablePath !== expected.executablePath ||
+      artifact.verificationMode !== expected.verificationMode
+    ) {
+      throw new Error(`Artifact ${artifact.key} does not match its canonical target metadata.`);
+    }
+    const expectedName = `AdRouter-Agent-${value.releaseVersion}-${expected.suffix}.zip`;
+    if (artifact.assetName !== expectedName) {
+      throw new Error(`Artifact ${artifact.key} has a non-canonical asset name.`);
+    }
+    const expectedUrl =
+      `https://github.com/${value.repository}/releases/download/` +
+      `${value.releaseTag}/${expectedName}`;
+    if (artifact.assetUrl !== expectedUrl) {
+      throw new Error(`Artifact ${artifact.key} has a non-canonical asset URL.`);
+    }
+    if (!SHA256_PATTERN.test(artifact.sha256)) {
+      throw new Error(`Artifact ${artifact.key} checksum is not a SHA-256 digest.`);
+    }
+  }
+  return Object.freeze({
+    ...value,
+    authentication: Object.freeze({ ...value.authentication }),
+    artifacts: Object.freeze(value.artifacts.map((artifact) => Object.freeze({ ...artifact }))),
+  });
+}
+
+export async function readManifest(url = new URL('../release-manifest.json', import.meta.url)) {
+  const text = await readFile(url, 'utf8');
+  return validateManifest(JSON.parse(text));
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@adrouter/agent",
+  "version": "0.1.0-beta.10",
+  "description": "Verified installer and launcher for the AdRouter Agent desktop application.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "adrouter-agent": "bin/adrouter-agent.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "LICENSE",
+    "README.md",
+    "release-manifest.json"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "arm64",
+    "x64"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adrouter/adrouterAgent.git",
+    "directory": "packages/agent-launcher"
+  },
+  "bugs": {
+    "url": "https://github.com/adrouter/adrouterAgent/issues"
+  },
+  "homepage": "https://github.com/adrouter/adrouterAgent#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/release-manifest.json

@@ -0,0 +1,57 @@
+{
+  "schema": 3,
+  "distributionMode": "credential-free-portable",
+  "releaseVersion": "0.1.0-beta.10",
+  "releaseTag": "v0.1.0-beta.10",
+  "repository": "adrouter/adrouterAgent",
+  "bundleIdentifier": "com.adrouter.agent",
+  "bundleShortVersion": "0.1.0",
+  "bundleVersion": "10010",
+  "authentication": {
+    "fixture": "tests/fixtures/platform-auth-v1.json",
+    "fixtureSha256": "93a8ec8d4eba38f9165179aa0cdfe3316f8134a882bd0426bd83339af55d17f8",
+    "acceptanceAsset": "authentication-acceptance.json"
+  },
+  "artifacts": [
+    {
+      "key": "darwin-universal",
+      "platform": "darwin",
+      "architectures": [
+        "arm64",
+        "x64"
+      ],
+      "archiveRoot": "AdRouter Agent.app",
+      "executablePath": "Contents/MacOS/AdRouter Agent",
+      "verificationMode": "macos-adhoc",
+      "assetName": "AdRouter-Agent-0.1.0-beta.10-darwin-universal.zip",
+      "assetUrl": "https://github.com/adrouter/adrouterAgent/releases/download/v0.1.0-beta.10/AdRouter-Agent-0.1.0-beta.10-darwin-universal.zip",
+      "sha256": "8509e4817b21a83efa6d26f312cdfb2e14788e7897f43931f118bb8d5228e33b"
+    },
+    {
+      "key": "linux-x64",
+      "platform": "linux",
+      "architectures": [
+        "x64"
+      ],
+      "archiveRoot": "AdRouter Agent-linux-x64",
+      "executablePath": "AdRouter Agent",
+      "verificationMode": "portable-checksum",
+      "assetName": "AdRouter-Agent-0.1.0-beta.10-linux-x64.zip",
+      "assetUrl": "https://github.com/adrouter/adrouterAgent/releases/download/v0.1.0-beta.10/AdRouter-Agent-0.1.0-beta.10-linux-x64.zip",
+      "sha256": "5ac61e2fd757f584762291c7fe65bf0c9edda4e650dd5e7c972a7dc7cadbd332"
+    },
+    {
+      "key": "win32-x64",
+      "platform": "win32",
+      "architectures": [
+        "x64"
+      ],
+      "archiveRoot": ".",
+      "executablePath": "AdRouter Agent.exe",
+      "verificationMode": "portable-checksum",
+      "assetName": "AdRouter-Agent-0.1.0-beta.10-win32-x64.zip",
+      "assetUrl": "https://github.com/adrouter/adrouterAgent/releases/download/v0.1.0-beta.10/AdRouter-Agent-0.1.0-beta.10-win32-x64.zip",
+      "sha256": "7fd83263aa2272b4585acd7a69b95f1e9f09f8e7bbde13b76f7dabc89916aa27"
+    }
+  ]
+}