@mithran-hq/aegis 0.0.0-stage → 0.9.5

package/LICENSE

@@ -0,0 +1,18 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+Copyright 2026 Mithran
+
+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
+
+https://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

@@ -1,3 +1,136 @@
-# Temporary Holding Version
+# Aegis
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Aegis is the Mithran CLI for account authentication, agent gateway
+configuration, and Forge deploys. This package is the npm launcher; it runs the
+native `aegis` binary from the matching `@mithran-hq/aegis-darwin-arm64` package.
+
+## Requirements
+
+- macOS 15 or later
+- Apple silicon (arm64)
+- Node.js and npm
+
+The launcher refuses unsupported platforms and macOS versions before it starts
+the native binary.
+
+## Install
+
+Prerelease builds are published under the npm dist-tag `next`:
+
+```bash
+npm install -g @mithran-hq/aegis@next
+```
+
+The release flow writes the `next` tag and preserves an existing `latest` tag;
+it does not promote `latest`. Install a pinned version when you need a fixed
+build:
+
+```bash
+npm install -g @mithran-hq/aegis@0.9.5
+```
+
+Check the installed version:
+
+```bash
+aegis version
+```
+
+## Sign in
+
+```bash
+aegis auth login
+aegis auth status
+```
+
+`aegis auth login` opens the browser for sign-in and always prints the sign-in
+URL. Pass `--no-browser` to skip the browser launch and open that URL yourself.
+Sign out with `aegis auth logout`.
+
+## Gateway
+
+Enable, inspect, or disable the gateway for one supported agent:
+
+```bash
+aegis gateway enable --agent claude
+aegis gateway status --agent claude
+aegis gateway disable --agent claude
+```
+
+Supported agents are `claude` and `codex`. Gateway commands require a bound
+account; run `aegis auth login` first.
+
+## Forge
+
+Initialize a Forge app in the current directory, then commit and push it before
+deploying the committed source:
+
+```bash
+mkdir my-app
+cd my-app
+aegis forge init
+git init
+git add mithran.yaml index.html
+git commit -m "Initialize app"
+git remote add origin git@github.com:<owner>/<repo>.git
+git push -u origin HEAD
+aegis forge deploy
+```
+
+`aegis forge init` writes `mithran.yaml` and `index.html`. `aegis forge deploy`
+resolves the committed source from the Git origin and `HEAD`; pass
+`--repo <owner>/<repo>` when the origin is not a GitHub repository, and pass
+`--ref` or `--sha` to select another committed source. Deploy requires a bound
+account.
+
+## Managed Forge skill
+
+A normal global user install also installs the `aegis-forge` instruction skill
+for Claude and Codex:
+
+- `~/.claude/skills/aegis-forge/SKILL.md`
+- `~/.agents/skills/aegis-forge/SKILL.md`
+
+Automatic installation runs only for a normal global user installation. It
+skips when npm runs as root or through sudo, under CI, from a local or
+dependency install, or through npx. A skip is reported and changes no files;
+run `aegis skills install` to install explicitly.
+
+If npm installs with scripts disabled, install the skill afterwards:
+
+```bash
+aegis skills install
+```
+
+Check the installed state with `aegis skills status`. Existing files Aegis does
+not own, changed Aegis-owned files and unexpected entries are preserved and
+reported; unsafe paths are not followed. Automatic installation uses the
+standard OS-account homes. A custom agent home is selected only by an explicit
+`aegis skills install --agent-home <path>`.
+
+npm has no uninstall hook, so remove the skill before removing the CLI:
+
+```bash
+aegis skills remove
+npm uninstall -g @mithran-hq/aegis
+```
+
+The skill explains `forge init` and deploying committed source. Installing it
+grants no deployment authority: authentication, operator decisions and
+point-of-use authorization still apply.
+
+## Documentation
+
+User and developer documentation: https://mithran.ai/docs
+
+## Uninstall
+
+```bash
+npm uninstall -g @mithran-hq/aegis
+```
+
+## Support and security
+
+Questions and bug reports: https://github.com/mithran-hq/aegis/issues
+
+Security policy: https://github.com/mithran-hq/aegis/blob/main/SECURITY.md
+Do not include live credentials in a report.

