@adrouter/agent 0.1.0-beta.2

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,35 @@
+# `@adrouter/agent`
+
+This dependency-free package installs and launches the credential-free,
+ad-hoc-signed universal macOS application from the matching
+[AdRouter Agent GitHub release](https://github.com/adrouter/adrouterAgent/releases).
+The desktop application is not duplicated in the npm tarball.
+
+```bash
+npm install --global @adrouter/agent@beta
+adrouter-agent doctor --json
+adrouter-agent
+```
+
+The launcher supports macOS 12 or newer, Apple Silicon and Intel, and Node.js
+22.19.0 or newer. It accepts no alternate download URL or checksum. Downloads
+are bounded, checked against the release manifest embedded in this package,
+and installed as the real application at `~/Applications/AdRouter Agent.app`
+after archive, bundle identity, universal architecture, and ad-hoc `codesign`
+integrity checks.
+
+This beta is not Developer ID signed or notarized. If macOS blocks the first
+launch, open **System Settings → Privacy & Security** and choose **Open Anyway**.
+The launcher never removes quarantine metadata or changes Gatekeeper settings.
+
+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 platform, installation receipt,
+  bundle integrity, ad-hoc signature, and diagnostic Gatekeeper status.
+- `adrouter-agent --version`: print the package/release version without a
+  network request.
+
+See the [repository security policy](https://github.com/adrouter/adrouterAgent/blob/main/SECURITY.md)
+before reporting a vulnerability.

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 } 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);
+}

package/lib/installer.mjs

