@aria_asi/cli 0.2.29 → 0.2.31

package/hooks/test-tier-lens-labeling.mjs

@@ -1,13 +1,12 @@
 #!/usr/bin/env node
-// Smoke test: Phase 11 #59 — tier-aware lens labeling
+// Smoke test: Phase 11 #59 — canonical lens labeling
 //
 // Verifies that aria-pre-tool-gate.mjs and aria-stop-gate.mjs:
 //   1. Show canonical Arabic lens names (nur, mizan, etc.) when the harness
 //      packet has isHamza/hamza=true (OWNER tier).
-//   2. Show neutral generic labels (perception, balance, etc.) when the
-//      harness packet is client-surface (CLIENT tier).
+//   2. Preserve those same canonical labels on client-surface execution too.
 //   3. Gate enforcement (block on insufficient cognition) fires in both
-//      tiers — label swap does not change gate substance.
+//      tiers without renaming the lenses.
 //
 // Usage: node hooks/test-tier-lens-labeling.mjs
 // Exit:  0 = all assertions passed, 1 = failure
@@ -24,9 +23,8 @@ const HOME = process.env.HOME || '/tmp';
 const CLAUDE_DIR = `${HOME}/.claude`;
 const PACKET_PATH = `${CLAUDE_DIR}/.aria-harness-last-packet.json`;
 
-// ── Canonical vs generic label sets ────────────────────────────────────────
+// ── Canonical label set ────────────────────────────────────────────────────
 const CANONICAL = ['nur', 'mizan', 'hikma', 'tafakkur', 'tadabbur', 'ilham', 'wahi', 'firasah'];
-const GENERIC   = ['perception', 'balance', 'wisdom', 'reflection', 'foresight', 'insight', 'revelation', 'discernment'];
 
 // ── Assertion helpers ───────────────────────────────────────────────────────
 let passed = 0;
@@ -225,21 +223,17 @@ console.log('Test 1: aria-pre-tool-gate — OWNER tier shows canonical lens name
     blockReason.slice(0, 400),
   );
 
-  // Must NOT mention generic labels — no IP exposure for owner
-  // (owner should only see canonical; absence of generic is nice-to-verify
-  // but not a hard requirement since some generic words may appear in prose)
-  // Instead check the first lens label is canonical not generic:
+  // The first visible lens label must be canonical.
   const firstCanonicalIdx = blockReason.indexOf(`${CANONICAL[0]}:`);
-  const firstGenericIdx = blockReason.indexOf(`${GENERIC[0]}:`);
   assert(
-    'T1: first lens label is canonical (nur:), not generic (perception:)',
-    firstCanonicalIdx >= 0 && (firstGenericIdx < 0 || firstCanonicalIdx < firstGenericIdx),
-    `firstCanonicalIdx=${firstCanonicalIdx} firstGenericIdx=${firstGenericIdx}`,
+    'T1: first lens label is canonical (nur:)',
+    firstCanonicalIdx >= 0,
+    `firstCanonicalIdx=${firstCanonicalIdx}`,
   );
 }
 
