habi-agent 0.1.0

package/src/cloud.ts

@@ -0,0 +1,165 @@
+/**
+ * HABI Cloud Sync
+ * Authenticates via HABI_KEY, registers device, and sends heartbeats.
+ */
+
+import * as https from 'https';
+import * as os from 'os';
+
+const HABI_API = process.env.HABI_API_URL ||
+  'https://dokcixjitwihtbdlkbdb.supabase.co/functions/v1';
+
+const HABI_KEY = process.env.HABI_KEY || '';
+const OWNER_EMAIL = process.env.HABI_OWNER_EMAIL || '';
+
+interface RegisterResponse {
+  ok: boolean;
+  deviceId?: string;
+  ownerId?: string;
+  sessionToken?: string;
+  sessionTokenExpiresAt?: string;
+  error?: string;
+}
+
+interface HeartbeatResponse {
+  ok: boolean;
+  sessionToken?: string;
+  sessionTokenExpiresAt?: string;
+  tokenRotated?: boolean;
+  pendingJobs?: Array<{ id: string; payload: Record<string, unknown>; payload_hash: string }>;
+  error?: string;
+}
+
+interface JobResultPayload {
+  jobId: string;
+  deviceId: string;
+  sessionToken: string;
+  status: 'COMPLETED' | 'FAILED';
+  result?: Record<string, unknown>;
+  error?: string;
+  durationMs?: number;
+}
+
+function post<T>(path: string, body: Record<string, unknown>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const bodyStr = JSON.stringify(body);
+    const url = new URL(`${HABI_API}/${path}`);
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'Content-Length': String(Buffer.byteLength(bodyStr)),
+    };
+
+    // Pass HABI_KEY in header if set
+    if (HABI_KEY) {
+      headers['x-habi-key'] = HABI_KEY;
+    }
+
+    const options: https.RequestOptions = {
+      hostname: url.hostname,
+      port: 443,
+      path: url.pathname,
+      method: 'POST',
+      headers,
+    };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.on('data', (chunk: Buffer) => data += chunk.toString());
+      res.on('end', () => {
+        try { resolve(JSON.parse(data) as T); }
+        catch { reject(new Error(`Parse error: ${data.slice(0, 100)}`)); }
+      });
+    });
+
+    req.on('error', reject);
+    req.setTimeout(10000, () => { req.destroy(); reject(new Error('Cloud sync timeout')); });
+    req.write(bodyStr);
+    req.end();
+  });
+}
+
+export interface CloudState {
+  deviceId: string;
+  ownerId: string;
+  sessionToken: string;
+  sessionTokenExpiresAt: string;
+  registered: boolean;
+}
+
+export async function registerDevice(params: {
+  friendlyName: string;
+  hardwareFingerprint: string;
+  fingerprintType: 'mac' | 'ipv6_link_local';
+  agentVersion?: string;
+  osPlatform?: string;
+}): Promise<CloudState | null> {
+
+  if (!HABI_KEY && !OWNER_EMAIL) {
+    console.warn('[HABI] No HABI_KEY or HABI_OWNER_EMAIL set — running offline.');
+    return null;
+  }
+
+  try {
+    const body: Record<string, unknown> = { ...params };
+    if (HABI_KEY)     body.habiKey = HABI_KEY;
+    if (OWNER_EMAIL)  body.ownerEmail = OWNER_EMAIL;
+
+    const res = await post<RegisterResponse>('device-register', body);
+
+    if (!res.ok || !res.deviceId) {
+      console.error(`[HABI] Registration failed: ${res.error}`);
+      return null;
+    }
+
+    console.log(`[HABI] ✓ Device registered: ${params.friendlyName} (${res.deviceId.slice(0, 8)}...)`);
+
+    return {
+      deviceId: res.deviceId,
+      ownerId: res.ownerId!,
+      sessionToken: res.sessionToken!,
+      sessionTokenExpiresAt: res.sessionTokenExpiresAt!,
+      registered: true,
+    };
+  } catch (err) {
+    console.error(`[HABI] Registration error: ${err}`);
+    return null;
+  }
+}
+
+export async function sendHeartbeat(params: {
+  deviceId: string;
+  sessionToken: string;
+  hardwareFingerprint: string;
+}): Promise<{ sessionToken: string; pendingJobs: HeartbeatResponse['pendingJobs'] } | null> {
+  try {
+    const body: Record<string, unknown> = { ...params };
+    if (HABI_KEY) body.habiKey = HABI_KEY;
+
+    const res = await post<HeartbeatResponse>('heartbeat', body);
+
+    if (!res.ok) {
+      console.error(`[HABI] Heartbeat failed: ${res.error}`);
+      return null;
+    }
+
+    return {
+      sessionToken: res.sessionToken || params.sessionToken,
+      pendingJobs: res.pendingJobs || [],
+    };
+  } catch (err) {
+    console.error(`[HABI] Heartbeat error: ${err}`);
+    return null;
+  }
+}
+
+export async function reportJobResult(payload: JobResultPayload): Promise<void> {
+  try {
+    const body = { ...payload as unknown as Record<string, unknown> };
+    if (HABI_KEY) body.habiKey = HABI_KEY;
+    await post<{ ok: boolean }>('job-result', body);
+    console.log(`[HABI] Job result reported: ${payload.jobId} → ${payload.status}`);
+  } catch (err) {
+    console.error(`[HABI] Job result error: ${err}`);
+  }
+}

