fix: tolerate unsigned validate manifests

Author: rafaelscosta

.aiox-core/cli/commands/validate/index.js

@@ -13,6 +13,7 @@
  *   aiox validate --repair           # Repair missing/corrupted files
  *   aiox validate --repair --dry-run # Preview repairs without applying
  *   aiox validate --detailed         # Show detailed file list
+ *   aiox validate --require-signature # Enforce signed manifests
  *   aiox validate --json             # Output as JSON
  */
 
@@ -63,6 +64,10 @@ function createValidateCommand() {
     .option('--detailed', 'Show detailed file list')
     .option('--no-hash', 'Skip hash verification (faster)')
     .option('--no-signature', 'Skip manifest signature verification (insecure; recovery only)')
+    .option(
+      '--require-signature',
+      'Fail when the manifest signature is missing (also enabled by AIOX_REQUIRE_SIGNATURE=1)',
+    )
     .option('--extras', 'Detect extra files not in manifest')
     .option('-v, --verbose', 'Enable verbose output')
     .option('--json', 'Output results as JSON')
@@ -86,6 +91,9 @@ Examples:
   ${chalk.dim('# Quick validation (skip hash check)')}
   $ aiox validate --no-hash
 
+  ${chalk.dim('# Strict validation (requires .minisig)')}
+  $ aiox validate --require-signature
+
   ${chalk.dim('# Output as JSON for CI/CD')}
   $ aiox validate --json
 
@@ -189,7 +197,7 @@ async function runValidation(options) {
     // Try to find source in common locations
     const possibleSources = [
       path.join(__dirname, '../../../../..'), // npm package root
-      path.join(projectRoot, 'node_modules/aiox-core'),
+      path.join(projectRoot, 'node_modules/@aiox-squads/core'),
       path.join(projectRoot, 'node_modules/aiox-core'),
     ];
 
@@ -201,6 +209,12 @@ async function runValidation(options) {
     }
   }
 
+  const requireSignature = resolveSignatureRequirement({
+    options,
+    aioxCoreDir,
+    sourceDir,
+  });
+
   // Show spinner for non-JSON output (must be defined before validator for closure)
   let spinner = null;
   if (!options.json) {
@@ -214,7 +228,7 @@ async function runValidation(options) {
   // Create validator instance
   const validator = new PostInstallValidator(projectRoot, sourceDir, {
     verifyHashes: options.hash !== false,
-    requireSignature: options.signature !== false,
+    requireSignature,
     detectExtras: options.extras === true,
     verbose: options.verbose === true,
     onProgress: options.json
@@ -266,6 +280,7 @@ async function runValidation(options) {
         status: report.status,
         integrityScore: report.integrityScore,
         manifestVerified: report.manifestVerified,
+        signatureRequired: report.signatureRequired,
         timestamp: report.timestamp,
         duration: report.duration,
         manifest: report.manifest,
@@ -343,6 +358,54 @@ async function runValidation(options) {
   }
 }
 
+/**
+ * Resolve whether validate should require manifest signature verification.
+ *
+ * Default behavior verifies signatures automatically when a .minisig is
+ * present, but it does not hard-fail public packages that were distributed
+ * without the signature artifact. Strict mode remains available via
+ * --require-signature or AIOX_REQUIRE_SIGNATURE=1.
+ *
+ * @param {Object} params - Resolution params
+ * @param {Object} params.options - Commander options
+ * @param {string} params.aioxCoreDir - Installed .aiox-core directory
+ * @param {string|null} [params.sourceDir] - Source package directory
+ * @param {Object} [params.env] - Environment object for tests
+ * @returns {boolean} True when validation must require a valid signature
+ */
+function resolveSignatureRequirement({ options = {}, aioxCoreDir, sourceDir = null, env = process.env }) {
+  if (options.signature === false) {
+    return false;
+  }
+
+  if (options.requireSignature === true || isTruthyEnv(env.AIOX_REQUIRE_SIGNATURE)) {
+    return true;
+  }
+
+  const targetSignaturePath = path.join(aioxCoreDir, 'install-manifest.yaml.minisig');
+  if (fs.existsSync(targetSignaturePath)) {
+    return true;
+  }
+
+  if (sourceDir) {
+    const sourceSignaturePath = path.join(sourceDir, '.aiox-core', 'install-manifest.yaml.minisig');
+    if (fs.existsSync(sourceSignaturePath)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Interpret common truthy environment variable values.
+ * @param {string|undefined} value - Raw environment value
+ * @returns {boolean} True when the value enables the setting
+ */
+function isTruthyEnv(value) {
+  return ['1', 'true', 'yes', 'on'].includes(String(value || '').trim().toLowerCase());
+}
+
 /**
  * Run repair process
  * @param {PostInstallValidator} validator - Validator instance
@@ -428,4 +491,5 @@ function truncatePath(filePath, maxLen) {
 
 module.exports = {
   createValidateCommand,
+  resolveSignatureRequirement,
 };

.aiox-core/install-manifest.yaml

@@ -7,8 +7,8 @@
 # - SHA256 hashes for change detection
 # - File types for categorization
 #
-version: 5.1.0
-generated_at: "2026-05-07T08:02:17.787Z"
+version: 5.1.1
+generated_at: "2026-05-07T10:20:29.036Z"
 generator: scripts/generate-install-manifest.js
 file_count: 1103
 files:
@@ -121,9 +121,9 @@ files:
     type: cli
     size: 5320
   - path: cli/commands/validate/index.js
-    hash: sha256:dcf19f1b4a46e562812c5c718783e88f9ac8ef0bf51f27eb1a6d31c7081fafdf
+    hash: sha256:8c695b2cde5390a867922f37dd5a89c539fe4c688303a1eb52f097a747d599ad
     type: cli
-    size: 13040
+    size: 15206
   - path: cli/commands/workers/formatters/info-formatter.js
     hash: sha256:11c17e16be0b7d09ba8949497e0887bb20996966d266454aa2bb5dfc9d9d91b8
     type: cli

docs/security/MANIFEST_SIGNING.md

@@ -186,6 +186,17 @@ The signature blob encoding follows the minisign specification. For reference, t
 
 **Note**: Applications should use the verification module (`manifest-signature.js`) rather than parsing the signature format directly. The exact wire format is defined by the minisign specification and may vary in optional fields.
 
+## CLI Verification Modes
+
+The `aiox validate` command uses a compatibility-safe default:
+
+- If `.aiox-core/install-manifest.yaml.minisig` exists in the target or repair source, the signature is verified automatically.
+- If no `.minisig` was distributed with the package, validation continues without signature verification and still verifies file hashes.
+- Strict enforcement is available with `aiox validate --require-signature` or `AIOX_REQUIRE_SIGNATURE=1`.
+- Emergency recovery can explicitly bypass verification with `aiox validate --no-signature`.
+
+This keeps unsigned public packages installable while preserving an explicit strict mode for signed releases and controlled environments.
+
 ## Development Mode
 
 During development and testing, signature verification can be bypassed:
@@ -203,14 +214,16 @@ const validator = new PostInstallValidator(projectRoot, frameworkRoot, {
 - Tampered manifests will be accepted
 - The trust chain is broken
 
-This option exists **exclusively** for local development environments. Production builds **MUST** enforce signature verification (`requireSignature: true`). Any deployment with signature verification disabled should be considered insecure.
+This option exists **exclusively** for local development, recovery, and unsigned package compatibility. Production builds that distribute `.minisig` artifacts **MUST** enforce signature verification (`requireSignature: true`) or run `aiox validate --require-signature`. Any deployment with signature verification disabled should be considered unsigned.
 
 ## Verification Behavior
 
 | Mode                                    | Signature Missing | Invalid Signature | Valid Signature |
 | --------------------------------------- | ----------------- | ----------------- | --------------- |
 | Production (`requireSignature: true`)   | ERROR             | ERROR             | OK              |
 | Development (`requireSignature: false`) | WARN              | ERROR             | OK              |
+| CLI default, no `.minisig` distributed  | WARN              | ERROR             | OK              |
+| CLI default, `.minisig` present         | ERROR             | ERROR             | OK              |
 
 ## Troubleshooting
 
@@ -281,7 +294,7 @@ Loads and verifies a manifest file.
 **Parameters:**
 
 - `manifestPath` (string): Path to manifest file
-- `options.requireSignature` (boolean): Fail if signature missing (default: true)
+- `options.requireSignature` (boolean): Fail if signature missing (default: true for the library API; CLI default is resolved by `.minisig` presence or strict flags)
 
 **Returns:**
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiox-squads/core",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "description": "Synkra AIOX: AI-Orchestrated System for Full Stack Development - Core Framework",
   "bin": {
     "aiox": "bin/aiox.js",

package.json

@@ -1095,6 +1095,7 @@ class PostInstallValidator {
       status,
       integrityScore,
       manifestVerified: this.manifestVerified,
+      signatureRequired: this.options.requireSignature,
       timestamp: new Date().toISOString(),
       duration: `${duration}ms`,
       manifest: this.manifest
@@ -1419,8 +1420,10 @@ function formatReport(report, options = {}) {
   // Signature status
   if (report.manifestVerified) {
     lines.push(`${c.green}✓${c.reset} Manifest signature: ${c.green}VERIFIED${c.reset}`);
-  } else {
+  } else if (report.signatureRequired) {
     lines.push(`${c.red}✗${c.reset} Manifest signature: ${c.red}NOT VERIFIED${c.reset}`);
+  } else {
+    lines.push(`${c.yellow}⚠${c.reset} Manifest signature: ${c.yellow}NOT REQUIRED${c.reset}`);
   }
 
   // Status

packages/installer/src/installer/post-install-validator.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const fs = require('fs-extra');
+const os = require('os');
+const path = require('path');
+
+const {
+  resolveSignatureRequirement,
+} = require('../../.aiox-core/cli/commands/validate/index');
+
+describe('validate signature mode', () => {
+  let testDir;
+  let aioxCoreDir;
+  let sourceDir;
+
+  beforeEach(async () => {
+    testDir = await fs.mkdtemp(path.join(os.tmpdir(), 'aiox-validate-signature-'));
+    aioxCoreDir = path.join(testDir, 'project', '.aiox-core');
+    sourceDir = path.join(testDir, 'source');
+    await fs.ensureDir(aioxCoreDir);
+    await fs.ensureDir(path.join(sourceDir, '.aiox-core'));
+  });
+
+  afterEach(async () => {
+    await fs.remove(testDir);
+  });
+
+  test('does not require signature when public package lacks minisig', () => {
+    expect(
+      resolveSignatureRequirement({
+        options: {},
+        aioxCoreDir,
+        sourceDir,
+        env: {},
+      }),
+    ).toBe(false);
+  });
+
+  test('requires signature when strict flag is set', () => {
+    expect(
+      resolveSignatureRequirement({
+        options: { requireSignature: true },
+        aioxCoreDir,
+        sourceDir,
+        env: {},
+      }),
+    ).toBe(true);
+  });
+
+  test('requires signature when strict env is set', () => {
+    expect(
+      resolveSignatureRequirement({
+        options: {},
+        aioxCoreDir,
+        sourceDir,
+        env: { AIOX_REQUIRE_SIGNATURE: 'true' },
+      }),
+    ).toBe(true);
+  });
+
+  test('no-signature flag overrides strict env and local signature', async () => {
+    await fs.writeFile(path.join(aioxCoreDir, 'install-manifest.yaml.minisig'), 'signature');
+
+    expect(
+      resolveSignatureRequirement({
+        options: { signature: false },
+        aioxCoreDir,
+        sourceDir,
+        env: { AIOX_REQUIRE_SIGNATURE: '1' },
+      }),
+    ).toBe(false);
+  });
+
+  test('requires signature automatically when target minisig exists', async () => {
+    await fs.writeFile(path.join(aioxCoreDir, 'install-manifest.yaml.minisig'), 'signature');
+
+    expect(
+      resolveSignatureRequirement({
+        options: {},
+        aioxCoreDir,
+        sourceDir,
+        env: {},
+      }),
+    ).toBe(true);
+  });
+
+  test('requires signature automatically when source minisig exists', async () => {
+    await fs.writeFile(
+      path.join(sourceDir, '.aiox-core', 'install-manifest.yaml.minisig'),
+      'signature',
+    );
+
+    expect(
+      resolveSignatureRequirement({
+        options: {},
+        aioxCoreDir,
+        sourceDir,
+        env: {},
+      }),
+    ).toBe(true);
+  });
+});

tests/cli/validate-signature-mode.test.js

@@ -243,6 +243,7 @@ describe('PostInstallValidator Security Tests', () => {
 
       // Should succeed without signature in dev mode
       expect(report.manifestVerified).toBe(false);
+      expect(report.signatureRequired).toBe(false);
       expect(report.status).not.toBe('failed');
     });
   });