package/aegis.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { readFileSync, statSync, writeSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { release as osRelease } from "node:os";
+
+const MANIFEST_SCHEMA = "aegis.npm.platform.v1";
+const CAPABILITY = "aegis:product:reduced-default";
+const PAYLOAD_PATH = "payload/aegis";
+const MANIFEST_NAME = "aegis.manifest.json";
+const MINIMUM_MACOS_MAJOR = 15;
+const MH_MAGIC_64 = 0xfeedfacf;
+const CPU_TYPE_ARM64 = 0x0100000c;
+const FORWARDED_SIGNALS = ["SIGHUP", "SIGINT", "SIGTERM", "SIGQUIT"];
+const SIGNAL_NUMBERS = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGTERM: 15 };
+
+function refuse(message) {
+  const text = Buffer.from(`aegis: ${message}\n`, "utf8");
+  try {
+    writeSync(2, text);
+  } catch {
+    process.stderr.write(text.toString("utf8"));
+  }
+  process.exit(1);
+}
+
+function readJson(path, label) {
+  let bytes;
+  try {
+    bytes = readFileSync(path);
+  } catch {
+    refuse(`${label} is missing at ${path}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    refuse(`${label} is malformed at ${path}`);
+  }
+  if (!isPlainObject(parsed)) {
+    refuse(`${label} is malformed at ${path}: expected a JSON object`);
+  }
+  return parsed;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function macOSMajorVersion() {
+  const system = typeof process.getSystemVersion === "function" ? process.getSystemVersion() : "";
+  const fromSystem = Number.parseInt(system, 10);
+  if (Number.isInteger(fromSystem)) {
+    return fromSystem;
+  }
+  const kernelMajor = Number.parseInt(String(osRelease()).split(".")[0], 10);
+  if (Number.isInteger(kernelMajor)) {
+    return kernelMajor - 9;
+  }
+  return null;
+}
+
+if (process.platform !== "darwin" || process.arch !== "arm64") {
+  refuse(
+    `unsupported host: this launcher runs only on macOS ${MINIMUM_MACOS_MAJOR}+ arm64, ` +
+      `found ${process.platform} ${process.arch}. No native payload was started.`,
+  );
+}
+const macOSMajor = macOSMajorVersion();
+if (macOSMajor === null) {
+  refuse(
+    `unable to determine the macOS version; macOS ${MINIMUM_MACOS_MAJOR}+ arm64 is required. ` +
+      "No native payload was started.",
+  );
+}
+if (macOSMajor < MINIMUM_MACOS_MAJOR) {
+  refuse(
+    `macOS ${MINIMUM_MACOS_MAJOR} or newer is required; found macOS ${macOSMajor}. ` +
+      "Upgrade macOS to run aegis.",
+  );
+}
+
+const launcherDir = dirname(fileURLToPath(import.meta.url));
+const launcher = readJson(join(launcherDir, "package.json"), "launcher package metadata");
+if (typeof launcher.name !== "string" || typeof launcher.version !== "string") {
+  refuse("launcher package metadata is malformed: name and version are required");
+}
+const launcherName = launcher.name;
+const launcherVersion = launcher.version;
+const suffix = "/aegis";
+const scope = launcherName.endsWith(suffix) ? launcherName.slice(0, -suffix.length) : "";
+if (!/^@[a-z0-9._-]+$/.test(scope)) {
+  refuse(`launcher package name is invalid: ${JSON.stringify(launcherName)}`);
+}
+const nativeName = `${scope}/aegis-darwin-arm64`;
+if (!isPlainObject(launcher.optionalDependencies)) {
+  refuse("launcher package metadata is malformed: optionalDependencies is required");
+}
+const dependencyKeys = Object.keys(launcher.optionalDependencies);
+if (dependencyKeys.length !== 1 || dependencyKeys[0] !== nativeName) {
+  refuse(
+    `launcher declares unexpected platform dependencies: ${JSON.stringify(dependencyKeys)}; ` +
+      `only ${nativeName} is supported`,
+  );
+}
+if (launcher.optionalDependencies[nativeName] !== launcherVersion) {
+  refuse(
+    `launcher platform dependency ${nativeName} is pinned to ` +
+      `${JSON.stringify(launcher.optionalDependencies[nativeName])}, not ${launcherVersion}`,
+  );
+}
+
+const require = createRequire(import.meta.url);
+let nativePackagePath;
+try {
+  nativePackagePath = require.resolve(`${nativeName}/package.json`);
+} catch {
+  refuse(
+    `native payload package ${nativeName}@${launcherVersion} is not installed. ` +
+      `Reinstall the launcher so its optional dependency lands: ` +
+      `npm install ${launcherName}@${launcherVersion} on a macOS ${MINIMUM_MACOS_MAJOR}+ arm64 host.`,
+  );
+}
+const nativeDir = dirname(nativePackagePath);
+const native = readJson(nativePackagePath, "native package metadata");
+if (native.name !== nativeName || native.version !== launcherVersion) {
+  refuse(
+    `native package identity mismatch: expected ${nativeName}@${launcherVersion}, ` +
+      `found ${JSON.stringify(native.name)}@${JSON.stringify(native.version)}`,
+  );
+}
+
+const manifest = readJson(join(nativeDir, MANIFEST_NAME), "native manifest");
+if (manifest.schema !== MANIFEST_SCHEMA) {
+  refuse(`native manifest schema is invalid: expected ${MANIFEST_SCHEMA}`);
+}
+if (manifest.version !== launcherVersion) {
+  refuse(
+    `native manifest version ${JSON.stringify(manifest.version)} does not match ` +
+      `launcher ${launcherVersion}`,
+  );
+}
+if (!isPlainObject(manifest.payload) || manifest.payload.path !== PAYLOAD_PATH) {
+  refuse(`native manifest payload path is invalid: expected ${PAYLOAD_PATH}`);
+}
+if (
+  !Array.isArray(manifest.capabilities) ||
+  manifest.capabilities.length !== 1 ||
+  manifest.capabilities[0] !== CAPABILITY
+) {
+  refuse(`native manifest capability contract is invalid: expected ${CAPABILITY}`);
+}
+const compatibility = manifest.compatibility;
+if (
+  !isPlainObject(compatibility) ||
+  compatibility.os !== "darwin" ||
+  compatibility.cpu !== "arm64" ||
+  compatibility.libc !== "none" ||
+  compatibility.minimum_glibc !== null
+) {
+  refuse("native manifest compatibility contract is invalid");
+}
+
+const payloadPath = join(nativeDir, PAYLOAD_PATH);
+let payloadStat;
+try {
+  payloadStat = statSync(payloadPath);
+} catch {
+  refuse(`native payload is missing at ${payloadPath}`);
+}
+if (!payloadStat.isFile()) {
+  refuse(`native payload is not a regular file at ${payloadPath}`);
+}
+let payload;
+try {
+  payload = readFileSync(payloadPath);
+} catch (error) {
+  refuse(`native payload cannot be read: ${error.message}`);
+}
+const digest = createHash("sha256").update(payload).digest("hex");
+if (typeof manifest.payload.sha256 !== "string" || digest !== manifest.payload.sha256) {
+  refuse("native payload checksum does not match the manifest");
+}
+if (manifest.payload.byte_count !== payload.length) {
+  refuse("native payload byte count does not match the manifest");
+}
+if ((payloadStat.mode & 0o111) === 0) {
+  refuse("native payload is not executable");
+}
+if (
+  payload.length < 8 ||
+  payload.readUInt32LE(0) !== MH_MAGIC_64 ||
+  payload.readUInt32LE(4) !== CPU_TYPE_ARM64
+) {
+  refuse("native payload is not a Darwin arm64 Mach-O binary");
+}
+
+const child = spawn(payloadPath, process.argv.slice(2), { stdio: "inherit" });
+const forwarders = new Map();
+for (const signal of FORWARDED_SIGNALS) {
+  const handler = () => {
+    try {
+      child.kill(signal);
+    } catch {
+      // The child already exited; its own status decides the outcome.
+    }
+  };
+  forwarders.set(signal, handler);
+  process.on(signal, handler);
+}
+child.on("error", (error) => {
+  refuse(`failed to start the native payload: ${error.message}`);
+});
+child.on("exit", (code, signal) => {
+  for (const [name, handler] of forwarders) {
+    process.removeListener(name, handler);
+  }
+  if (signal) {
+    for (const name of FORWARDED_SIGNALS) {
+      process.removeAllListeners(name);
+    }
+    try {
+      process.kill(process.pid, signal);
+    } catch {
+      // Fall through to the conventional 128+signal status below.
+    }
+    process.exitCode = 128 + (SIGNAL_NUMBERS[signal] ?? 0);
+    return;
+  }
+  process.exitCode = typeof code === "number" ? code : 1;
+});

package/package.json

@@ -1,6 +1,44 @@
 {
+  "bin": {
+    "aegis": "aegis.mjs"
+  },
+  "bugs": {
+    "url": "https://github.com/mithran-hq/aegis/issues"
+  },
+  "cpu": [
+    "arm64"
+  ],
+  "description": "Aegis auth, gateway, and Forge CLI for macOS 15+ Apple silicon",
+  "files": [
+    "package.json",
+    "aegis.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://mithran.ai/docs",
+  "keywords": [
+    "aegis",
+    "auth",
+    "gateway",
+    "forge",
+    "cli",
+    "macos",
+    "arm64"
+  ],
+  "license": "Apache-2.0",
   "name": "@mithran-hq/aegis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "optionalDependencies": {
+    "@mithran-hq/aegis-darwin-arm64": "0.9.5"
+  },
+  "os": [
+    "darwin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mithran-hq/aegis.git"
+  },
+  "scripts": {
+    "postinstall": "node aegis.mjs skills install --npm-postinstall"
+  },
+  "version": "0.9.5"
 }