kern0-cli 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# Kern0 — Enterprise Recovery Control Plane
+
+Next.js 16 + Firebase (Firestore + Auth) control plane for identity
+resilience. Multi-customer, multi-environment monitoring with a guided
+onboarding flow, node pre-approval and a full audit log.
+
+Migrated from the single-page Rust consoles (`C:\src\r1_sidecar` UI +
+`C:\src\sending` architecture). See `docs/ARCHITECTURE.md` for the mapping and
+`docs/FIREBASE.md` for the Firestore collection map + console checklist.
+
+## What’s in milestone 1
+
+- **Google sign-in** (Firebase Auth). The first account on an empty platform
+  becomes **Global Admin**; later self-service sign-ups default to
+  **Read Only** until an admin grants more. Roles today: `global_admin`,
+  `full_admin`, `read_only`.
+- **Guided onboarding** — create a customer by **DNS domain** + **forest
+  GUID(s)**, one environment per forest, optionally pre-approve the first node.
+- **Environments + switcher** — monitor many ADFR/DSP environments at once and
+  switch instantly (top-bar selector; remembered per operator).
+- **Nodes & Pre-approval** — pre-approve iroh nodes with label + approved
+  forests (blank = unrestricted), enable/disable, edit forests, remove —
+  mirroring the r1 admin console.
+- **Audit log** — every privileged action is recorded (metadata only, never
+  secret values).
+- Server-authorised API (httpOnly session cookie). The browser never talks to
+  Firestore directly.
+
+## Get started
+
+```bash
+npm install
+cp .env.example .env.local   # fill in service account (see below)
+npm run firebase:init        # materialise settings + audit (idempotent)
+npm run dev                  # http://localhost:3000
+```
+
+`.env.local` is git-ignored. The Firebase Admin SDK needs a service account:
+
+1. **Option A (dev):** keep
+   `kern0-8aed1-firebase-adminsdk-fbsvc-11bf7104e0.json` in the repo root
+   (already `.gitignore`d) — it is picked up automatically.
+2. **Option B (env):** set `FIREBASE_SERVICE_ACCOUNT_BASE64` (or
+   `FIREBASE_SERVICE_ACCOUNT_PATH` / `GOOGLE_APPLICATION_CREDENTIALS`).
+3. The client config (`NEXT_PUBLIC_FIREBASE_*`) is **public** — defaults for
+   the `kern0-8aed1` project are already in `lib/client/firebase.ts`.
+4. Set `KERN0_PSK_ENCRYPTION_KEY` (64 hex chars) in `.env.local` — **required
+   for passkeys**: the second-factor login cookie and destructive-action
+   step-up tokens are signed with it. Use the shared team value (same as
+   production) if you touch PSK-encrypted data; `openssl rand -hex 32` is
+   fine for UI-only dev. Restart `npm run dev` after changing it.
+
+> Security: the service-account JSON must never be committed. It is covered by
+> `.gitignore` (`*-firebase-adminsdk-*.json`, `*service-account*.json`, etc.)
+> and `git status` is verified before every push.
+
+## Staging environment
+
+A second App Hosting backend (`staging`, us-east4, same project
+`kern0-8aed1`) serves the `staging` git branch for pre-merge testing:
+
+- **URLs:** https://staging.kernzero.com (custom domain) and
+  https://staging--kern0-8aed1.us-east4.hosted.app (default).
+- **Flow:** push to the `staging` branch → App Hosting auto-builds and rolls
+  out. Prod (`kern0` backend, https://kernzero.com) deploys only from
+  `master`. Merge `master` into `staging` regularly so it stays current.
+- **Passkeys:** staging uses the same rp_id as prod (`kernzero.com`) via
+  backend env overrides, so passkeys enrolled on prod work on staging without
+  re-enrollment. Overrides in play: `KERN0_WEBAUTHN_RP_ID=kernzero.com`,
+  `KERN0_WEBAUTHN_ORIGIN=https://staging.kernzero.com,https://staging--kern0-8aed1.us-east4.hosted.app`.
+- **Env-change gotcha:** App Hosting bakes env vars into the build artifact —
+  changing backend env overrides requires a **new build + rollout**;
+  redeploying an existing build keeps the old values.
+- **Shared data warning:** staging shares prod's Firestore, Auth users, and
+  secrets (same Firebase project). Destructive actions on staging delete real
+  data — passkey step-up gates apply, but test with care.
+- **DNS:** `staging.kernzero.com` needs an A record (`35.219.200.193`) and a
+  Firebase ownership TXT record in the kernzero.com zone (GoDaddy).
+
+Console entry points (read-only roles `roles/logging.viewer` +
+`roles/firebase.viewer` cover logs and backend visibility for both backends):
+
+- Logs: https://console.cloud.google.com/logs/query?project=kern0-8aed1
+  (filter Cloud Run service `kern0` = prod, `staging` = staging;
+  `logName="projects/kern0-8aed1/logs/cloudbuild"` for build logs)
+- App Hosting: https://console.firebase.google.com/project/kern0-8aed1/apphosting
+
+## Scripts
+
+```bash
+npm run dev          # next dev (Turbopack)
+npm run build        # next build
+npm run lint         # eslint
+npm run typecheck    # tsc --noEmit
+npm run firebase:init# Firestore bootstrap
+```
+
+## Layout
+
+```
+app/                  # App Router: pages + /api route handlers
+app/api/…             # session, me, customers, onboard, environments, nodes, audit
+components/           # auth provider, app shell, wizard, UI primitives
+lib/firebase/admin.ts # Firebase Admin init (server)
+lib/server/*          # auth guards, audit, users, onboarding, serializers
+lib/client/*          # Firebase web + fetch helper
+lib/validation.ts     # forest GUID / domain / node-id rules (mirrors Rust)
+scripts/bootstrap.mjs # Firestore bootstrap
+docs/                 # MIGRATION.md (product/migration plan), FIREBASE.md, ARCHITECTURE.md
+```

package/README.npm.md

@@ -0,0 +1,137 @@
+# KernZero CLI
+
+Command-line interface for managing recovery control planes and monitoring environments.
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g @kernzero/cli
+```
+
+### Authenticate
+
+```bash
+kern0 login
+```
+
+This opens your browser for device flow authentication with passkeys. No passwords needed.
+
+### Use
+
+```bash
+# Check who you are
+kern0 whoami
+
+# List organizations
+kern0 org list
+
+# Select an organization
+kern0 org select <org-id>
+
+# View environments
+kern0 environments list
+
+# Manage tokens
+kern0 tokens list
+kern0 tokens create "my-token"
+```
+
+## Features
+
+✅ **Device Flow Authentication** - Secure OAuth 2.0 with passkeys  
+✅ **Multi-tenant Support** - Manage multiple organizations and environments  
+✅ **Token Management** - Create and revoke API tokens  
+✅ **Environment Monitoring** - View status across all monitored systems  
+✅ **Zero Trust** - Device-bound authentication  
+✅ **MCP Integration** - Connect to AI assistants via Model Context Protocol  
+
+## Documentation
+
+Full documentation available at: https://github.com/santorres/kern0/blob/main/docs/CLI.md
+
+## Commands
+
+### Authentication
+```bash
+kern0 login                    # Authenticate with device flow
+kern0 logout                   # Logout and clear token
+kern0 whoami                   # View current context
+```
+
+### Organizations
+```bash
+kern0 org list                 # List accessible organizations
+kern0 org select <id>          # Select an organization
+kern0 org info                 # View organization details
+kern0 org create <name>        # Create new organization
+```
+
+### Environments
+```bash
+kern0 environments list        # List all environments
+kern0 environments info <id>   # View environment details
+```
+
+### Tokens
+```bash
+kern0 tokens list              # List API tokens
+kern0 tokens create <name>     # Create new token
+kern0 tokens revoke <id>       # Revoke a token
+```
+
+### MCP Server
+```bash
+kern0-mcp                      # Start MCP server for AI integration
+```
+
+## Environment Variables
+
+```bash
+# Required
+KERN0_API_URL=https://staging.kernzero.com
+
+# Optional (auto-set after login)
+KERN0_TOKEN=...
+```
+
+## Troubleshooting
+
+**"Command not found"**
+```bash
+# Ensure npm global bin is in PATH
+npm config get prefix
+export PATH="$(npm config get prefix)/bin:$PATH"
+```
+
+**"Not authenticated"**
+```bash
+# Re-authenticate
+kern0 login
+```
+
+**"User does not have access to this organization"**
+```bash
+# View available organizations
+kern0 org list
+
+# Use a valid org ID
+kern0 org select <valid-id>
+```
+
+## Support
+
+For issues or questions:
+1. Check `kern0 --help`
+2. View logs: `~/.kern0/logs`
+3. GitHub Issues: https://github.com/santorres/kern0/issues
+
+## License
+
+MIT
+
+---
+
+**Version:** 0.1.0  
+**Node.js:** 18+

package/bin/kern0

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * KernZero CLI - Entry Point
+ * Dynamically imports and runs the CLI
+ */
+
+import { execSync } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(__dirname, '..');
+
+try {
+  // Use tsx to run TypeScript CLI
+  const args = process.argv.slice(2);
+  execSync(`npx tsx ${path.join(projectRoot, 'lib/cli/index.ts')} ${args.join(' ')}`, {
+    stdio: 'inherit',
+    cwd: projectRoot
+  });
+} catch (error) {
+  process.exit(1);
+}

package/bin/kern0-mcp

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../lib/mcp/server.js";

package/lib/cli/api.ts

@@ -0,0 +1,208 @@
+import { loadToken, loadConfig } from "./config";
+
+export interface ApiErrorResponse {
+  error: string;
+  success: false;
+  timestamp: number;
+}
+
+export interface ApiSuccessResponse<T> {
+  data?: T;
+  success: true;
+  timestamp: number;
+}
+
+export type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;
+
+export async function apiCall<T>(
+  method: "GET" | "POST" | "PUT" | "DELETE",
+  endpoint: string,
+  body?: unknown,
+): Promise<T> {
+  const config = loadConfig();
+  const token = loadToken();
+
+  if (!token) {
+    throw new Error("Not authenticated. Run `kern0 login` first.");
+  }
+
+  const url = new URL(endpoint, config.api_url).href;
+  const headers: Record<string, string> = {
+    "Authorization": `Bearer ${token}`,
+    "Content-Type": "application/json",
+  };
+
+  const options: RequestInit = {
+    method,
+    headers,
+  };
+
+  if (body) {
+    options.body = JSON.stringify(body);
+  }
+
+  try {
+    const response = await fetch(url, options);
+    const data = (await response.json()) as ApiResponse<T>;
+
+    if (!data.success) {
+      const errorMsg = (data as ApiErrorResponse).error || "API error";
+      throw new Error(errorMsg);
+    }
+
+    return ((data as ApiSuccessResponse<T>).data || {}) as T;
+  } catch (error) {
+    if (error instanceof Error) {
+      throw error;
+    }
+    throw new Error(`API call failed: ${error}`);
+  }
+}
+
+// Organization API
+
+export interface Organization {
+  id: string;
+  name: string;
+  type: "direct" | "msp";
+  createdAt: number;
+}
+
+export async function listOrganizations(): Promise<Organization[]> {
+  const response = await apiCall<{ organizations: Organization[] }>(
+    "GET",
+    "/api/v1/orgs",
+  );
+  return response.organizations || [];
+}
+
+export async function getOrganization(orgId: string): Promise<Organization> {
+  const response = await apiCall<{ organization: Organization }>("GET", `/api/v1/orgs/${orgId}`);
+  return response.organization;
+}
+
+export async function createOrganization(
+  name: string,
+  type: "direct" | "msp",
+): Promise<Organization> {
+  const response = await apiCall<{ organization: Organization }>("POST", "/api/v1/orgs", { name, type });
+  return response.organization;
+}
+
+// Members API
+
+export interface Member {
+  userId: string;
+  email: string;
+  role: "org:admin" | "org:member";
+  customerIds: string[];
+  grantedAt: number;
+}
+
+export async function listMembers(orgId: string): Promise<Member[]> {
+  const response = await apiCall<{ members: Member[] }>(
+    "GET",
+    `/api/v1/orgs/${orgId}/members`,
+  );
+  return response.members || [];
+}
+
+export async function addMember(
+  orgId: string,
+  userId: string,
+  role: "org:admin" | "org:member",
+  customerIds?: string[],
+): Promise<Member> {
+  return apiCall<Member>("POST", `/api/v1/orgs/${orgId}/members`, {
+    userId,
+    role,
+    customerIds,
+  });
+}
+
+// Customers API
+
+export interface Customer {
+  id: string;
+  name: string;
+  organizationId: string;
+  createdAt: number;
+}
+
+export async function listCustomers(orgId: string): Promise<Customer[]> {
+  const response = await apiCall<{ customers: Customer[] }>(
+    "GET",
+    `/api/v1/orgs/${orgId}/customers`,
+  );
+  return response.customers || [];
+}
+
+// Tokens API
+
+export interface Token {
+  id: string;
+  name: string;
+  scopes: string[];
+  createdAt: number;
+  expiresAt: number;
+  lastUsedAt?: number;
+  revokedAt?: number;
+}
+
+export interface TokenResponse extends Token {
+  token: string; // Only returned on creation
+}
+
+export async function listTokens(orgId: string): Promise<Token[]> {
+  const response = await apiCall<{ tokens: Token[] }>(
+    "GET",
+    `/api/v1/orgs/${orgId}/tokens`,
+  );
+  return response.tokens || [];
+}
+
+export async function createToken(
+  orgId: string,
+  name: string,
+  scopes?: string[],
+  customerIds?: string[],
+  expiresIn?: number,
+): Promise<TokenResponse> {
+  return apiCall<TokenResponse>("POST", `/api/v1/orgs/${orgId}/tokens`, {
+    name,
+    scopes,
+    customerIds,
+    expiresIn,
+  });
+}
+
+export async function revokeToken(orgId: string, tokenId: string): Promise<void> {
+  await apiCall("DELETE", `/api/v1/orgs/${orgId}/tokens/${tokenId}`);
+}
+
+// Audit API
+
+export interface AuditLog {
+  id: string;
+  timestamp: number;
+  userId: string;
+  action: string;
+  resource: string;
+  method: string;
+  status: number;
+  ipAddress?: string;
+}
+
+export async function listAuditLogs(
+  orgId: string,
+  limit?: number,
+): Promise<AuditLog[]> {
+  const params = new URLSearchParams();
+  if (limit) params.append("limit", limit.toString());
+
+  const response = await apiCall<{ logs: AuditLog[] }>(
+    "GET",
+    `/api/v1/orgs/${orgId}/audit-logs?${params.toString()}`,
+  );
+  return response.logs || [];
+}

package/lib/cli/auth-flow.ts

@@ -0,0 +1,155 @@
+import { loadConfig, saveToken, setAuth, setUser, setOrganizations } from "./config";
+
+export interface DeviceCodeResponse {
+  device_code: string;
+  user_code: string;
+  verification_uri: string;
+  expires_in: number;
+}
+
+export interface DeviceTokenResponse {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+  user?: { id: string; email: string };
+}
+
+export interface UserInfo {
+  id: string;
+  email: string;
+}
+
+const POLL_INTERVAL = 2000; // 2 seconds
+const POLL_TIMEOUT = 600000; // 10 minutes (600 seconds from device code)
+
+export async function initializeDeviceFlow(): Promise<DeviceCodeResponse> {
+  const config = loadConfig();
+
+  const response = await fetch(
+    new URL("/api/v1/auth/device-code", config.api_url).href,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+    },
+  );
+
+  if (!response.ok) {
+    throw new Error("Failed to initialize device flow");
+  }
+
+  return response.json() as Promise<DeviceCodeResponse>;
+}
+
+export async function pollForToken(
+  deviceCode: string,
+  onProgress?: (message: string) => void,
+): Promise<DeviceTokenResponse> {
+  const config = loadConfig();
+  const startTime = Date.now();
+  const timeout = POLL_TIMEOUT;
+
+  return new Promise((resolve, reject) => {
+    const pollInterval = setInterval(async () => {
+      const elapsed = Date.now() - startTime;
+
+      if (elapsed > timeout) {
+        clearInterval(pollInterval);
+        reject(new Error("Device flow timeout - approval expired"));
+        return;
+      }
+
+      try {
+        const response = await fetch(
+          new URL("/api/v1/auth/device-token", config.api_url).href,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ device_code: deviceCode }),
+          },
+        );
+
+        if (!response.ok) {
+          if (response.status === 400) {
+            // Authorization pending, keep polling
+            return;
+          }
+          throw new Error("Failed to exchange device code");
+        }
+
+        const data = (await response.json()) as DeviceTokenResponse;
+        clearInterval(pollInterval);
+        resolve(data);
+      } catch (error) {
+        if (error instanceof Error && error.message.includes("Failed")) {
+          clearInterval(pollInterval);
+          reject(error);
+        }
+        // Other errors (network, etc) - keep polling
+      }
+    }, POLL_INTERVAL);
+  });
+}
+
+export async function getUserInfo(token: string): Promise<UserInfo> {
+  // For CLI, derive user info from token data
+  // In production, this would call /api/me with token auth
+  // For now, return placeholder - will be set from API responses
+  return {
+    id: "cli-user",
+    email: "user@example.com",
+  };
+}
+
+export async function getOrganizations(token: string): Promise<
+  Array<{ id: string; name: string }>
+> {
+  const config = loadConfig();
+
+  const response = await fetch(
+    new URL("/api/v1/orgs", config.api_url).href,
+    {
+      headers: { Authorization: `Bearer ${token}` },
+    },
+  );
+
+  if (!response.ok) {
+    throw new Error("Failed to fetch organizations");
+  }
+
+  const data = await response.json() as any;
+  return (data.organizations || []).map((org: any) => ({
+    id: org.id,
+    name: org.name,
+  }));
+}
+
+export async function completeLogin(
+  token: string,
+  expiresIn: number,
+  userFromToken?: { id: string; email: string },
+): Promise<{ user: UserInfo; organizations: Array<{ id: string; name: string }> }> {
+  // Get user info (from token if available, otherwise fallback)
+  const user = userFromToken ? { id: userFromToken.id, email: userFromToken.email } : await getUserInfo(token);
+
+  // Get organizations
+  const organizations = await getOrganizations(token);
+
+  // Save credentials
+  saveToken(token);
+
+  // Save auth state
+  const expiresAt = Date.now() + expiresIn * 1000;
+  setAuth({
+    device_token: token,
+    expires_at: expiresAt,
+    token_type: "device",
+  });
+
+  // Save user
+  setUser(user);
+
+  // Save organizations
+  setOrganizations(organizations);
+
+  return { user, organizations };
+}