@autokap/core 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# @autokap/core
+
+Shared core library consumed by the bundled `autokap` CLI binary and the
+`@autokap/mcp` server. **You probably do not need to install this package
+directly** — install `@autokap/mcp` (for IDE agents) or `autokap` (for
+CI / Cloud Run) and let them pull `@autokap/core` in transitively.
+
+The package exists to keep request shaping, schema validation, secret
+redaction, and the SSRF-aware config layer in a single source of truth
+across the two consumers.
+
+## Entry points
+
+```ts
+import { /* ... */ } from "@autokap/core";              // re-exports everything below
+import { /* ... */ } from "@autokap/core/config";       // ~/.autokap/config.json, SSRF guards
+import { /* ... */ } from "@autokap/core/api-client";   // apiCall(), validateApiKey(), ApiClientError
+import { /* ... */ } from "@autokap/core/endpoint-helpers"; // buildEndpointAssetUrl, toCsv
+import { /* ... */ } from "@autokap/core/types";        // ValidateResponse, AutokapConfig, CheckResult
+import { /* ... */ } from "@autokap/core/logger";       // createStderrLogger, redactString, redactValue
+```
+
+## What's in here
+
+- **Config** — atomic-write `~/.autokap/config.json` with `chmod 0600` on
+  POSIX. The same file is read by the CLI and the MCP server so users
+  authenticate once.
+- **SSRF / origin guard** (`validatePublicHttpUrl`) — rejects non-http(s),
+  loopback, private IPv4 (including obfuscated forms — `0177.0.0.1`,
+  `2130706433`, hex), `.local` / `.internal`, IPv6 ULA / link-local /
+  IPv4-mapped / 6to4 / NAT64.
+- **API client** — typed `apiCall<T>()` wrapping `fetch` with bearer auth,
+  retry on 429 / 5xx (idempotent methods only), `Retry-After` honoring,
+  error envelope unpacking, and uniform secret redaction in error bodies.
+- **Logger** — stderr-only logger (stdout is reserved for the MCP
+  transport) plus `redactString` / `redactValue` helpers that scrub
+  obvious tokens (`ak_cli_…`, `ak_run_…`, bearer headers) from any string
+  before it lands in an error message or log line.
+
+## Versioning
+
+`@autokap/core` is pinned **exactly** by `@autokap/mcp` and `autokap`.
+When you bump it, bump the consumers' manifests in the same commit so
+the dependency graph stays internally consistent. See the release
+sequence in the root `CHANGELOG.md`.

package/dist/api-client.d.ts

@@ -0,0 +1,53 @@
+import type { ValidateResponse } from './types.js';
+export interface ValidateOptions {
+    apiKey: string;
+    apiBaseUrl: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export declare function validateApiKey(options: ValidateOptions): Promise<ValidateResponse>;
+export declare class ApiClientError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly params?: Record<string, unknown>;
+    readonly responseBody?: unknown;
+    constructor(message: string, status: number, options?: {
+        code?: string;
+        params?: Record<string, unknown>;
+        responseBody?: unknown;
+        cause?: unknown;
+    });
+}
+export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+export interface ApiCallContext {
+    apiKey: string;
+    apiBaseUrl: string;
+}
+export interface ApiCallOptions<TBody = unknown> {
+    method?: HttpMethod;
+    body?: TBody;
+    searchParams?: Record<string, string | number | boolean | undefined | null>;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    /** When true, returns the raw response text instead of parsing JSON. */
+    asText?: boolean;
+    /**
+     * Number of retry attempts after a transient failure (5xx, 429, or network
+     * error). Only applied to idempotent methods (GET, DELETE) by default; pass
+     * `idempotent: true` to force retries on POST/PATCH/PUT.
+     */
+    retries?: number;
+    idempotent?: boolean;
+}
+/**
+ * Generic AutoKap API helper used by every MCP tool. Handles auth, URL
+ * construction, error envelope unpacking (`{ error, code, params }`), retries
+ * on transient failures, and the 204 / empty-body cases.
+ *
+ * Non-JSON 200 responses are surfaced as ApiClientError unless `asText: true`
+ * — we never silently return text-as-T because that hides server contract
+ * drift from typed callers.
+ */
+export declare function apiCall<TResult = unknown, TBody = unknown>(context: ApiCallContext, path: string, options?: ApiCallOptions<TBody>): Promise<TResult>;
+export declare function buildApiUrl(apiBaseUrl: string, path: string, searchParams?: Record<string, string | number | boolean | undefined | null>): string;

package/dist/api-client.js