-// ── Test 2: pre-tool-gate, CLIENT tier → generic labels in block reason ──
-console.log('\nTest 2: aria-pre-tool-gate — CLIENT tier shows generic lens labels');
+// ── Test 2: pre-tool-gate, CLIENT tier → canonical labels in block reason ──
+console.log('\nTest 2: aria-pre-tool-gate — CLIENT tier keeps canonical lens labels');
 {
   writeClientPacket();
   writeEmptyTranscript(tmpTranscript);
@@ -259,32 +253,15 @@ console.log('\nTest 2: aria-pre-tool-gate — CLIENT tier shows generic lens lab
     blockReason = result.stdout || '';
   }
 
-  // Must mention at least one generic label
-  const hasGeneric = GENERIC.some((name) => blockReason.includes(`${name}:`));
+  const hasCanonical = CANONICAL.some((name) => blockReason.includes(`${name}:`));
   assert(
-    'T2: block reason mentions generic label (e.g. perception:)',
-    hasGeneric,
+    'T2: block reason mentions canonical label (e.g. nur:)',
+    hasCanonical,
     blockReason.slice(0, 400),
   );
-
-  // Must NOT expose canonical Arabic names
-  const exposesCanonical = CANONICAL.some((name) =>
-    blockReason.includes(`${name}:`),
-  );
-  assert(
-    'T2: block reason does NOT expose canonical Arabic lens names',
-    !exposesCanonical,
-    `canonical leak: ${CANONICAL.filter((n) => blockReason.includes(`${n}:`)).join(', ')} in: ${blockReason.slice(0, 300)}`,
-  );
-
-  // Check doctrine memory filename is neutralized (no feedback_no_flag_without_fix.md for client)
-  const noDocFileLeak = !blockReason.includes('feedback_no_flag_without_fix.md');
-  // (This specific file only appears in discovery-unresolved path; just verify
-  // that the block reason itself also neutralizes EIGHT_LENS_DOCTRINE references if any)
-  // For this test we just assert the generic label set is present.
   assert(
-    'T2: first generic label (perception:) appears in block reason',
-    blockReason.includes(`${GENERIC[0]}:`),
+    'T2: first visible lens label is canonical (nur:)',
+    blockReason.includes(`${CANONICAL[0]}:`),
     blockReason.slice(0, 400),
   );
 }
@@ -318,8 +295,8 @@ console.log('\nTest 3: aria-stop-gate — OWNER tier shows canonical lens names'
   );
 }
 
-// ── Test 4: stop-gate, CLIENT tier → generic labels, no canonical leak ──
-console.log('\nTest 4: aria-stop-gate — CLIENT tier shows generic labels, no canonical leak');
+// ── Test 4: stop-gate, CLIENT tier → canonical labels ──────────────────────
+console.log('\nTest 4: aria-stop-gate — CLIENT tier keeps canonical lens labels');
 {
   writeClientPacket();
   writeNoCognitionStopTranscript(tmpTranscriptStop);
@@ -339,23 +316,16 @@ console.log('\nTest 4: aria-stop-gate — CLIENT tier shows generic labels, no c
     blockReason = result.stdout || '';
   }
 
-  const hasGeneric = GENERIC.some((name) => blockReason.includes(`${name}:`));
+  const hasCanonical = CANONICAL.some((name) => blockReason.includes(`${name}:`));
   assert(
-    'T4: stop-gate block reason mentions generic label',
-    hasGeneric,
+    'T4: stop-gate block reason mentions canonical label',
+    hasCanonical,
     blockReason.slice(0, 400),
   );
-
-  const exposesCanonical = CANONICAL.some((name) => blockReason.includes(`${name}:`));
-  assert(
-    'T4: stop-gate block reason does NOT expose canonical lens names',
-    !exposesCanonical,
-    `canonical leak: ${CANONICAL.filter((n) => blockReason.includes(`${n}:`)).join(', ')}`,
-  );
 }
 
-// ── Test 5: packet missing → defaults to CLIENT tier (fail-safe) ──────────
-console.log('\nTest 5: missing packet cache → defaults to CLIENT tier (fail-safe)');
+// ── Test 5: packet missing → defaults to canonical labels (fail-safe) ─────
+console.log('\nTest 5: missing packet cache → defaults to canonical labels');
 {
   // Remove the packet cache
   try { unlinkSync(PACKET_PATH); } catch {}
@@ -376,13 +346,11 @@ console.log('\nTest 5: missing packet cache → defaults to CLIENT tier (fail-sa
     blockReason = result.stdout || '';
   }
 
-  // With no packet, should default to generic (client-safe fail direction)
-  const hasGeneric = GENERIC.some((name) => blockReason.includes(`${name}:`));
-  const exposesCanonical = CANONICAL.some((name) => blockReason.includes(`${name}:`));
+  const hasCanonical = CANONICAL.some((name) => blockReason.includes(`${name}:`));
   assert(
-    'T5: defaults to generic labels when packet is absent',
-    hasGeneric && !exposesCanonical,
-    `generic=${hasGeneric} canonicalLeak=${exposesCanonical} reason=${blockReason.slice(0, 300)}`,
+    'T5: defaults to canonical labels when packet is absent',
+    hasCanonical,
+    `canonical=${hasCanonical} reason=${blockReason.slice(0, 300)}`,
   );
 }
 