package/src/context.ts

@@ -0,0 +1,186 @@
+/**
+ * HABI Project Context File Loader
+ *
+ * The Project Context File is the source of truth for what is authorized
+ * on this machine for this project. It lives OUTSIDE version control.
+ *
+ * The SHA-256 hash of the file is computed on load and included in every
+ * session fingerprint. Tampering with the file invalidates active sessions.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+
+export interface AllowedOperations {
+  paths?: string[];
+  cloudAccounts?: string[];
+  databases?: string[];
+  repos?: string[];
+  commands?: string[];
+}
+
+export interface ProjectContext {
+  project: string;
+  version: string;
+  owner: string;
+  allowedMachines: string[];          // MAC or IPv6 link-local values
+  allowedOperations: AllowedOperations;
+  deniedOperations: string[];         // string patterns — rejected on match
+  contextHash: string;                // SHA-256 of file contents (self-referential, set on write)
+}
+
+export interface LoadedContext {
+  context: ProjectContext;
+  contextHash: string;                // recomputed on load — verified against stored
+  filePath: string;
+}
+
+const CONTEXT_FILE_NAMES = [
+  'habi-context.json',
+  '.habi-context.json',
+  'habi.context.json',
+];
+
+/**
+ * Locates the context file by walking up from cwd.
+ * Searches: cwd → parent → grandparent → $HOME
+ */
+export function findContextFile(startDir: string = process.cwd()): string | null {
+  let dir = path.resolve(startDir);
+  const home = os_homedir();
+
+  while (true) {
+    for (const name of CONTEXT_FILE_NAMES) {
+      const candidate = path.join(dir, name);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;       // filesystem root
+    if (dir === home) break;         // don't go above home
+    dir = parent;
+  }
+  return null;
+}
+
+function os_homedir(): string {
+  return process.env.HOME || process.env.USERPROFILE || '/';
+}
+
+/**
+ * Loads and validates a Project Context File.
+ *
+ * Validation:
+ * 1. File exists and is valid JSON
+ * 2. Required fields are present
+ * 3. Recomputed hash matches stored contextHash
+ *    (if mismatch → file was tampered with → reject)
+ */
+export function loadContext(filePath: string): LoadedContext {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`HABI: Context file not found: ${filePath}`);
+  }
+
+  const raw = fs.readFileSync(filePath, 'utf8');
+
+  let context: ProjectContext;
+  try {
+    context = JSON.parse(raw) as ProjectContext;
+  } catch {
+    throw new Error(`HABI: Context file is not valid JSON: ${filePath}`);
+  }
+
+  // Validate required fields
+  const required = ['project', 'version', 'owner', 'allowedMachines', 'allowedOperations', 'deniedOperations'];
+  for (const field of required) {
+    if (!(field in context)) {
+      throw new Error(`HABI: Context file missing required field: ${field}`);
+    }
+  }
+
+  // Compute hash of file contents excluding the contextHash field itself
+  const { contextHash: _stored, ...rest } = context;
+  const computedHash = crypto
+    .createHash('sha256')
+    .update(JSON.stringify(rest, null, 2))
+    .digest('hex');
+
+  // If contextHash is set, verify it matches
+  if (_stored && _stored !== computedHash) {
+    throw new Error(
+      `HABI: Context file integrity check FAILED.\n` +
+      `  Stored hash:   ${_stored}\n` +
+      `  Computed hash: ${computedHash}\n` +
+      `  File may have been tampered with: ${filePath}`
+    );
+  }
+
+  return {
+    context,
+    contextHash: computedHash,
+    filePath,
+  };
+}
+
+/**
+ * Checks whether a proposed operation is authorized under the loaded context.
+ *
+ * Returns: { allowed: true } or { allowed: false, reason: string }
+ */
+export function assertOperation(
+  operation: string,
+  context: ProjectContext
+): { allowed: boolean; reason?: string } {
+
+  const opLower = operation.toLowerCase();
+
+  // ── Check denied list first (deny wins) ────────────────────────────────────
+  for (const denied of context.deniedOperations) {
+    if (opLower.includes(denied.toLowerCase())) {
+      return {
+        allowed: false,
+        reason: `Operation matches denied pattern: "${denied}"`,
+      };
+    }
+  }
+
+  // ── Check allowed paths ─────────────────────────────────────────────────────
+  const ops = context.allowedOperations;
+
+  if (ops.commands && ops.commands.length > 0) {
+    const commandAllowed = ops.commands.some(cmd =>
+      opLower.startsWith(cmd.toLowerCase())
+    );
+    if (!commandAllowed) {
+      return {
+        allowed: false,
+        reason: `Operation not in allowedOperations.commands list`,
+      };
+    }
+  }
+
+  return { allowed: true };
+}
+
+/**
+ * Checks whether this machine's hardware ID is authorized in the context file.
+ */
+export function assertMachineAuthorized(
+  hardwareId: string,
+  context: ProjectContext
+): { allowed: boolean; reason?: string } {
+  const allowed = context.allowedMachines.some(
+    m => m.toUpperCase() === hardwareId.toUpperCase()
+  );
+
+  if (!allowed) {
+    return {
+      allowed: false,
+      reason:
+        `Hardware ID ${hardwareId} is not in allowedMachines list. ` +
+        `Authorized machines: ${context.allowedMachines.join(', ')}`,
+    };
+  }
+
+  return { allowed: true };
+}