@@ -0,0 +1,211 @@
+import { validateServerOrigin } from './config.js';
+import { redactString, redactValue } from './logger.js';
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const DEFAULT_RETRY_ATTEMPTS = 1;
+export async function validateApiKey(options) {
+    const { apiKey, apiBaseUrl, signal, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS } = options;
+    validateServerOrigin(apiBaseUrl);
+    const url = `${apiBaseUrl.replace(/\/+$/, '')}/api/cli/validate`;
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${apiKey}` },
+            signal: signal ?? AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        throw wrapNetworkError(err, 'GET', '/api/cli/validate');
+    }
+    if (response.status === 401 || response.status === 403) {
+        return { valid: false };
+    }
+    if (!response.ok) {
+        throw new ApiClientError(`Validation endpoint returned HTTP ${response.status}`, response.status);
+    }
+    const data = (await response.json());
+    return data;
+}
+export class ApiClientError extends Error {
+    status;
+    code;
+    params;
+    responseBody;
+    constructor(message, status, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = 'ApiClientError';
+        this.status = status;
+        this.code = options.code;
+        this.params = options.params;
+        this.responseBody = options.responseBody;
+    }
+}
+const IDEMPOTENT_METHODS = new Set(['GET', 'DELETE']);
+/**
+ * Generic AutoKap API helper used by every MCP tool. Handles auth, URL
+ * construction, error envelope unpacking (`{ error, code, params }`), retries
+ * on transient failures, and the 204 / empty-body cases.
+ *
+ * Non-JSON 200 responses are surfaced as ApiClientError unless `asText: true`
+ * — we never silently return text-as-T because that hides server contract
+ * drift from typed callers.
+ */
+export async function apiCall(context, path, options = {}) {
+    const { method = 'GET', body, searchParams, headers, signal, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS, asText = false, retries = DEFAULT_RETRY_ATTEMPTS, idempotent, } = options;
+    validateServerOrigin(context.apiBaseUrl);
+    const url = buildApiUrl(context.apiBaseUrl, path, searchParams);
+    const finalHeaders = {
+        Authorization: `Bearer ${context.apiKey}`,
+        ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+        ...(headers ?? {}),
+    };
+    const maxAttempts = Math.max(1, (idempotent ?? IDEMPOTENT_METHODS.has(method)) ? retries + 1 : 1);
+    let lastError;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers: finalHeaders,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: signal ?? AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (err) {
+            lastError = wrapNetworkError(err, method, path);
+            if (attempt < maxAttempts - 1) {
+                await sleep(backoffMs(attempt));
+                continue;
+            }
+            throw lastError;
+        }
+        if (response.status === 204) {
+            return null;
+        }
+        if (!response.ok) {
+            const apiError = await buildApiClientError(response, method, path);
+            // Retry on 429 / 5xx if attempts remain and the method is idempotent.
+            const transient = response.status === 429 || response.status >= 500;
+            if (transient && attempt < maxAttempts - 1) {
+                lastError = apiError;
+                await sleep(retryAfterMs(response) ?? backoffMs(attempt));
+                continue;
+            }
+            throw apiError;
+        }
+        if (asText) {
+            return (await response.text());
+        }
+        const contentLength = response.headers.get('content-length');
+        if (contentLength === '0') {
+            return null;
+        }
+        const contentType = response.headers.get('content-type') ?? '';
+        if (!contentType.toLowerCase().includes('json')) {
+            const text = await response.text();
+            if (text.trim().length === 0) {
+                return null;
+            }
+            throw new ApiClientError(`Expected JSON response from ${method} ${path}, got content-type "${contentType || '(none)'}"`, response.status, { responseBody: text.slice(0, 200) });
+        }
+        return (await response.json());
+    }
+    // Unreachable — the loop either returns or throws — but TS doesn't know that.
+    throw lastError ?? new ApiClientError('apiCall exhausted retries', 0);
+}
+async function buildApiClientError(response, method, path) {
+    let errorBody = undefined;
+    let errorMessage = `Request ${method} ${path} failed with HTTP ${response.status}`;
+    let errorCode;
+    let errorParams;
+    try {
+        const text = await response.text();
+        if (text.trim().length > 0) {
+            try {
+                errorBody = JSON.parse(text);
+                if (errorBody && typeof errorBody === 'object') {
+                    const envelope = errorBody;
+                    if (typeof envelope.error === 'string' && envelope.error.length > 0) {
+                        errorMessage = envelope.error;
+                    }
+                    if (typeof envelope.code === 'string') {
+                        errorCode = envelope.code;
+                    }
+                    if (envelope.params && typeof envelope.params === 'object') {
+                        errorParams = envelope.params;
+                    }
+                }
+            }
+            catch {
+                errorBody = text;
+                errorMessage = `${errorMessage}: ${text.slice(0, 200)}`;
+            }
+        }
+    }
+    catch {
+        // ignore body read failures
+    }
+    // Always redact before constructing the error envelope. The body and the
+    // params/message frequently land in MCP tool error responses and IDE log
+    // panes; a server response that echoes the bearer or includes the API key
+    // in a stack trace would otherwise leak straight to the agent / user.
+    return new ApiClientError(redactString(errorMessage), response.status, {
+        code: errorCode,
+        params: errorParams ? redactValue(errorParams) : undefined,
+        responseBody: errorBody !== undefined ? redactValue(errorBody) : undefined,
+    });
+}
+function wrapNetworkError(err, method, path) {
+    if (err instanceof ApiClientError)
+        return err;
+    const cause = err?.cause;
+    const causeCode = cause && typeof cause === 'object' && 'code' in cause ? cause.code : undefined;
+    const rawDetail = causeCode ? String(causeCode) : err.message ?? 'unknown network failure';
+    // Run the detail through the redactor before concatenating. Node fetch
+    // errors usually carry just an ENOTFOUND / ECONNREFUSED code, but a
+    // custom fetch polyfill (or a user-supplied URL containing inline
+    // credentials like `https://u:p@host/`) can echo the bearer or the
+    // basic-auth secret into the error message. Without redaction, those
+    // strings would land in the MCP tool error envelope the agent sees.
+    const detail = redactString(rawDetail);
+    return new ApiClientError(`Network failure on ${method} ${path}: ${detail}`, 0, { code: 'network_error', cause: err });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function backoffMs(attempt) {
+    // 250ms * 2^attempt + 0–250ms jitter — keeps the second try inside the 1s
+    // ballpark and the third inside ~2s.
+    return 250 * 2 ** attempt + Math.floor(Math.random() * 250);
+}
+function retryAfterMs(response) {
+    const header = response.headers.get('retry-after');
+    if (!header)
+        return null;
+    const asInt = Number.parseInt(header, 10);
+    if (Number.isFinite(asInt) && asInt >= 0) {
+        return Math.min(asInt * 1000, 30_000);
+    }
+    const asDate = Date.parse(header);
+    if (Number.isFinite(asDate)) {
+        return Math.max(0, Math.min(asDate - Date.now(), 30_000));
+    }
+    return null;
+}
+export function buildApiUrl(apiBaseUrl, path, searchParams) {
+    const trimmedBase = apiBaseUrl.replace(/\/+$/, '');
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    const url = new URL(`${trimmedBase}${normalizedPath}`);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`Refusing to build API URL with unsupported scheme "${url.protocol}"; only http(s) are allowed.`);
+    }
+    if (searchParams) {
+        for (const [key, value] of Object.entries(searchParams)) {
+            if (value === undefined || value === null)
+                continue;
+            url.searchParams.set(key, String(value));
+        }
+    }
+    return url.toString();
+}
+//# sourceMappingURL=api-client.js.map