@@ -0,0 +1,437 @@
+import { execFile, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  access,
+  lstat,
+  mkdir,
+  mkdtemp,
+  open,
+  readdir,
+  readFile,
+  realpath,
+  rename,
+  rm,
+} from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join, sep } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const APP_NAME = 'AdRouter Agent.app';
+const EXECUTABLE_NAME = 'AdRouter Agent';
+const RECEIPT_OWNER = '@adrouter/agent';
+const MAX_DOWNLOAD_BYTES = 512 * 1024 * 1024;
+const MAX_REDIRECTS = 5;
+const GATEKEEPER_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 ALLOWED_HOSTS = new Set([
+  'github.com',
+  'objects.githubusercontent.com',
+  'release-assets.githubusercontent.com',
+]);
+
+export function assertSupportedPlatform(platform = process.platform, arch = process.arch) {
+  if (platform !== 'darwin') {
+    throw new Error(`Unsupported platform ${platform}; AdRouter Agent requires macOS 12 or newer.`);
+  }
+  if (arch !== 'arm64' && arch !== 'x64') {
+    throw new Error(`Unsupported macOS architecture ${arch}; expected arm64 or x64.`);
+  }
+}
+
+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; install it as the logged-in macOS 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) {
+  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('/') ||
+      entry.startsWith('\\') ||
+      entry.split(/[\\/]/).includes('..')
+    ) {
+      throw new Error(`Unsafe ZIP entry: ${JSON.stringify(entry)}`);
+    }
+    if (entry !== APP_NAME && !entry.startsWith(`${APP_NAME}/`)) {
+      throw new Error(`Unexpected ZIP layout entry: ${entry}`);
+    }
+  }
+}
+
+export function releasePaths(_manifest, homeDirectory = homedir()) {
+  const applicationsDirectory = join(homeDirectory, 'Applications');
+  const supportDirectory = join(
+    homeDirectory,
+    'Library',
+    'Application Support',
+    'adrouter-agent-launcher'
+  );
+  return {
+    applicationsDirectory,
+    supportDirectory,
+    appPath: join(applicationsDirectory, APP_NAME),
+    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 verifyApp(appPath, manifest, executeImpl = execute) {
+  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.');
+  }
+
+  const bundleIdentifier = await plistValue(appPath, 'CFBundleIdentifier', executeImpl);
+  const shortVersion = await plistValue(appPath, 'CFBundleShortVersionString', executeImpl);
+  const buildVersion = await plistValue(appPath, 'CFBundleVersion', executeImpl);
+  if (bundleIdentifier !== manifest.bundleIdentifier) {
+    throw new Error('The installed app bundle identifier does not match the release manifest.');
+  }
+  if (shortVersion !== manifest.bundleShortVersion) {
+    throw new Error('The installed app short bundle version does not match the release manifest.');
+  }
+  if (buildVersion !== manifest.bundleVersion) {
+    throw new Error('The installed app build version does not match the release manifest.');
+  }
+
+  const executable = join(appPath, 'Contents', 'MacOS', EXECUTABLE_NAME);
+  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 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) {
+  const canonicalRoot = `${await realpath(root)}${sep}`;
+  async function visit(path) {
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink()) throw new Error(`Release archive contains a symbolic link: ${path}`);
+    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()) return;
+    for (const entry of await readdir(path)) await visit(join(path, entry));
+  }
+  const topLevel = await readdir(root);
+  if (topLevel.length !== 1 || topLevel[0] !== APP_NAME) {
+    throw new Error('Release archive must contain exactly AdRouter Agent.app.');
+  }
+  await visit(appPath);
+}
+
+async function download(manifest, destination, fetchImpl = fetch) {
+  let current = assertAllowedDownloadUrl(manifest.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 !== manifest.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, executeImpl = execute) {
+  const { stdout } = await executeImpl('/usr/bin/unzip', ['-Z1', zipPath]);
+  const entries = stdout.split('\n').filter(Boolean);
+  assertSafeArchiveEntries(entries);
+  const { stdout: listing } = await executeImpl('/usr/bin/zipinfo', ['-l', zipPath]);
+  if (listing.split('\n').some((line) => /^l[rwx-]{9}\s/.test(line))) {
+    throw new Error('Release ZIP contains symbolic links.');
+  }
+  return entries;
+}
+
+async function readReceipt(receiptPath, appPath) {
+  try {
+    const receipt = JSON.parse(await readFile(receiptPath, 'utf8'));
+    const owned =
+      receipt.schema === 2 &&
+      receipt.owner === RECEIPT_OWNER &&
+      receipt.applicationPath === appPath;
+    return { receipt, owned };
+  } catch {
+    return { receipt: null, owned: false };
+  }
+}
+
+function receiptMatchesManifest(receipt, manifest) {
+  return (
+    receipt?.releaseVersion === manifest.releaseVersion &&
+    receipt?.sha256 === manifest.sha256 &&
+    receipt?.releaseTag === manifest.releaseTag
+  );
+}
+
+async function appIsRunning(appPath, executeImpl = execute) {
+  const executable = join(appPath, 'Contents', 'MacOS', EXECUTABLE_NAME);
+  const { stdout } = await executeImpl('/bin/ps', ['-axo', 'command=']);
+  return stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .some((line) => line === executable || line.startsWith(`${executable} `));
+}
+
+export async function inspectInstallation(manifest, options = {}) {
+  const paths = releasePaths(manifest, options.homeDirectory);
+  const report = {
+    schema: 2,
+    distributionMode: manifest.distributionMode,
+    platform: options.platform ?? process.platform,
+    architecture: options.arch ?? process.arch,
+    macOsVersion: null,
+    supported: false,
+    releaseVersion: manifest.releaseVersion,
+    releaseTag: manifest.releaseTag,
+    applicationPath: paths.appPath,
+    installed: false,
+    receiptMatches: false,
+    bundleIntegrity: false,
+    signatureType: 'missing',
+    gatekeeperAssessment: 'unavailable',
+    warning: GATEKEEPER_WARNING,
+  };
+  try {
+    assertSupportedPlatform(report.platform, report.architecture);
+    const versionResult =
+      options.macOsVersion === undefined
+        ? await (options.executeImpl ?? execute)('/usr/bin/sw_vers', ['-productVersion'])
+        : { stdout: options.macOsVersion };
+    report.macOsVersion = versionResult.stdout.trim();
+    assertSupportedMacOsVersion(report.macOsVersion);
+    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);
+  report.receiptMatches =
+    receiptStatus.owned && receiptMatchesManifest(receiptStatus.receipt, manifest);
+  try {
+    await verifyApp(paths.appPath, manifest, options.executeImpl);
+    report.bundleIntegrity = true;
+    report.signatureType = 'adhoc';
+  } catch (error) {
+    report.signatureType = 'invalid';
+    report.error = error instanceof Error ? error.message : String(error);
+  }
+  report.gatekeeperAssessment = await assessGatekeeper(paths.appPath, options.executeImpl);
+  if (report.gatekeeperAssessment === 'accepted') report.warning = null;
+  return report;
+}
+
+export async function install(manifest, options = {}) {
+  assertSupportedPlatform(options.platform ?? process.platform, options.arch ?? process.arch);
+  assertNonRoot(options.uid ?? process.getuid?.());
+  const paths = releasePaths(manifest, options.homeDirectory);
+  const executeImpl = options.executeImpl ?? execute;
+  const existing = await inspectInstallation(manifest, options);
+  if (!existing.supported) {
+    throw new Error(existing.error ?? 'This Mac is not supported.');
+  }
+  if (
+    existing.installed &&
+    existing.receiptMatches &&
+    existing.bundleIntegrity &&
+    existing.signatureType === 'adhoc'
+  ) {
+    return paths.appPath;
+  }
+
+  const receiptStatus = await readReceipt(paths.receiptPath, 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, 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(manifest.assetName));
+  const extracted = join(staging, 'extracted');
+  const stagedApp = join(extracted, APP_NAME);
+  const backupPath = join(
+    paths.applicationsDirectory,
+    `.AdRouter Agent.app.backup-${process.pid}-${Date.now()}`
+  );
+  let backedUp = false;
+  let activated = false;
+  try {
+    const receipt = await download(manifest, archive, options.fetchImpl);
+    await archiveEntries(archive, executeImpl);
+    await mkdir(extracted, { mode: 0o700 });
+    await executeImpl('/usr/bin/ditto', ['-x', '-k', archive, extracted]);
+    await verifyExtractedTree(extracted, stagedApp);
+    await verifyApp(stagedApp, manifest, 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: 2,
+      owner: RECEIPT_OWNER,
+      distributionMode: manifest.distributionMode,
+      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, spawnImpl = spawn) {
+  await new Promise((resolvePromise, reject) => {
+    const child = spawnImpl('/usr/bin/open', [appPath], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.once('error', reject);
+    child.once('exit', (code) => {
+      if (code === 0) resolvePromise();
+      else reject(new Error(`macOS open failed with exit code ${code}.`));
+    });
+    child.unref();
+  });
+}

package/lib/manifest.mjs

@@ -0,0 +1,67 @@
+import { readFile } from 'node:fs/promises';
+
+const SHA256_PATTERN = /^[a-f0-9]{64}$/;
+const VERSION_PATTERN = /^\d+\.\d+\.\d+-beta\.\d+$/;
+
+export function validateManifest(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('The embedded release manifest is not an object.');
+  }
+  const requiredStrings = [
+    'releaseVersion',
+    'releaseTag',
+    'assetName',
+    'assetUrl',
+    'sha256',
+    'repository',
+    'distributionMode',
+    'bundleIdentifier',
+    'bundleShortVersion',
+    'bundleVersion',
+  ];
+  for (const key of requiredStrings) {
+    if (typeof value[key] !== 'string' || value[key].length === 0) {
+      throw new Error(`The embedded release manifest has an invalid ${key}.`);
+    }
+  }
+  if (value.schema !== 2) throw new Error('Unsupported release manifest schema.');
+  if (value.distributionMode !== 'credential-free-adhoc') {
+    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 beta 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 (value.assetName !== `AdRouter-Agent-${value.releaseVersion}-universal.zip`) {
+    throw new Error('The embedded release asset name is not canonical.');
+  }
+  const expectedUrl =
+    `https://github.com/${value.repository}/releases/download/` +
+    `${value.releaseTag}/${value.assetName}`;
+  if (value.assetUrl !== expectedUrl) {
+    throw new Error('The embedded release asset URL is not canonical.');
+  }
+  if (!SHA256_PATTERN.test(value.sha256)) {
+    throw new Error('The embedded release checksum is not a SHA-256 digest.');
+  }
+  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.');
+  }
+  return Object.freeze({ ...value });
+}
+
+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,40 @@
+{
+  "name": "@adrouter/agent",
+  "version": "0.1.0-beta.2",
+  "description": "Verified installer and launcher for the AdRouter Agent macOS 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"
+  ],
+  "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,13 @@
+{
+  "schema": 2,
+  "distributionMode": "credential-free-adhoc",
+  "releaseVersion": "0.1.0-beta.2",
+  "releaseTag": "v0.1.0-beta.2",
+  "assetName": "AdRouter-Agent-0.1.0-beta.2-universal.zip",
+  "assetUrl": "https://github.com/adrouter/adrouterAgent/releases/download/v0.1.0-beta.2/AdRouter-Agent-0.1.0-beta.2-universal.zip",
+  "sha256": "51bc43a700e06ced94ad6e64d281ee7f6f20ae092a3a8b2e6effa39bea52df8a",
+  "repository": "adrouter/adrouterAgent",
+  "bundleIdentifier": "com.adrouter.agent",
+  "bundleShortVersion": "0.1.0",
+  "bundleVersion": "10002"
+}