package/opencode-plugins/harness-gate/index.js

@@ -2,7 +2,7 @@
  * Aria Harness Gate — pre-tool cognition enforcement for OpenCode.
  * Routes through HTTPHarnessClient SDK for substrate-backed validation.
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
@@ -15,6 +15,7 @@ const SDK_CANDIDATES = [
 const OWNER_TOKEN_PATH = join(HOME, '.aria', 'owner-token');
 const LICENSE_PATH = join(HOME, '.aria', 'license.json');
 const RUNTIME_URL = (process.env.ARIA_RUNTIME_URL || 'http://127.0.0.1:4319').replace(/\/+$/, '');
+const RECEIPT_DIR = join(HOME, '.opencode', 'aria-mizan-receipts');
 
 const DESTRUCTIVE_PATTERNS = [
   { rx: /(?:^|[;&|]\s*|\$\(\s*|`\s*)sudo\s+\S/, name: 'sudo' },
@@ -41,7 +42,7 @@ const DEPLOY_PATTERNS = [
   { rx: /\bdocker\s+build\b.*--push\b/, name: 'docker-build-push' },
 ];
 
-const INLINE_LENS_RX = /^\s*#\s*(?:nur|mizan|hikma|tafakkur|tadabbur|ilham|wahi|firasah|perception|balance|wisdom|reflection|foresight|insight|revelation|discernment)\s*:\s*.{20,}/im;
+const INLINE_LENS_RX = /^\s*#\s*(?:nur|mizan|hikma|tafakkur|tadabbur|ilham|wahi|firasah|truth|harm|trust|power|reflection|context|impact|beauty)\s*:\s*.{20,}/im;
 const VERIFY_BLOCK_RX = /<verify>[\s\S]*?target\s*:[\s\S]*?verified\s*:[\s\S]*?axiom\s*:[\s\S]*?<\/verify>/i;
 const TRIVIAL_BASH_RX = /^\s*(?:ls|cat|head|tail|grep|find|echo|wc|stat|which|pwd|date|file|du|df|ss|ps)\s/;
 const SHORT_BASH_LIMIT = 30;
@@ -51,6 +52,17 @@ let _clientError = null;
 let _lastMizanReceipt = null;
 let _lastActionSummary = '';
 
+function receiptPath(sessionId) {
+  return join(RECEIPT_DIR, `${String(sessionId || 'opencode').replace(/[^a-zA-Z0-9_-]/g, '_')}.json`);
+}
+
+function persistReceipt(sessionId, payload) {
+  try {
+    mkdirSync(RECEIPT_DIR, { recursive: true, mode: 0o755 });
+    writeFileSync(receiptPath(sessionId), JSON.stringify(payload, null, 2) + '\n');
+  } catch {}
+}
+
 function resolveToken() {
   if (process.env.ARIA_HARNESS_TOKEN) return process.env.ARIA_HARNESS_TOKEN;
   if (process.env.ARIA_API_KEY) return process.env.ARIA_API_KEY;
@@ -182,6 +194,16 @@ export default async function HarnessGatePlugin(ctx) {
           },
         });
         _lastMizanReceipt = pre.receipt || null;
+        if (_lastMizanReceipt) {
+          persistReceipt(sessionId, {
+            updatedAt: new Date().toISOString(),
+            sessionId,
+            receipt: _lastMizanReceipt,
+            preResult: pre.result || null,
+            preContract: pre.contract || null,
+            preSummary: pre.summary || null,
+          });
+        }
         _lastActionSummary = cmdPreview;
         if (pre.receipt?.blocked || pre.result?.fitrahVetoed || pre.result?.reAuthorSignal) {
           throw new Error(

package/opencode-plugins/harness-stop/index.js

@@ -2,7 +2,7 @@
  * Aria Harness Stop — text-emission gate via HTTPHarnessClient SDK.
  * Routes text through Mizan validateOutput() for substrate-backed QC.
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
@@ -15,10 +15,11 @@ const SDK_CANDIDATES = [
 const OWNER_TOKEN_PATH = join(HOME, '.aria', 'owner-token');
 const LICENSE_PATH = join(HOME, '.aria', 'license.json');
 const RUNTIME_URL = (process.env.ARIA_RUNTIME_URL || 'http://127.0.0.1:4319').replace(/\/+$/, '');
+const RECEIPT_DIR = join(HOME, '.opencode', 'aria-mizan-receipts');
 
 const LENS_NAMES = [
   'nur', 'mizan', 'hikma', 'tafakkur', 'tadabbur', 'ilham', 'wahi', 'firasah',
-  'perception', 'balance', 'wisdom', 'reflection', 'foresight', 'insight', 'revelation', 'discernment',
+  'truth', 'harm', 'trust', 'power', 'reflection', 'context', 'impact', 'beauty',
 ];
 
 const COGNITION_BLOCK_RX = /<cognition>([\s\S]*?)<\/cognition>/i;
@@ -33,6 +34,27 @@ let _client = null;
 let _clientError = null;
 let _lastMizanReceipt = null;
 
+function receiptPath(sessionId) {
+  return join(RECEIPT_DIR, `${String(sessionId || 'opencode').replace(/[^a-zA-Z0-9_-]/g, '_')}.json`);
+}
+
+function loadReceiptState(sessionId) {
+  try {
+    const target = receiptPath(sessionId);
+    if (!existsSync(target)) return null;
+    return JSON.parse(readFileSync(target, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function persistReceiptState(sessionId, payload) {
+  try {
+    mkdirSync(RECEIPT_DIR, { recursive: true, mode: 0o755 });
+    writeFileSync(receiptPath(sessionId), JSON.stringify(payload, null, 2) + '\n');
+  } catch {}
+}
+
 function resolveToken() {
   if (process.env.ARIA_HARNESS_TOKEN) return process.env.ARIA_HARNESS_TOKEN;
   if (process.env.ARIA_API_KEY) return process.env.ARIA_API_KEY;
@@ -100,6 +122,7 @@ async function runtimeValidateOutput(text, sessionId) {
 }
 
 async function runtimeMizanPost(text, sessionId, context = {}) {
+  const existing = loadReceiptState(sessionId);
   const token = resolveToken();
   if (!token) throw new Error('no token');
   const response = await fetch(`${RUNTIME_URL}/mizan/post`, {
@@ -115,7 +138,7 @@ async function runtimeMizanPost(text, sessionId, context = {}) {
         sessionId,
         ...context,
       },
-      parentReceiptId: _lastMizanReceipt?.receiptId || null,
+      parentReceiptId: existing?.receipt?.receiptId || _lastMizanReceipt?.receiptId || null,
     }),
   });
   if (!response.ok) {
@@ -125,6 +148,24 @@ async function runtimeMizanPost(text, sessionId, context = {}) {
   return response.json();
 }
 
+async function runtimeDecisionLog(payload) {
+  const token = resolveToken();
+  if (!token) throw new Error('no token');
+  const response = await fetch(`${RUNTIME_URL}/decision/log`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify(payload),
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(body?.error || `runtime decision/log failed ${response.status}`);
+  }
+  return body;
+}
+
 function detectCognitionLenses(text) {
   if (!text) return { count: 0, names: [] };
   const block = text.match(COGNITION_BLOCK_RX);
@@ -172,6 +213,18 @@ export default async function HarnessStopPlugin(ctx) {
           plannedApproach: 'OpenCode stop gate output review',
         });
         _lastMizanReceipt = mizan.receipt || _lastMizanReceipt;
+        if (_lastMizanReceipt) {
+          const existing = loadReceiptState(sessionId) || {};
+          persistReceiptState(sessionId, {
+            ...existing,
+            updatedAt: new Date().toISOString(),
+            sessionId,
+            postReceipt: _lastMizanReceipt,
+            postResult: mizan.result || null,
+            postContract: mizan.contract || null,
+            postSummary: mizan.summary || null,
+          });
+        }
         if (mizan.receipt?.blocked || mizan.result?.fitrahVetoed || mizan.result?.reAuthorSignal) {
           process.stderr.write(
             `[harness-stop] MIZAN POST BLOCK — ${(mizan.result?.notes || ['post-phase blocked']).slice(0, 4).join(' | ')}\n`
@@ -213,10 +266,18 @@ export default async function HarnessStopPlugin(ctx) {
 
       // Local fallback gate
       // Scan drift triggers
-      const triggerMapPath = `${HOME}/.claude/hooks/doctrine_trigger_map.json`;
+      const triggerMapPaths = [
+        `${HOME}/.aria/runtime/discipline/doctrine_trigger_map.json`,
+        `${HOME}/.aria/runtime/doctrine_trigger_map.json`,
+        `${HOME}/.opencode/doctrine_trigger_map.json`,
+        `${HOME}/.codex/doctrine_trigger_map.json`,
+        `${HOME}/.claude/hooks/doctrine_trigger_map.json`,
+        `${HOME}/.claude/projects/-home-hamzaibrahim1/memory/doctrine_trigger_map.json`,
+      ];
       let driftHits = [];
       try {
-        if (existsSync(triggerMapPath)) {
+        const triggerMapPath = triggerMapPaths.find((candidate) => existsSync(candidate));
+        if (triggerMapPath) {
           const triggerMap = JSON.parse(readFileSync(triggerMapPath, 'utf8'));
           const lower = text.toLowerCase();
           for (const t of triggerMap.triggers || []) {
@@ -236,6 +297,34 @@ export default async function HarnessStopPlugin(ctx) {
           `[harness-stop] LOCAL GATE — cognition=${cog.count}/${REQUIRED_LENSES} drift=${driftHits.length}\n`
         );
       }
+
+      try {
+        const existing = loadReceiptState(sessionId);
+        await runtimeDecisionLog({
+          decision_type: 'turn_action',
+          category: 'agentic_execution',
+          context: `opencode stop-gate turn (chars=${text.length})`,
+          decision: 'turn completed',
+          reasoning: cog.count > 0
+            ? `Cognition lenses applied: ${cog.names.join(', ')}.`
+            : 'No explicit cognition block in turn.',
+          outcome: 'pending',
+          outcome_details: {
+            expected: null,
+            immediate_actual: null,
+            anchors: [],
+          },
+          expected_outcome: null,
+          metadata: {
+            pre_receipt_id: existing?.receipt?.receiptId || null,
+            post_receipt_id: _lastMizanReceipt?.receiptId || null,
+          },
+          source: 'opencode-stop-gate-runtime',
+          model_used: process.env.OPENCODE_MODEL || 'opencode',
+        });
+      } catch (e) {
+        process.stderr.write(`[harness-stop] decision/log unavailable: ${e.message}\n`);
+      }
     },
   };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aria_asi/cli",
-  "version": "0.2.29",
-  "description": "Aria Smart CLI — the world's first harness-powered terminal companion",
+  "version": "0.2.31",
+  "description": "Aria Smart CLI \u2014 the world's first harness-powered terminal companion",
   "bin": {
     "aria": "./bin/aria.js"
   },

package/runtime-src/auth-middleware.mjs

@@ -0,0 +1,251 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const STATE_DIR = join(__dirname, '..', 'state');
+const KEYS_PATH = join(STATE_DIR, 'api-keys.json');
+const USERS_PATH = join(STATE_DIR, 'users.json');
+const SESSIONS_PATH = join(STATE_DIR, 'sessions.json');
+const SCRYPT_KEY_LENGTH = 32;
+const SCRYPT_COST = 16384;
+const SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+
+const OWNER_USERNAME = 'admin';
+const OWNER_PASSWORD_HASH = hashPassword('Loveala613#');
+
+function ensureDir(p) {
+  if (!existsSync(p)) mkdirSync(p, { recursive: true });
+}
+
+function loadJson(path, fallback = []) {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function saveJson(path, data) {
+  ensureDir(dirname(path));
+  writeFileSync(path, JSON.stringify(data, null, 2));
+}
+
+function hashPassword(password) {
+  return scryptSync(password, 'aria-hq-user-salt-v2', SCRYPT_COST, 8, 1, SCRYPT_KEY_LENGTH).toString('hex');
+}
+
+function hashKey(key) {
+  return scryptSync(key, 'aria-hq-api-key-salt', SCRYPT_COST, 8, 1, SCRYPT_KEY_LENGTH).toString('hex');
+}
+
+// ─── API Key Management ───────────────────────────────────────
+
+function loadKeys() {
+  return loadJson(KEYS_PATH, []);
+}
+
+function saveKeys(keys) {
+  saveJson(KEYS_PATH, keys);
+}
+
+export function generateApiKey(tenantId) {
+  const raw = randomBytes(32).toString('hex');
+  const key = `aria_${raw.slice(0, 8)}_${raw.slice(8)}`;
+  const keyHash = hashKey(key);
+  const keys = loadKeys();
+  const existing = keys.findIndex(k => k.tenantId === tenantId);
+  const entry = {
+    tenantId,
+    keyHash,
+    keyPrefix: key.slice(0, 15),
+    createdAt: new Date().toISOString(),
+  };
+  if (existing >= 0) keys[existing] = entry; else keys.push(entry);
+  saveKeys(keys);
+  return key;
+}
+
+export function validateApiKey(key) {
+  if (!key || typeof key !== 'string') return { valid: false, tenantId: null };
+  const keys = loadKeys();
+  const keyHash = hashKey(key);
+  for (const entry of keys) {
+    try {
+      if (timingSafeEqual(Buffer.from(keyHash), Buffer.from(entry.keyHash))) {
+        return { valid: true, tenantId: entry.tenantId };
+      }
+    } catch {
+      continue;
+    }
+  }
+  return { valid: false, tenantId: null };
+}
+
+export function rotateApiKey(tenantId) {
+  return generateApiKey(tenantId);
+}
+
+export function revokeApiKey(tenantId) {
+  const keys = loadKeys();
+  const filtered = keys.filter(k => k.tenantId !== tenantId);
+  saveKeys(filtered);
+  return filtered.length < keys.length;
+}
+
+// ─── User Management ──────────────────────────────────────────
+
+export function registerUser(email, password, tenantId) {
+  if (!email || !password || !tenantId) {
+    return { ok: false, error: 'email, password, and tenantId required' };
+  }
+  const users = loadJson(USERS_PATH, []);
+  if (users.find(u => u.email === email.toLowerCase().trim())) {
+    return { ok: false, error: 'User already exists' };
+  }
+  if (users.find(u => u.tenantId === tenantId)) {
+    return { ok: false, error: 'Tenant already has a registered user' };
+  }
+  const user = {
+    id: randomBytes(16).toString('hex'),
+    email: email.toLowerCase().trim(),
+    passwordHash: hashPassword(password),
+    role: 'client',
+    tenantId,
+    createdAt: new Date().toISOString(),
+    lastLogin: null,
+  };
+  users.push(user);
+  saveJson(USERS_PATH, users);
+  return { ok: true, user: { id: user.id, email: user.email, role: user.role, tenantId: user.tenantId } };
+}
+
+export function loginUser(usernameOrEmail, password) {
+  if (usernameOrEmail === OWNER_USERNAME) {
+    try {
+      if (timingSafeEqual(Buffer.from(hashPassword(password)), Buffer.from(OWNER_PASSWORD_HASH))) {
+        const session = createSession({ userId: 'owner', role: 'owner', tenantId: null, email: OWNER_USERNAME });
+        return { ok: true, session, user: { id: 'owner', email: OWNER_USERNAME, role: 'owner', tenantId: null } };
+      }
+    } catch {
+      return { ok: false, error: 'Invalid credentials' };
+    }
+    return { ok: false, error: 'Invalid credentials' };
+  }
+
+  const users = loadJson(USERS_PATH, []);
+  const user = users.find(u => u.email === usernameOrEmail.toLowerCase().trim());
+  if (!user) return { ok: false, error: 'No account found with that email' };
+  try {
+    if (timingSafeEqual(Buffer.from(hashPassword(password)), Buffer.from(user.passwordHash))) {
+      const session = createSession({ userId: user.id, role: user.role, tenantId: user.tenantId, email: user.email });
+      user.lastLogin = new Date().toISOString();
+      saveJson(USERS_PATH, users);
+      return { ok: true, session, user: { id: user.id, email: user.email, role: user.role, tenantId: user.tenantId } };
+    }
+  } catch {
+    return { ok: false, error: 'Invalid password' };
+  }
+  return { ok: false, error: 'Invalid password' };
+}
+
+// ─── Session Management ───────────────────────────────────────
+
+function createSession(identity) {
+  const token = `hq_${randomBytes(32).toString('hex')}`;
+  const session = {
+    token,
+    userId: identity.userId,
+    role: identity.role,
+    tenantId: identity.tenantId,
+    email: identity.email,
+    createdAt: new Date().toISOString(),
+    expiresAt: new Date(Date.now() + SESSION_TTL_MS).toISOString(),
+  };
+  const sessions = loadJson(SESSIONS_PATH, []);
+  sessions.push(session);
+  saveJson(SESSIONS_PATH, sessions);
+  return { token, role: identity.role, tenantId: identity.tenantId, email: identity.email };
+}
+
+export function validateSession(token) {
+  if (!token || typeof token !== 'string') return { valid: false };
+  const sessions = loadJson(SESSIONS_PATH, []);
+  const session = sessions.find(s => s.token === token);
+  if (!session) return { valid: false };
+  if (new Date(session.expiresAt) < new Date()) {
+    revokeSession(token);
+    return { valid: false };
+  }
+  return {
+    valid: true,
+    userId: session.userId,
+    role: session.role,
+    tenantId: session.tenantId,
+    email: session.email,
+  };
+}
+
+export function revokeSession(token) {
+  const sessions = loadJson(SESSIONS_PATH, []);
+  const filtered = sessions.filter(s => s.token !== token);
+  saveJson(SESSIONS_PATH, filtered);
+}
+
+// ─── Owner Tenant Listing ─────────────────────────────────────
+
+export function listAllTenants() {
+  const users = loadJson(USERS_PATH, []);
+  const results = [];
+  for (const user of users) {
+    if (user.role !== 'client') continue;
+    results.push({
+      tenantId: user.tenantId,
+      email: user.email,
+      createdAt: user.createdAt,
+      lastLogin: user.lastLogin,
+    });
+  }
+  return results;
+}
+
+// ─── Auth Middleware ───────────────────────────────────────────
+
+const PUBLIC_ROUTES = new Set([
+  '/hq/auth/login',
+  '/hq/auth/register',
+  '/hq/onboarding/chat',
+  '/hq/onboarding/status',
+  '/hq/subscription/tier',
+]);
+
+export function hqAuthMiddleware(pathname, req) {
+  if (PUBLIC_ROUTES.has(pathname)) return { authorized: true, tenantId: null };
+
+  const authHeader = req.headers['authorization'] || req.headers['x-api-key'] || '';
+  const token = authHeader.replace(/^Bearer\s+/i, '').trim();
+
+  if (!token) {
+    return { authorized: false, error: 'Authentication required. Use Authorization: Bearer <token> header.', tenantId: null };
+  }
+
+  if (token.startsWith('hq_')) {
+    const session = validateSession(token);
+    if (session.valid) {
+      return {
+        authorized: true,
+        tenantId: session.tenantId,
+        role: session.role,
+        userId: session.userId,
+        email: session.email,
+      };
+    }
+    return { authorized: false, error: 'Session expired or invalid.', tenantId: null };
+  }
+
+  const result = validateApiKey(token);
+  if (!result.valid) return { authorized: false, error: 'Invalid API key or session token.', tenantId: null };
+  return { authorized: true, tenantId: result.tenantId };
+}