package/dist/config.d.ts

@@ -0,0 +1,37 @@
+import type { AutokapConfig } from './types.js';
+declare const DEFAULT_API_BASE_URL = "https://autokap.app";
+declare const DEFAULT_WS_URL = "wss://autokap.app/ws";
+declare const LOCAL_API_BASE_URL = "http://localhost:3000";
+declare const API_KEY_ENV_VAR = "AUTOKAP_API_KEY";
+declare const RUN_TOKEN_ENV_VAR = "AUTOKAP_RUN_TOKEN";
+declare const API_BASE_URL_ENV_VAR = "AUTOKAP_API_BASE_URL";
+declare const WS_URL_ENV_VAR = "AUTOKAP_WS_URL";
+declare const ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR = "AUTOKAP_ALLOW_UNSAFE_SERVER_ORIGIN";
+export declare function getConfigDir(): string;
+export declare function getConfigPath(): string;
+export declare function getDefaultApiBaseUrl(): string;
+export declare function getDefaultWsUrl(apiBaseUrl?: string): string;
+export declare function readConfig(): Promise<AutokapConfig | null>;
+export declare function writeConfig(config: AutokapConfig): Promise<void>;
+export declare function deleteConfig(): Promise<void>;
+declare function assertAllowedApiOrigin(candidateUrl: string, baselineUrl: string, envVar?: string): void;
+/**
+ * SSRF guard for any caller-supplied URL that the AutoKap stack will
+ * eventually fetch (MCP tool inputs — apiBaseUrl, proxyUrl, webhookUrl,
+ * loginUrl, project baseUrl, etc.).
+ *
+ * Rejects:
+ *   - non-http(s) schemes (file://, javascript:, gopher://, data:, ...)
+ *   - localhost / 127.0.0.0/8 / private IPv4 / link-local / IPv6 loopback
+ *   - hostnames ending in `.local`, `.internal`
+ *
+ * When `AUTOKAP_ALLOW_UNSAFE_SERVER_ORIGIN=1`, the private-host check is
+ * relaxed for dev workflows. The scheme check is NEVER relaxed.
+ *
+ * `validatePublicHttpUrl` is the public alias used by MCP tools that accept
+ * user-provided URLs; `validateServerOrigin` is the alias used by core API
+ * client paths.
+ */
+export declare function validateServerOrigin(candidateUrl: string): void;
+export declare function validatePublicHttpUrl(candidateUrl: string, fieldLabel?: string): void;
+export { DEFAULT_API_BASE_URL, DEFAULT_WS_URL, LOCAL_API_BASE_URL, API_KEY_ENV_VAR, RUN_TOKEN_ENV_VAR, API_BASE_URL_ENV_VAR, WS_URL_ENV_VAR, ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR, assertAllowedApiOrigin, };

package/dist/config.js