package/src/hardware.ts

@@ -0,0 +1,114 @@
+/**
+ * HABI Hardware Identity Reader
+ * Reads MAC address (physical) or IPv6 link-local (container/VM)
+ * This is the foundation primitive of the entire HABI system.
+ *
+ * On physical machines: returns MAC via os.networkInterfaces()
+ * On containers/VMs:    returns IPv6 link-local (fe80::/10) — auto-generated
+ *                       per virtual NIC, stable for container lifetime,
+ *                       non-routable externally
+ */
+
+import * as os from 'os';
+import * as crypto from 'crypto';
+
+export type FingerprintType = 'mac' | 'ipv6_link_local';
+
+export interface HardwareIdentity {
+  fingerprint: string;
+  type: FingerprintType;
+  iface: string;
+  platform: string;
+  hostname: string;
+}
+
+/**
+ * Reads network interfaces and returns the primary hardware identifier.
+ * Priority: real MAC → IPv6 link-local → error
+ *
+ * Excludes loopback and virtual/docker interfaces.
+ * Returns the most stable, unique identifier available on this machine.
+ */
+export function readHardwareIdentity(): HardwareIdentity {
+  const ifaces = os.networkInterfaces();
+  const platform = os.platform();
+  const hostname = os.hostname();
+
+  // ── Pass 1: Find a real MAC address ────────────────────────────────────────
+  // Exclude loopback (lo, lo0) and known virtual prefixes
+  const VIRTUAL_PREFIXES = ['docker', 'br-', 'veth', 'virbr', 'vmnet', 'vbox'];
+
+  for (const [name, addrs] of Object.entries(ifaces)) {
+    if (!addrs) continue;
+
+    // Skip loopback
+    if (addrs.some(a => a.internal)) continue;
+
+    // Skip known virtual interfaces
+    const ifaceLower = name.toLowerCase();
+    if (VIRTUAL_PREFIXES.some(prefix => ifaceLower.startsWith(prefix))) continue;
+
+    for (const addr of addrs) {
+      const mac = addr.mac;
+      // Validate: real MAC is not all-zeros, not broadcast
+      if (mac && mac !== '00:00:00:00:00:00' && mac !== 'ff:ff:ff:ff:ff:ff') {
+        return {
+          fingerprint: mac.toUpperCase(),
+          type: 'mac',
+          iface: name,
+          platform,
+          hostname,
+        };
+      }
+    }
+  }
+
+  // ── Pass 2: IPv6 link-local (fe80::/10) — container/VM fallback ───────────
+  for (const [name, addrs] of Object.entries(ifaces)) {
+    if (!addrs) continue;
+    if (addrs.some(a => a.internal)) continue;
+
+    for (const addr of addrs) {
+      if (addr.family === 'IPv6' && addr.address.toLowerCase().startsWith('fe80')) {
+        return {
+          fingerprint: addr.address.toLowerCase(),
+          type: 'ipv6_link_local',
+          iface: name,
+          platform,
+          hostname,
+        };
+      }
+    }
+  }
+
+  // ── Fail loudly — never silently return a fake identity ───────────────────
+  throw new Error(
+    'HABI: No stable hardware identifier found. ' +
+    'Physical machines require a non-virtual network interface with a MAC address. ' +
+    'Containers require an IPv6 link-local address (fe80::/10).'
+  );
+}
+
+/**
+ * Generates a session fingerprint from hardware identity + context hash + timestamp.
+ * This fingerprint is signed into every audit log entry.
+ *
+ * fingerprint = SHA-256(hardware_id + ":" + context_hash + ":" + timestamp_ms)
+ */
+export function generateSessionFingerprint(
+  hardwareId: string,
+  contextHash: string,
+  timestampMs: number = Date.now()
+): string {
+  return crypto
+    .createHash('sha256')
+    .update(`${hardwareId}:${contextHash}:${timestampMs}`)
+    .digest('hex');
+}
+
+/**
+ * Computes SHA-256 of arbitrary input — used for operation hashing in audit log.
+ */
+export function sha256(input: string): string {
+  return crypto.createHash('sha256').update(input).digest('hex');
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { HabiLocalServer } from './server';
+export { readHardwareIdentity, generateSessionFingerprint, sha256 } from './hardware';
+export { findContextFile, loadContext, assertOperation, assertMachineAuthorized } from './context';
+export type { HardwareIdentity, FingerprintType } from './hardware';
+export type { ProjectContext, LoadedContext, AllowedOperations } from './context';