P0: security scans + stable tool envelopes + doctor tool

Author: phwizard

.github/workflows/security-scan.yml

@@ -0,0 +1,36 @@
+name: Security scan (report-only)
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  gitleaks:
+    name: gitleaks (secrets)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Run gitleaks (report-only)
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          GITLEAKS_ENABLE_UPLOAD_ARTIFACT: "true"
+          GITLEAKS_ENABLE_SUMMARY: "true"
+
+  semgrep:
+    name: semgrep (sast)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run semgrep (report-only)
+        uses: semgrep/semgrep-action@v1
+        with:
+          config: "auto"
+

README.md

@@ -14,6 +14,7 @@ Use it from **Cursor**, **VS Code MCP**, **Claude Desktop**, or **Windsurf/Cline
 - **Session / Config**
   - `ethora-configure` — set API URL + App JWT (in-memory for this MCP session)
   - `ethora-status` — show configured API URL + whether auth tokens are present
+  - `ethora-doctor` — validate config + ping the configured Ethora API
   - `ethora-app-select` — select current appId and optionally set appToken (B2B)
   - `ethora-auth-use-app` — switch to app-token auth mode (B2B)
   - `ethora-auth-use-user` — switch to user-session auth mode
@@ -195,7 +196,7 @@ You can provide these either:
 After the server shows as **connected** in your client:
 
 - Run `list tools` (client command) to verify Ethora tools are available.
-- Check config: call `ethora-status`
+- Check config/connectivity: call `ethora-doctor` (or `ethora-status`)
 - Configure (optional): call `ethora-configure` with `apiUrl` / `appJwt`
 - Try a login: call `ethora-user-login`
 - List applications: call `ethora-app-list`
@@ -209,6 +210,12 @@ After the server shows as **connected** in your client:
 - Use **least privilege** keys and consider **allowlists/rate limits** on your Ethora backend.
 - Rotate credentials regularly in production use.
 
+### CI security scans (report-only)
+
+This repo runs **report-only** scans on pushes/PRs:
+- **gitleaks** for secret scanning
+- **semgrep** for basic SAST
+
 ---
 
 ## 🧰 Development

src/apiClientDappros.ts

@@ -29,6 +29,11 @@ export const httpClientDappros = axios.create({
   baseURL: appConfig.apiUrl,
 });
 
+// Small helper used by `ethora-doctor`
+export async function apiPing(timeoutMs = 3000) {
+  return httpClientDappros.get("/ping", { timeout: timeoutMs })
+}
+
 httpClientDappros.interceptors.request.use((config) => {
   // If the user provides a full URL, don't attempt to mutate headers.
   if (!config.url) return config

src/mcpResponse.ts

@@ -0,0 +1,48 @@
+export type McpEnvelope = {
+  ok: boolean
+  ts: string
+  meta?: Record<string, any>
+  data?: any
+  error?: {
+    message: string
+    kind?: string
+    status?: number
+    details?: any
+  }
+}
+
+function isoNow() {
+  return new Date().toISOString()
+}
+
+function parseAxiosishError(error: unknown): { message: string; status?: number; details?: any } {
+  if (error && typeof error === "object" && "response" in error) {
+    const e = error as any
+    const status = e.response?.status
+    const data = e.response?.data
+    const msg = e.message || "request failed"
+    return { message: msg, status, details: data }
+  }
+  if (error instanceof Error) return { message: error.message }
+  return { message: String(error) }
+}
+
+export function ok(data: any, meta?: Record<string, any>): McpEnvelope {
+  return { ok: true, ts: isoNow(), meta, data }
+}
+
+export function fail(error: unknown, meta?: Record<string, any>): McpEnvelope {
+  const parsed = parseAxiosishError(error)
+  return {
+    ok: false,
+    ts: isoNow(),
+    meta,
+    error: {
+      message: parsed.message,
+      status: parsed.status,
+      details: parsed.details,
+    },
+  }
+}
+
+