@mnemom/mnemom 0.7.0

package/dist/lib/api.js

@@ -0,0 +1,207 @@
+import { getApiUrl } from "./config.js";
+import { resolveAuth } from "./auth.js";
+export const API_BASE = getApiUrl();
+/** Sanitize file-sourced data before use in outbound HTTP requests. */
+function sanitizeForHttp(data) {
+    return String(data).trim();
+}
+/** Validate a URL before use in HTTP requests to prevent injection. */
+function validateUrl(url) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new Error(`Invalid URL protocol: ${parsed.protocol}`);
+    }
+    return parsed.href;
+}
+async function fetchApi(endpoint) {
+    const url = validateUrl(`${API_BASE}${endpoint}`);
+    const response = await fetch(url);
+    if (!response.ok) {
+        const error = (await response.json().catch(() => ({
+            error: "unknown",
+            message: response.statusText,
+        })));
+        throw new Error(error.message || `API request failed: ${response.status}`);
+    }
+    return response.json();
+}
+export async function postApi(endpoint, body) {
+    const url = validateUrl(`${API_BASE}${endpoint}`);
+    const cred = await resolveAuth();
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    if (cred.type === "jwt") {
+        headers["Authorization"] = `Bearer ${cred.token}`;
+    }
+    else if (cred.type === "api-key") {
+        headers["X-Mnemom-Api-Key"] = cred.key;
+    }
+    const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const error = (await response.json().catch(() => ({
+            error: "unknown",
+            message: `HTTP ${response.status}`,
+        })));
+        const msg = "message" in error ? error.message : JSON.stringify(error);
+        // Preserve conflict_agent_id in the error message for 409 handling upstream
+        if (response.status === 409 && "conflict_agent_id" in error) {
+            throw new Error(`409: ${msg} (conflict: ${error.conflict_agent_id})`);
+        }
+        throw new Error(`${response.status}: ${msg}`);
+    }
+    return response.json();
+}
+export async function verifyBinding(agentId, keyHash) {
+    return postApi(`/v1/agents/${agentId}/verify-binding`, { key_hash: keyHash });
+}
+/**
+ * Build auth headers from the best available credential.
+ * Returns empty object when unauthenticated (read-only calls).
+ */
+async function authHeaders() {
+    const cred = await resolveAuth();
+    switch (cred.type) {
+        case "jwt":
+            return { Authorization: `Bearer ${sanitizeForHttp(cred.token)}` };
+        case "api-key":
+            return { "X-Mnemom-Api-Key": sanitizeForHttp(cred.key) };
+        case "none":
+            return {};
+    }
+}
+export async function getAgent(id) {
+    return fetchApi(`/v1/agents/${id}`);
+}
+export async function listAgents() {
+    const url = validateUrl(`${API_BASE}/v1/agents?limit=100`);
+    const response = await fetch(url, { headers: await authHeaders() });
+    if (!response.ok) {
+        if (response.status === 401) {
+            throw new Error("Not authenticated. Run `smoltbot login` or set MNEMOM_API_KEY.");
+        }
+        const err = await response.json().catch(() => ({ error: "unknown" }));
+        throw new Error(err.message || `Failed to list agents: ${response.status}`);
+    }
+    const data = await response.json();
+    return data.agents ?? [];
+}
+/**
+ * Look up an agent in the authenticated user's account by name.
+ * Tries exact match first, then single partial match.
+ * Throws if multiple agents partially match (ambiguous).
+ * Returns null if no match found.
+ * Note: capped at 100 agents by listAgents().
+ */
+export async function getAgentByName(name) {
+    const agents = await listAgents();
+    const lower = name.toLowerCase();
+    const exact = agents.find(a => a.name?.toLowerCase() === lower);
+    if (exact)
+        return exact;
+    const partials = agents.filter(a => a.name?.toLowerCase().includes(lower));
+    if (partials.length === 1)
+        return partials[0];
+    if (partials.length > 1) {
+        const names = partials.map(a => a.name ?? a.id).join(", ");
+        throw new Error(`Multiple agents match '${name}': ${names}. Use a more specific name.`);
+    }
+    return null;
+}
+export async function getIntegrity(id) {
+    return fetchApi(`/v1/integrity/${id}`);
+}
+export async function getTraces(id, limit = 10) {
+    return fetchApi(`/v1/traces?agent_id=${id}&limit=${limit}`);
+}
+export async function getCard(agentId) {
+    try {
+        return await fetchApi(`/v1/agents/${agentId}/card`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("404") || message.includes("not found")) {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function updateCard(agentId, cardJson) {
+    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/card`);
+    const response = await fetch(url, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json", ...(await authHeaders()) },
+        body: sanitizeForHttp(JSON.stringify({ card_json: cardJson })),
+    });
+    if (!response.ok) {
+        const error = (await response.json().catch(() => ({
+            error: "unknown",
+            message: response.statusText,
+        })));
+        throw new Error(error.message || `Card update failed: ${response.status}`);
+    }
+    return response.json();
+}
+export async function reverifyAgent(agentId) {
+    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/reverify`);
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...(await authHeaders()) },
+    });
+    if (!response.ok) {
+        const error = (await response.json().catch(() => ({
+            error: "unknown",
+            message: response.statusText,
+        })));
+        throw new Error(error.message || `Reverify failed: ${response.status}`);
+    }
+    return response.json();
+}
+export async function getPolicy(agentId) {
+    try {
+        return await fetchApi(`/v1/agents/${agentId}/policy`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("404") || message.includes("not found")) {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function publishPolicy(agentId, policyJson) {
+    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/policy`);
+    const response = await fetch(url, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json", ...(await authHeaders()) },
+        body: sanitizeForHttp(JSON.stringify({ policy_json: policyJson })),
+    });
+    if (!response.ok) {
+        const error = (await response.json().catch(() => ({
+            error: "unknown",
+            message: response.statusText,
+        })));
+        throw new Error(error.message || `Policy publish failed: ${response.status}`);
+    }
+    return response.json();
+}
+export async function testPolicyHistorical(agentId, policyJson, limit = 50) {
+    const url = validateUrl(`${API_BASE}/v1/policies/evaluate/historical`);
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...(await authHeaders()) },
+        body: sanitizeForHttp(JSON.stringify({ agent_id: agentId, policy_json: policyJson, limit })),
+    });
+    if (!response.ok) {
+        const error = (await response.json().catch(() => ({
+            error: "unknown",
+            message: response.statusText,
+        })));
+        throw new Error(error.message || `Historical evaluation failed: ${response.status}`);
+    }
+    return response.json();
+}

package/dist/lib/auth.d.ts

@@ -0,0 +1,60 @@
+import { type AuthTokens } from "./config.js";
+export type AuthCredential = {
+    type: "jwt";
+    token: string;
+} | {
+    type: "api-key";
+    key: string;
+} | {
+    type: "none";
+};
+/**
+ * Get a valid access token, or null if not authenticated.
+ *
+ * Resolution order:
+ *  1. SMOLTBOT_TOKEN environment variable (CI / non-interactive)
+ *  2. Stored token from config (auto-refreshes if expired)
+ */
+export declare function getAccessToken(): Promise<string | null>;
+/**
+ * Get a valid access token or exit with a helpful message.
+ */
+export declare function requireAccessToken(): Promise<string>;
+/**
+ * Get the Mnemom API key from env var or config.
+ *
+ * Resolution order:
+ *  1. MNEMOM_API_KEY environment variable
+ *  2. Stored mnemomApiKey from config
+ */
+export declare function getMnemomApiKey(): string | null;
+/**
+ * Resolve the best available auth credential.
+ *
+ * Resolution order:
+ *  1. JWT (SMOLTBOT_TOKEN env or stored token with auto-refresh)
+ *  2. API key (MNEMOM_API_KEY env or config mnemomApiKey)
+ *  3. None
+ */
+export declare function resolveAuth(): Promise<AuthCredential>;
+/**
+ * Require authentication (JWT or API key) or exit with a helpful message.
+ */
+export declare function requireAuth(): Promise<AuthCredential & {
+    type: "jwt" | "api-key";
+}>;
+/**
+ * Authenticate via browser-based login flow.
+ *
+ * 1. Start a local HTTP server on a random port
+ * 2. Generate a random `state` nonce for CSRF protection
+ * 3. Open the browser to the API's CLI login page
+ * 4. Wait for the login page to POST tokens back to localhost
+ * 5. Verify state, store tokens, and close the server
+ */
+export declare function loginWithBrowser(): Promise<AuthTokens>;
+/**
+ * Authenticate with email + password via the API auth proxy.
+ * Used by --no-browser fallback.
+ */
+export declare function loginWithPassword(email: string, password: string): Promise<AuthTokens>;

package/dist/lib/auth.js

@@ -0,0 +1,281 @@
+import * as http from "node:http";
+import * as crypto from "node:crypto";
+import { exec } from "node:child_process";
+import { getApiUrl, getWebsiteUrl, getAuthInfo, saveAuthTokens, loadConfig } from "./config.js";
+/** Sanitize file-sourced data before use in outbound HTTP requests. */
+function sanitizeForHttp(data) {
+    return String(data).trim();
+}
+/**
+ * Get a valid access token, or null if not authenticated.
+ *
+ * Resolution order:
+ *  1. SMOLTBOT_TOKEN environment variable (CI / non-interactive)
+ *  2. Stored token from config (auto-refreshes if expired)
+ */
+export async function getAccessToken() {
+    // 1. Env var override (CI / non-interactive)
+    const envToken = process.env.SMOLTBOT_TOKEN;
+    if (envToken)
+        return envToken;
+    // 2. Stored token
+    const auth = getAuthInfo();
+    if (!auth)
+        return null;
+    // Check expiry (with 60s buffer)
+    const now = Math.floor(Date.now() / 1000);
+    if (auth.expiresAt > now + 60) {
+        return auth.accessToken;
+    }
+    // 3. Auto-refresh
+    const refreshed = await refreshAccessToken(auth.refreshToken);
+    if (refreshed)
+        return refreshed.accessToken;
+    return null;
+}
+/**
+ * Get a valid access token or exit with a helpful message.
+ */
+export async function requireAccessToken() {
+    const token = await getAccessToken();
+    if (!token) {
+        console.error("Authentication required. Run `smoltbot login` first.");
+        process.exit(1);
+    }
+    return token;
+}
+/**
+ * Get the Mnemom API key from env var or config.
+ *
+ * Resolution order:
+ *  1. MNEMOM_API_KEY environment variable
+ *  2. Stored mnemomApiKey from config
+ */
+export function getMnemomApiKey() {
+    const envKey = process.env.MNEMOM_API_KEY;
+    if (envKey)
+        return envKey;
+    const config = loadConfig();
+    return config?.mnemomApiKey ?? null;
+}
+/**
+ * Resolve the best available auth credential.
+ *
+ * Resolution order:
+ *  1. JWT (SMOLTBOT_TOKEN env or stored token with auto-refresh)
+ *  2. API key (MNEMOM_API_KEY env or config mnemomApiKey)
+ *  3. None
+ */
+export async function resolveAuth() {
+    const jwt = await getAccessToken();
+    if (jwt)
+        return { type: "jwt", token: jwt };
+    const apiKey = getMnemomApiKey();
+    if (apiKey)
+        return { type: "api-key", key: apiKey };
+    return { type: "none" };
+}
+/**
+ * Require authentication (JWT or API key) or exit with a helpful message.
+ */
+export async function requireAuth() {
+    const cred = await resolveAuth();
+    if (cred.type === "none") {
+        console.error("Authentication required. Run `smoltbot login` or set MNEMOM_API_KEY.");
+        process.exit(1);
+    }
+    return cred;
+}
+/**
+ * Authenticate via browser-based login flow.
+ *
+ * 1. Start a local HTTP server on a random port
+ * 2. Generate a random `state` nonce for CSRF protection
+ * 3. Open the browser to the API's CLI login page
+ * 4. Wait for the login page to POST tokens back to localhost
+ * 5. Verify state, store tokens, and close the server
+ */
+export async function loginWithBrowser() {
+    const state = crypto.randomBytes(16).toString("hex");
+    const { port, tokenPromise, close } = await startCallbackServer(state);
+    const callbackUrl = `http://127.0.0.1:${port}/callback`;
+    const loginUrl = `${getWebsiteUrl()}/login?cli_callback=${encodeURIComponent(callbackUrl)}&state=${encodeURIComponent(state)}`;
+    console.log("Opening browser to authenticate...");
+    console.log(`If the browser doesn't open, visit:\n  ${loginUrl}\n`);
+    openBrowser(loginUrl);
+    console.log("Waiting for authentication...");
+    try {
+        const tokens = await tokenPromise;
+        saveAuthTokens(tokens);
+        return tokens;
+    }
+    finally {
+        close();
+    }
+}
+/**
+ * Start a local HTTP server that listens for the auth callback POST.
+ * Returns the assigned port, a promise that resolves with tokens, and a close function.
+ */
+async function startCallbackServer(expectedState) {
+    let resolveTokens;
+    let rejectTokens;
+    const tokenPromise = new Promise((resolve, reject) => {
+        resolveTokens = resolve;
+        rejectTokens = reject;
+    });
+    const server = http.createServer((req, res) => {
+        // Handle CORS preflight for the POST from the browser page
+        if (req.method === "OPTIONS") {
+            res.writeHead(200, {
+                "Access-Control-Allow-Origin": "*",
+                "Access-Control-Allow-Methods": "POST, OPTIONS",
+                "Access-Control-Allow-Headers": "Content-Type",
+            });
+            res.end();
+            return;
+        }
+        if (req.method !== "POST" || req.url !== "/callback") {
+            res.writeHead(404, { "Content-Type": "text/plain" });
+            res.end("Not found");
+            return;
+        }
+        let body = "";
+        req.on("data", (chunk) => {
+            body += chunk.toString();
+            // Limit body size to prevent abuse
+            if (body.length > 1_000_000) {
+                req.destroy();
+                rejectTokens(new Error("Callback body too large"));
+            }
+        });
+        req.on("end", () => {
+            try {
+                const data = JSON.parse(body);
+                if (data.state !== expectedState) {
+                    res.writeHead(403, {
+                        "Content-Type": "text/html",
+                        "Access-Control-Allow-Origin": "*",
+                    });
+                    res.end("<html><body><h2>Authentication failed</h2><p>State mismatch. Please try again.</p></body></html>");
+                    rejectTokens(new Error("State mismatch — possible CSRF attack"));
+                    return;
+                }
+                const tokens = {
+                    accessToken: data.access_token,
+                    refreshToken: data.refresh_token,
+                    expiresAt: Math.floor(Date.now() / 1000) + data.expires_in,
+                    userId: data.user_id,
+                    email: data.user_email,
+                };
+                res.writeHead(200, {
+                    "Content-Type": "text/html",
+                    "Access-Control-Allow-Origin": "*",
+                });
+                res.end(`<html><body style="font-family:system-ui;text-align:center;padding:60px">
+<h2>Authenticated!</h2>
+<p>You can close this tab and return to the terminal.</p>
+</body></html>`);
+                resolveTokens(tokens);
+            }
+            catch {
+                res.writeHead(400, {
+                    "Content-Type": "text/html",
+                    "Access-Control-Allow-Origin": "*",
+                });
+                res.end("<html><body><h2>Authentication failed</h2><p>Invalid callback data.</p></body></html>");
+                rejectTokens(new Error("Invalid callback data"));
+            }
+        });
+    });
+    // Listen on port 0, wait for the server to be ready before reading the address
+    const port = await new Promise((resolve) => {
+        server.listen(0, "127.0.0.1", () => {
+            resolve(server.address().port);
+        });
+    });
+    // Auto-timeout after 5 minutes
+    const timeout = setTimeout(() => {
+        rejectTokens(new Error("Login timed out. Please try again."));
+        server.close();
+    }, 5 * 60 * 1000);
+    return {
+        port,
+        tokenPromise,
+        close: () => {
+            clearTimeout(timeout);
+            server.close();
+        },
+    };
+}
+/**
+ * Open a URL in the user's default browser.
+ */
+function openBrowser(url) {
+    const cmd = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "start"
+            : "xdg-open";
+    exec(`${cmd} ${JSON.stringify(url)}`);
+}
+/**
+ * Authenticate with email + password via the API auth proxy.
+ * Used by --no-browser fallback.
+ */
+export async function loginWithPassword(email, password) {
+    const url = `${getApiUrl()}/v1/auth/login`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ email, password }),
+    });
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throw new Error(body.error || body.message || "Login failed");
+    }
+    const data = (await res.json());
+    const tokens = {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        expiresAt: Math.floor(Date.now() / 1000) + data.expires_in,
+        userId: data.user.id,
+        email: data.user.email,
+    };
+    saveAuthTokens(tokens);
+    return tokens;
+}
+/**
+ * Refresh an expired access token.
+ * Returns new tokens on success, null on failure.
+ */
+async function refreshAccessToken(refreshToken) {
+    if (!refreshToken || typeof refreshToken !== "string") {
+        return null;
+    }
+    const url = new URL(`${getApiUrl()}/v1/auth/refresh`).href;
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: sanitizeForHttp(JSON.stringify({ refresh_token: String(refreshToken) })),
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        // Preserve existing user info from stored auth
+        const existing = getAuthInfo();
+        const tokens = {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token,
+            expiresAt: Math.floor(Date.now() / 1000) + data.expires_in,
+            userId: existing?.userId ?? "",
+            email: existing?.email ?? "",
+        };
+        saveAuthTokens(tokens);
+        return tokens;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,105 @@
+export declare const CONFIG_DIR: string;
+export declare const CONFIG_FILE: string;
+export type Environment = "production" | "staging" | "local";
+/**
+ * Resolve the active environment.
+ *
+ * Resolution order:
+ *  1. `SMOLTBOT_ENV` environment variable
+ *  2. Defaults to `production`
+ */
+export declare function getEnvironment(): Environment;
+export declare function getApiUrl(): string;
+export declare function getGatewayUrl(): string;
+export declare function getWebsiteUrl(): string;
+export interface ConfigV1 {
+    agentId: string;
+    email?: string;
+    gateway?: string;
+    openclawConfigured?: boolean;
+    providers?: string[];
+    mnemomApiKey?: string;
+    licenseJwt?: string;
+    configuredAt?: string;
+}
+export interface AgentConfig {
+    agentId: string;
+    openclawConfigured?: boolean;
+    providers?: string[];
+    configuredAt?: string;
+}
+export interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    userId: string;
+    email: string;
+}
+export interface ConfigV2 {
+    version: 2;
+    defaultAgent: string;
+    gateway: string;
+    mnemomApiKey?: string;
+    licenseJwt?: string;
+    agents: Record<string, AgentConfig>;
+    auth?: AuthTokens;
+}
+/** Backward-compatible alias so existing imports keep working. */
+export type Config = ConfigV2;
+/**
+ * Migrate a v1 config into v2 format.
+ * All agent-specific fields move into `agents.default`.
+ */
+export declare function migrateConfig(raw: ConfigV1): ConfigV2;
+export declare function configExists(): boolean;
+/**
+ * Load the config file.
+ * If the file is v1 (no `version` field), it is automatically migrated to v2
+ * and written back to disk before returning.
+ */
+export declare function loadConfig(): ConfigV2 | null;
+export declare function saveConfig(config: ConfigV2): void;
+/**
+ * Resolve the active agent config.
+ *
+ * Resolution order:
+ *  1. Explicit `agentName` parameter (--agent flag)
+ *  2. `SMOLTBOT_AGENT` environment variable
+ *
+ * Returns `null` if no agent is specified or the agent is not found.
+ * Callers must require --agent or SMOLTBOT_AGENT for agent-scoped commands.
+ */
+export declare function getActiveAgent(agentName?: string): AgentConfig | null;
+/**
+ * Require an explicit agent selection. Exits with a helpful error if
+ * no agent was specified via --agent or SMOLTBOT_AGENT.
+ *
+ * Falls back to API lookup if the agent is not in local config:
+ *  - smolt-XXXXXXXX IDs: public endpoint, no auth required
+ *  - Names: authenticated account listing (requires `smoltbot login`)
+ */
+export declare function requireAgent(agentName?: string): Promise<AgentConfig>;
+export declare function generateAgentId(): string;
+/**
+ * Compute the 16-char agent_hash for a given API key and optional agent name.
+ * Matches the gateway's hashApiKey() and the POST /v1/agents/:id/rekey expected format.
+ *
+ * Unnamed agent:  SHA256(apiKey).slice(0, 16)
+ * Named agent:    SHA256(apiKey + '|' + name).slice(0, 16)
+ */
+export declare function computeAgentHash(apiKey: string, name?: string | null): string;
+/**
+ * Derive agent ID deterministically from an API key.
+ * Uses SHA-256 to match the gateway's hashApiKey (Web Crypto SHA-256, first 16 hex chars).
+ * The agent ID is "smolt-" + first 8 hex chars of the SHA-256 digest.
+ */
+export declare function deriveAgentId(apiKey: string): string;
+/**
+ * Derive agent ID deterministically from an API key *and* a name.
+ * Allows multiple named agents to share one API key with distinct IDs.
+ * Uses SHA-256 to match the gateway's hashApiKey(apiKey + '|' + name).
+ */
+export declare function deriveAgentIdWithName(apiKey: string, name: string): string;
+export declare function saveAuthTokens(tokens: AuthTokens): void;
+export declare function clearAuthTokens(): void;
+export declare function getAuthInfo(): AuthTokens | null;