@@ -0,0 +1,404 @@
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+const DEFAULT_API_BASE_URL = 'https://autokap.app';
+const DEFAULT_WS_URL = 'wss://autokap.app/ws';
+const LOCAL_API_BASE_URL = 'http://localhost:3000';
+const API_KEY_ENV_VAR = 'AUTOKAP_API_KEY';
+const RUN_TOKEN_ENV_VAR = 'AUTOKAP_RUN_TOKEN';
+const API_BASE_URL_ENV_VAR = 'AUTOKAP_API_BASE_URL';
+const WS_URL_ENV_VAR = 'AUTOKAP_WS_URL';
+const ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR = 'AUTOKAP_ALLOW_UNSAFE_SERVER_ORIGIN';
+export function getConfigDir() {
+    return path.join(os.homedir(), '.autokap');
+}
+export function getConfigPath() {
+    return path.join(getConfigDir(), 'config.json');
+}
+export function getDefaultApiBaseUrl() {
+    return normalizeUrl(process.env[API_BASE_URL_ENV_VAR]) ?? DEFAULT_API_BASE_URL;
+}
+export function getDefaultWsUrl(apiBaseUrl = getDefaultApiBaseUrl()) {
+    return normalizeUrl(process.env[WS_URL_ENV_VAR]) ?? deriveWsUrl(apiBaseUrl);
+}
+export async function readConfig() {
+    const envRunToken = normalizeApiKey(process.env[RUN_TOKEN_ENV_VAR]);
+    if (envRunToken) {
+        const apiBaseUrl = getDefaultApiBaseUrl();
+        const wsUrl = getDefaultWsUrl(apiBaseUrl);
+        assertAllowedApiOrigin(apiBaseUrl, DEFAULT_API_BASE_URL, API_BASE_URL_ENV_VAR);
+        return { apiKey: envRunToken, apiBaseUrl, wsUrl };
+    }
+    const envApiKey = normalizeApiKey(process.env[API_KEY_ENV_VAR]);
+    if (envApiKey) {
+        const apiBaseUrl = getDefaultApiBaseUrl();
+        const wsUrl = getDefaultWsUrl(apiBaseUrl);
+        assertAllowedApiOrigin(apiBaseUrl, DEFAULT_API_BASE_URL, API_BASE_URL_ENV_VAR);
+        return { apiKey: envApiKey, apiBaseUrl, wsUrl };
+    }
+    // Only swallow IO / parse failures. Origin-allowlist / schema errors must
+    // bubble up so the user sees what's wrong instead of "not authenticated".
+    let raw;
+    try {
+        raw = await fs.readFile(getConfigPath(), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const record = parsed;
+    if (typeof record.apiKey !== 'string' || record.apiKey.length === 0)
+        return null;
+    const storedApiBaseUrlRaw = typeof record.apiBaseUrl === 'string' ? record.apiBaseUrl : null;
+    const storedWsUrlRaw = typeof record.wsUrl === 'string' ? record.wsUrl : null;
+    const envApiBaseUrl = normalizeUrl(process.env[API_BASE_URL_ENV_VAR]);
+    const envWsUrl = normalizeUrl(process.env[WS_URL_ENV_VAR]);
+    const storedApiBaseUrl = normalizeUrl(storedApiBaseUrlRaw) ?? DEFAULT_API_BASE_URL;
+    const apiBaseUrl = envApiBaseUrl ?? storedApiBaseUrl;
+    const wsUrl = envWsUrl ??
+        (envApiBaseUrl
+            ? deriveWsUrl(apiBaseUrl)
+            : normalizeUrl(storedWsUrlRaw) ?? deriveWsUrl(apiBaseUrl));
+    assertAllowedApiOrigin(apiBaseUrl, storedApiBaseUrl, envApiBaseUrl ? API_BASE_URL_ENV_VAR : undefined);
+    if (envWsUrl) {
+        assertAllowedApiOrigin(wsUrl.replace(/^ws/, 'http'), deriveWsUrl(storedApiBaseUrl).replace(/^ws/, 'http'), WS_URL_ENV_VAR);
+    }
+    return { apiKey: record.apiKey, apiBaseUrl, wsUrl };
+}
+export async function writeConfig(config) {
+    const dir = getConfigDir();
+    await fs.mkdir(dir, { recursive: true });
+    if (process.platform !== 'win32') {
+        try {
+            await fs.chmod(dir, 0o700);
+        }
+        catch {
+            // best-effort — the file's 0600 below is the real safety
+        }
+    }
+    const configPath = getConfigPath();
+    const normalizedConfig = {
+        ...config,
+        apiBaseUrl: normalizeUrl(config.apiBaseUrl) ?? DEFAULT_API_BASE_URL,
+        wsUrl: normalizeUrl(config.wsUrl) ?? deriveWsUrl(config.apiBaseUrl),
+    };
+    // Atomic write: write to a per-process tmp file (so concurrent writes don't
+    // clobber each other), chmod it BEFORE the rename (so the final file is
+    // never world-readable on POSIX), then rename. `fs.rename` is atomic on
+    // POSIX for paths on the same filesystem; Windows replaces the destination
+    // atomically as well when the source/dest are on the same volume.
+    //
+    // `mode: 0o600` is passed to writeFile so the tmp file is created with the
+    // tight permission set from the very first byte — closes the small window
+    // where umask alone would have produced 0o644.
+    const tmpPath = `${configPath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+    try {
+        await fs.writeFile(tmpPath, JSON.stringify(normalizedConfig, null, 2), {
+            encoding: 'utf-8',
+            mode: 0o600,
+        });
+        if (process.platform !== 'win32') {
+            // Belt-and-suspenders: enforce 0600 even if the FS ignored the mode
+            // argument (some filesystems / Node versions do).
+            await fs.chmod(tmpPath, 0o600);
+        }
+        await fs.rename(tmpPath, configPath);
+    }
+    catch (err) {
+        await fs.rm(tmpPath, { force: true }).catch(() => undefined);
+        throw err;
+    }
+}
+export async function deleteConfig() {
+    try {
+        await fs.rm(getConfigPath());
+    }
+    catch {
+        // ignore missing file
+    }
+}
+function normalizeApiKey(value) {
+    const trimmed = value?.trim();
+    return trimmed || null;
+}
+function normalizeUrl(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return null;
+    return trimmed.replace(/\/+$/, '');
+}
+function deriveWsUrl(apiBaseUrl) {
+    try {
+        const url = new URL(apiBaseUrl);
+        url.protocol =
+            url.protocol === 'https:' ? 'wss:' : url.protocol === 'http:' ? 'ws:' : url.protocol;
+        const pathname = url.pathname.replace(/\/+$/, '');
+        url.pathname = `${pathname || ''}/ws`;
+        url.search = '';
+        url.hash = '';
+        return url.toString().replace(/\/+$/, '');
+    }
+    catch {
+        return DEFAULT_WS_URL;
+    }
+}
+function normalizeOrigin(value) {
+    const normalized = normalizeUrl(value);
+    if (!normalized)
+        return null;
+    try {
+        const parsed = new URL(normalized);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            return null;
+        return parsed.origin;
+    }
+    catch {
+        return null;
+    }
+}
+function isUnsafeOverrideEnabled() {
+    const raw = process.env[ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR]?.trim().toLowerCase();
+    return raw === '1' || raw === 'true';
+}
+function isTrustedOrigin(origin) {
+    return (origin === normalizeOrigin(DEFAULT_API_BASE_URL) ||
+        origin === normalizeOrigin(LOCAL_API_BASE_URL));
+}
+function assertAllowedApiOrigin(candidateUrl, baselineUrl, envVar) {
+    const candidateOrigin = normalizeOrigin(candidateUrl);
+    const baselineOrigin = normalizeOrigin(baselineUrl);
+    if (!candidateOrigin || !baselineOrigin) {
+        throw new Error('AutoKap config contains an invalid server origin');
+    }
+    if (candidateOrigin === baselineOrigin || isTrustedOrigin(candidateOrigin)) {
+        return;
+    }
+    if (isUnsafeOverrideEnabled()) {
+        process.stderr.write(`[autokap:warn] Allowing unsafe server override from ${baselineOrigin} to ${candidateOrigin} because ${ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR}=1\n`);
+        return;
+    }
+    throw new Error(`Refusing unsafe server override to ${candidateOrigin}. Set ${ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR}=1 to allow ${envVar ?? 'this override'} explicitly.`);
+}
+/**
+ * SSRF guard for any caller-supplied URL that the AutoKap stack will
+ * eventually fetch (MCP tool inputs — apiBaseUrl, proxyUrl, webhookUrl,
+ * loginUrl, project baseUrl, etc.).
+ *
+ * Rejects:
+ *   - non-http(s) schemes (file://, javascript:, gopher://, data:, ...)
+ *   - localhost / 127.0.0.0/8 / private IPv4 / link-local / IPv6 loopback
+ *   - hostnames ending in `.local`, `.internal`
+ *
+ * When `AUTOKAP_ALLOW_UNSAFE_SERVER_ORIGIN=1`, the private-host check is
+ * relaxed for dev workflows. The scheme check is NEVER relaxed.
+ *
+ * `validatePublicHttpUrl` is the public alias used by MCP tools that accept
+ * user-provided URLs; `validateServerOrigin` is the alias used by core API
+ * client paths.
+ */
+export function validateServerOrigin(candidateUrl) {
+    validatePublicHttpUrl(candidateUrl, 'server origin');
+}
+export function validatePublicHttpUrl(candidateUrl, fieldLabel = 'URL') {
+    let parsed;
+    try {
+        parsed = new URL(candidateUrl);
+    }
+    catch {
+        throw new Error(`Invalid ${fieldLabel}: ${candidateUrl}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`Refusing ${fieldLabel} with unsupported scheme "${parsed.protocol}"; only http(s) are allowed.`);
+    }
+    if (isPrivateOrInternalHost(parsed.hostname)) {
+        if (isUnsafeOverrideEnabled()) {
+            process.stderr.write(`[autokap:warn] Allowing private/internal host ${parsed.hostname} for ${fieldLabel} because ${ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR}=1\n`);
+            return;
+        }
+        throw new Error(`Refusing ${fieldLabel} pointing at a private or link-local host (${parsed.hostname}). ` +
+            `Set ${ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR}=1 to override (dev/test only).`);
+    }
+}
+function isPrivateOrInternalHost(hostname) {
+    const lower = hostname.toLowerCase();
+    if (lower === 'localhost')
+        return true;
+    if (lower === '0.0.0.0' || lower === '::' || lower === '[::]')
+        return true;
+    if (lower.endsWith('.local') || lower.endsWith('.internal'))
+        return true;
+    if (lower === '::1' || lower === '[::1]')
+        return true;
+    // IPv4 — dotted-decimal AND obfuscated forms (octal/hex/decimal). Node's
+    // fetch normalizes these via libuv's getaddrinfo, so `http://2130706433/`
+    // resolves to 127.0.0.1 and would otherwise slip past a dotted-only check.
+    const ipv4 = parseIpv4(lower);
+    if (ipv4) {
+        const [a, b] = ipv4;
+        if (a === 10)
+            return true; // 10.0.0.0/8
+        if (a === 127)
+            return true; // loopback 127.0.0.0/8
+        if (a === 169 && b === 254)
+            return true; // link-local 169.254.0.0/16
+        if (a === 172 && b >= 16 && b <= 31)
+            return true; // 172.16.0.0/12
+        if (a === 192 && b === 168)
+            return true; // 192.168.0.0/16
+        if (a === 100 && b >= 64 && b <= 127)
+            return true; // CGNAT 100.64.0.0/10
+        if (a === 0)
+            return true; // 0.0.0.0/8 (this network)
+        if (a >= 224)
+            return true; // multicast + reserved
+    }
+    // Bracketed IPv6 — loopback, ULA, link-local, IPv4-mapped, 6to4-encoded
+    // loopback, NAT64 well-known prefix carrying private/loopback v4.
+    if (lower.startsWith('[') && lower.endsWith(']')) {
+        return isPrivateIpv6(lower.slice(1, -1));
+    }
+    return false;
+}
+/**
+ * Parse an IPv4 literal that Node's fetch / getaddrinfo would accept,
+ * including the obfuscated forms attackers use to bypass naive checks:
+ *   - dotted-decimal:        127.0.0.1
+ *   - dotted with leading 0: 0177.0.0.1 (octal — 0177 = 127)
+ *   - dotted with 0x prefix: 0x7f.0.0.1 (hex)
+ *   - single 32-bit integer: 2130706433 (decimal — equals 127.0.0.1)
+ *   - single hex integer:    0x7f000001
+ *
+ * Returns the octet tuple [a, b, c, d] when recognized, else null.
+ * Each octet is clamped on parse so malformed inputs like 999.0.0.0
+ * return null instead of allowing the SSRF guard to mis-classify them.
+ */
+function parseIpv4(literal) {
+    const parts = literal.split('.');
+    if (parts.length === 4) {
+        const octets = [];
+        for (const part of parts) {
+            const n = parseObfuscatedOctet(part);
+            if (n === null || n < 0 || n > 255)
+                return null;
+            octets.push(n);
+        }
+        return octets;
+    }
+    if (parts.length === 1) {
+        const n = parseObfuscatedInt(parts[0]);
+        if (n === null || n < 0 || n > 0xff_ff_ff_ff)
+            return null;
+        return [
+            (n >>> 24) & 0xff,
+            (n >>> 16) & 0xff,
+            (n >>> 8) & 0xff,
+            n & 0xff,
+        ];
+    }
+    return null;
+}
+function parseObfuscatedOctet(part) {
+    // Reject empties / spaces / sign.
+    if (part.length === 0 || /[^0-9a-fx]/.test(part))
+        return null;
+    if (part.startsWith('0x') || part.startsWith('0X')) {
+        const hex = part.slice(2);
+        if (hex.length === 0 || /[^0-9a-f]/.test(hex))
+            return null;
+        return Number.parseInt(hex, 16);
+    }
+    if (part.length > 1 && part.startsWith('0')) {
+        if (/[^0-7]/.test(part))
+            return null;
+        return Number.parseInt(part, 8);
+    }
+    if (/[^0-9]/.test(part))
+        return null;
+    return Number.parseInt(part, 10);
+}
+function parseObfuscatedInt(part) {
+    if (part.startsWith('0x') || part.startsWith('0X')) {
+        const hex = part.slice(2);
+        if (hex.length === 0 || /[^0-9a-f]/.test(hex))
+            return null;
+        return Number.parseInt(hex, 16);
+    }
+    if (part.length > 1 && part.startsWith('0')) {
+        if (/[^0-7]/.test(part))
+            return null;
+        return Number.parseInt(part, 8);
+    }
+    if (/[^0-9]/.test(part))
+        return null;
+    return Number.parseInt(part, 10);
+}
+function isPrivateIpv6(ipv6) {
+    if (ipv6 === '::1')
+        return true;
+    if (ipv6.startsWith('fc') || ipv6.startsWith('fd'))
+        return true; // ULA fc00::/7
+    if (ipv6.startsWith('fe80'))
+        return true; // link-local
+    // IPv4-mapped (RFC 4291): canonicalizes to either `::ffff:a.b.c.d` or the
+    // hex-pair shorthand `::ffff:H:L`. Node's URL canonicalizes dotted form to
+    // the hex-pair form, so both must be handled.
+    if (ipv6.startsWith('::ffff:')) {
+        const tail = ipv6.slice('::ffff:'.length);
+        return embeddedV4IsPrivate(tail);
+    }
+    if (ipv6.startsWith('::ffff:0:')) {
+        const tail = ipv6.slice('::ffff:0:'.length);
+        return embeddedV4IsPrivate(tail);
+    }
+    // Bare hex-pair shorthand (no ::ffff prefix), e.g. `::7f00:1` = 127.0.0.1.
+    if (ipv6.startsWith('::') && !ipv6.startsWith(':::')) {
+        const tail = ipv6.slice(2);
+        if (/^[0-9a-f]{1,4}:[0-9a-f]{1,4}$/.test(tail)) {
+            return embeddedV4IsPrivate(tail);
+        }
+    }
+    // 6to4-encoded prefix `2002::/16` — when the embedded IPv4 is private/
+    // loopback, the route lands in those networks despite the public-looking
+    // outer prefix.
+    const sixToFour = ipv6.match(/^2002:([0-9a-f]{1,4}):([0-9a-f]{1,4})/);
+    if (sixToFour) {
+        return embeddedV4IsPrivate(`${sixToFour[1]}:${sixToFour[2]}`);
+    }
+    // NAT64 well-known prefix `64:ff9b::/96` — last 32 bits are the embedded v4.
+    const nat64 = ipv6.match(/^64:ff9b::([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (nat64) {
+        return embeddedV4IsPrivate(`${nat64[1]}:${nat64[2]}`);
+    }
+    return false;
+}
+/**
+ * Parse a 32-bit IPv4 embedded in an IPv6 address. Accepts both the
+ * dotted-decimal form (`127.0.0.1`) and the hex-pair shorthand (`7f00:1`).
+ */
+function embeddedV4IsPrivate(tail) {
+    const inner = parseIpv4(tail);
+    if (inner) {
+        return isPrivateOrInternalHost(`${inner[0]}.${inner[1]}.${inner[2]}.${inner[3]}`);
+    }
+    const colon = tail.split(':');
+    if (colon.length === 2) {
+        const hi = Number.parseInt(colon[0], 16);
+        const lo = Number.parseInt(colon[1], 16);
+        if (Number.isFinite(hi) && Number.isFinite(lo) && hi >= 0 && hi <= 0xffff && lo >= 0 && lo <= 0xffff) {
+            const dotted = `${(hi >>> 8) & 0xff}.${hi & 0xff}.${(lo >>> 8) & 0xff}.${lo & 0xff}`;
+            return isPrivateOrInternalHost(dotted);
+        }
+    }
+    return false;
+}
+export { DEFAULT_API_BASE_URL, DEFAULT_WS_URL, LOCAL_API_BASE_URL, API_KEY_ENV_VAR, RUN_TOKEN_ENV_VAR, API_BASE_URL_ENV_VAR, WS_URL_ENV_VAR, ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR, assertAllowedApiOrigin, };
+//# sourceMappingURL=config.js.map

package/dist/endpoint-helpers.d.ts

@@ -0,0 +1,12 @@
+export declare function buildEndpointAssetUrl(apiBaseUrl: string, endpointId: string): string;
+export interface EndpointUrlParams {
+    lang: string;
+    theme: string;
+    target: string;
+    w?: string;
+    quality?: string;
+    format?: string;
+    scale?: string;
+}
+export declare function buildEndpointUrlParams(assetType: string): EndpointUrlParams;
+export declare function toCsv(rows: Array<Record<string, unknown>>, columns: string[]): string;

package/dist/endpoint-helpers.js

@@ -0,0 +1,33 @@
+export function buildEndpointAssetUrl(apiBaseUrl, endpointId) {
+    // Encode the id even though today it's always a UUID — if the backend ever
+    // adopts a non-opaque id format (timestamp-prefixed, slug-shaped) that
+    // includes `/`, `?`, `#`, or `..`, raw interpolation would silently
+    // produce a malformed URL or a path-traversal vector.
+    return `${apiBaseUrl.replace(/\/+$/, '')}/api/v1/assets/${encodeURIComponent(endpointId)}`;
+}
+export function buildEndpointUrlParams(assetType) {
+    const isClip = assetType === 'clip';
+    return {
+        lang: '<lang>',
+        theme: '<theme>',
+        target: '<target>',
+        ...(isClip
+            ? { format: 'mp4|webm|gif' }
+            : { w: '<width>', quality: '<quality>', format: 'png|jpeg|webp', scale: '1|2|3' }),
+    };
+}
+export function toCsv(rows, columns) {
+    const escape = (value) => {
+        if (value === null || value === undefined)
+            return '';
+        const str = String(value);
+        if (str.includes(',') || str.includes('"') || str.includes('\n') || str.includes('\r')) {
+            return `"${str.replace(/"/g, '""')}"`;
+        }
+        return str;
+    };
+    const header = columns.map(escape).join(',');
+    const body = rows.map((row) => columns.map((col) => escape(row[col])).join(',')).join('\n');
+    return `${header}\n${body}`;
+}
+//# sourceMappingURL=endpoint-helpers.js.map

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './config.js';
+export * from './api-client.js';
+export * from './endpoint-helpers.js';
+export * from './logger.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './config.js';
+export * from './api-client.js';
+export * from './endpoint-helpers.js';
+export * from './logger.js';
+//# sourceMappingURL=index.js.map

package/dist/logger.d.ts

@@ -0,0 +1,22 @@
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface Logger {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+export interface CreateLoggerOptions {
+    /**
+     * Minimum log level. Defaults to `process.env.AUTOKAP_LOG` (case-insensitive
+     * one of 'debug' | 'info' | 'warn' | 'error') and falls back to 'info'.
+     */
+    minLevel?: LogLevel;
+}
+export declare function createStderrLogger(options?: CreateLoggerOptions): Logger;
+declare function redactString(input: string): string;
+declare function redactValue(value: unknown, seen?: WeakSet<object>): unknown;
+export { redactString, redactValue };
+export declare const __test: {
+    redactString: typeof redactString;
+    redactValue: typeof redactValue;
+};

package/dist/logger.js

@@ -0,0 +1,91 @@
+const LEVEL_ORDER = { debug: 10, info: 20, warn: 30, error: 40 };
+// AutoKap API/run-token prefixes — leak detection. Pattern is intentionally
+// broad: catches `ak_cli_<hex>`, `ak_run_<hex>`, and any other `ak_<scope>_<id>`
+// that's at least 6 chars long so we never accidentally log a real key.
+const API_KEY_PATTERN = /\bak_[a-z]+_[A-Za-z0-9_-]{6,}\b/g;
+const BEARER_PATTERN = /\bBearer\s+[A-Za-z0-9._\-]{6,}/gi;
+const SENSITIVE_KEY_PATTERN = /(api[_-]?key|password|token|bearer|secret|authorization)/i;
+function format(level, message) {
+    return `[autokap:${level}] ${message}`;
+}
+function resolveMinLevel(explicit) {
+    if (explicit)
+        return explicit;
+    const env = process.env.AUTOKAP_LOG?.trim().toLowerCase();
+    if (env && env in LEVEL_ORDER)
+        return env;
+    return 'info';
+}
+export function createStderrLogger(options = {}) {
+    const minLevel = resolveMinLevel(options.minLevel);
+    const minRank = LEVEL_ORDER[minLevel];
+    const write = (level, message, args) => {
+        if (LEVEL_ORDER[level] < minRank)
+            return;
+        const line = format(level, redactString(message));
+        if (args.length > 0) {
+            process.stderr.write(`${line} ${args.map(serialize).join(' ')}\n`);
+        }
+        else {
+            process.stderr.write(`${line}\n`);
+        }
+    };
+    return {
+        debug: (msg, ...args) => write('debug', msg, args),
+        info: (msg, ...args) => write('info', msg, args),
+        warn: (msg, ...args) => write('warn', msg, args),
+        error: (msg, ...args) => write('error', msg, args),
+    };
+}
+function redactString(input) {
+    // Bearer first — otherwise the inner ak_… pattern matches first and the
+    // Bearer suffix won't recognize the masked literal as a Bearer token.
+    return input.replace(BEARER_PATTERN, 'Bearer ***REDACTED').replace(API_KEY_PATTERN, 'ak_***_REDACTED');
+}
+function redactValue(value, seen = new WeakSet()) {
+    if (typeof value === 'string')
+        return redactString(value);
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value !== 'object')
+        return value;
+    if (seen.has(value))
+        return '[Circular]';
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.map((entry) => redactValue(entry, seen));
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (SENSITIVE_KEY_PATTERN.test(key)) {
+            out[key] = '[redacted]';
+        }
+        else {
+            out[key] = redactValue(raw, seen);
+        }
+    }
+    return out;
+}
+function serialize(value) {
+    if (value instanceof Error) {
+        const stack = value.stack ?? value.message;
+        const cause = value.cause;
+        const causeSuffix = cause ? ` (cause: ${redactString(String(cause))})` : '';
+        return `${redactString(stack)}${causeSuffix}`;
+    }
+    if (typeof value === 'string')
+        return redactString(value);
+    try {
+        return JSON.stringify(redactValue(value));
+    }
+    catch {
+        return redactString(String(value));
+    }
+}
+// Public for callers that need to redact a value before surfacing it to an
+// MCP client (e.g. `errorResult.responseBody`, tool error envelopes). The
+// canonical entry point — using the logger's own redaction keeps the
+// secrets-on-the-wire definition in one place.
+export { redactString, redactValue };
+// Backwards-compat alias retained for older tests; prefer the named exports.
+export const __test = { redactString, redactValue };
+//# sourceMappingURL=logger.js.map

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+export interface AutokapConfig {
+    apiKey: string;
+    apiBaseUrl: string;
+    wsUrl: string;
+}
+export interface ValidateResponse {
+    valid: boolean;
+    userId?: string;
+    keyType?: string;
+    email?: string;
+    name?: string;
+}
+export type CheckStatus = 'ok' | 'warn' | 'fail';
+export interface CheckResult {
+    name: string;
+    status: CheckStatus;
+    message: string;
+    fixCommand?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@autokap/core",
+  "version": "0.1.0",
+  "description": "Shared core library for AutoKap CLI and MCP server",
+  "license": "ISC",
+  "author": "AutoKap",
+  "homepage": "https://autokap.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AutoKap/autokap.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
+    "./api-client": {
+      "types": "./dist/api-client.d.ts",
+      "default": "./dist/api-client.js"
+    },
+    "./endpoint-helpers": {
+      "types": "./dist/endpoint-helpers.d.ts",
+      "default": "./dist/endpoint-helpers.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./logger": {
+      "types": "./dist/logger.d.ts",
+      "default": "./dist/logger.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --root ../..",
+    "prepublishOnly": "npm run build && node -e \"require('node:fs').accessSync('dist/index.js'); require('node:fs').accessSync('dist/index.d.ts');\""
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/**/*.js.map"
+  ],
+  "dependencies": {},
+  "devDependencies": {}
+}