hakira-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hakira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# hakira-mcp
+
+A local **stdio MCP server** that lets your coding agent (Claude Code, Cursor, Windsurf, …) trigger
+**Hakira cloud security audits** of the repo you're working in — and read the findings back — without
+leaving the editor.
+
+It exposes eight tools and one resource:
+
+| Tool | Cost | What it does |
+|---|---|---|
+| `start_audit` | **spends credits** | Zip the working tree (gitignore-respecting, secrets stripped), upload it, and start a cloud audit. Returns `{ audit_id, mode, do_not_poll, agent_instruction }` immediately. Asks background vs wait when the host supports MCP elicitation. |
+| `get_audit_status` | free | Poll an audit: `queued → provisioning → running → ready` (or `canceled` / `error`). Full-scope audits also carry `full_project_estimate_usd`. |
+| `get_audit_events` | free | Activity trail (coalesced assistant text, collapsed tool runs, progress, findings). No tool result bodies. Use when checking what Hakira is doing / has done. Omit `after` for the latest page. |
+| `get_audit_findings` | free | Finding **summaries** only. Then call `get_finding` for critical/high or when explaining/fixing. |
+| `get_finding` | free | Full finding (description, evidence, recommendation). Use after `get_audit_findings`. |
+| `list_audits` | free | Recent audits/sessions across your account (`is_current` marks this local project). Optional `workspace_id` filter. |
+| `list_workspaces` | free | All workspaces on your account; `is_current` marks this local project. |
+| `cancel_audit` | free | Request cancellation of a running audit. |
+
+Resource `hakira://finding/<id>` returns the same full detail as `get_finding` (kept for hosts that prefer resources).
+
+> **⚠️ `start_audit` spends credits** — it's the only Hakira tool that does; the other seven are free.
+> A whole-project (`full`) audit costs more than a changed-files (`diff`) audit. If your credit balance
+> is too low the call fails immediately with a `payment_required` error carrying a top-up link, and
+> **nothing is uploaded** — add credits and re-run.
+
+## Quickstart
+
+1. Add the server to your client config (see **Install** below) — browser login, no token.
+   **On Cursor, Add to Cursor is faster than pasting the prompt.**
+2. **Restart the client** so it launches the server (MCP config loads at start; no hot reload).
+   On Cursor after one-click install, toggle/enable in MCP settings is often enough.
+3. Ask your agent to run an audit — the first tool call opens your browser to authorize.
+4. Read the findings back in your editor.
+
+### Give this to your coding agent
+
+Paste this into Claude Code or Cursor and it will set Hakira up and run your first audit — it asks what
+to scan and waits for your go-ahead before the paid call. On Cursor, prefer **Add to Cursor** (Install)
+for the install step, then paste this to run the first audit:
+
+```
+Set up the Hakira security-audit MCP server for this project and run a first audit.
+
+1. Add this server to my MCP config (Claude Code: .mcp.json; Cursor:
+   .cursor/mcp.json) — do not overwrite other servers:
+   {
+     "mcpServers": {
+       "hakira": { "type": "stdio", "command": "npx", "args": ["-y", "hakira-mcp"] }
+     }
+   }
+   Then tell me to restart so the server loads.
+
+2. After I restart, ask me what to scan — the whole project (scope:"full") or only
+   my locally-changed files (scope:"diff") — and whether to narrow to a path or
+   point at a running URL. Then call the Hakira `start_audit` tool with my choice.
+   Do NOT pass `mode` unless I explicitly said "background" or "wait" — omit it so
+   the host can ask (or default background). start_audit is the only Hakira tool
+   that spends credits, so WAIT for my explicit go-ahead before calling it. The
+   first call will open my browser to authorize this machine.
+   - If start_audit returns a `payment_required` error, show me the buy_credits_url
+     from that error and stop — I need to add credits before the audit can run.
+
+3. It returns { audit_id, status, mode, do_not_poll, agent_instruction }.
+   ALWAYS follow `agent_instruction` / `do_not_poll`:
+   - If do_not_poll is true (background): do NOT poll. Tell me the audit_id and
+     that I can ask later for status/findings. Continue helping with other work.
+     When I ask to check the audit / what Hakira is doing, call `get_audit_events`
+     (omit after for the latest page; page with after=next_after if has_more).
+   - If do_not_poll is false (wait): poll `get_audit_status` with that audit_id,
+     waiting poll_after_ms between calls, until status is "ready" (stop on
+     "canceled" or "error"). Then call `get_audit_findings`.
+   Hosts that support MCP elicitation may ask me background vs wait before the
+   audit starts; if I cancel that prompt, do not start.
+
+4. When findings are fetched (wait mode, or later when I ask): summarize by
+   severity. For any high/critical — or when I ask what findings are about —
+   call `get_finding` for each of those ids and show evidence + recommended fix.
+   If there are no findings, tell me the audit came back clean.
+```
+
+## Install
+
+The server runs via `npx` — no global install needed. **Browser login is the default** (no token in
+config): the first tool call opens your browser to authorize this machine, then caches a credential in
+`~/.hakira/credentials.json` (chmod 600).
+
+### Cursor (one-click)
+
+Prefer Cursor’s official install deeplink (browser-login config, no token):
+
+[Add to Cursor](https://cursor.com/install-mcp?name=hakira&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImhha2lyYS1tY3AiXX0%3D)
+
+Or open the deeplink directly:
+
+```text
+cursor://anysphere.cursor-deeplink/mcp/install?name=hakira&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImhha2lyYS1tY3AiXX0%3D
+```
+
+Badge (for docs / landing pages):
+
+```html
+<a href="https://cursor.com/install-mcp?name=hakira&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImhha2lyYS1tY3AiXX0%3D">
+  <img alt="Add to Cursor" src="https://cursor.com/deeplink/mcp-install-dark.svg" />
+</a>
+```
+
+After install, enable the server in Cursor MCP settings if it appears disabled. Manual
+`.cursor/mcp.json` editing is still supported (table below).
+
+| Client | Config file | Fallback-token env syntax |
+|---|---|---|
+| Claude Code | `.mcp.json` (project) or `~/.claude/.mcp.json` | `${HAKIRA_TOKEN}` |
+| Cursor | `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` | `${env:HAKIRA_TOKEN}` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` (global only) | `${HAKIRA_TOKEN}` |
+
+**Primary (browser login):**
+
+```jsonc
+{ "mcpServers": { "hakira": { "type": "stdio", "command": "npx", "args": ["-y", "hakira-mcp"] } } }
+```
+
+**Headless / CI (no browser):** set a Personal Access Token instead. Mint one from the Hakira dashboard
+and expose it as `HAKIRA_TOKEN` — the server uses it directly and never opens a browser:
+
+```jsonc
+{
+  "mcpServers": {
+    "hakira": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "hakira-mcp"],
+      "env": { "HAKIRA_TOKEN": "${HAKIRA_TOKEN}" }
+    }
+  }
+}
+```
+
+On a headless machine with no `HAKIRA_TOKEN`, a tool call returns a structured `authorization_required`
+message with a URL to open elsewhere — it never hangs.
+
+## Commands
+
+- `hakira-mcp` — run the MCP server (what your client launches).
+- `hakira-mcp logout` — delete the cached credential (`~/.hakira/credentials.json`).
+
+## Configuration (env)
+
+| Var | Default | Purpose |
+|---|---|---|
+| `HAKIRA_TOKEN` | — | Personal Access Token. If set, used directly (fully headless; no browser, no cache). |
+| `HAKIRA_API_URL` | `https://app.hakira.io/api` | Control-Plane API base (Netlify rewrites `/api/*`→CP). |
+| `HAKIRA_WEB_URL` | `https://app.hakira.io` | App host for human SPA pages (e.g. `/billing`). |
+
+## Privacy — what leaves your machine
+
+`start_audit` uploads a ZIP of your **working tree** (honoring `.gitignore`). It never ships your real
+`.git`, and it strips a secret deny-list on top of `.gitignore`: `.env*`, `*.pem`, `*.key`, `id_rsa*`,
+`*.p12`, `*.pfx`, `.ssh/`, `.aws/`, `.npmrc`, `*.keystore`. Add more patterns in a `.hakiraignore` file
+at the repo root. Every run prints a one-line manifest (`uploading N files / M MB; excluded: …`) to
+stderr and in the tool result, so you see exactly what left the machine before the paid run.
+
+## Dev / e2e (local stack)
+
+Build the package, then point a client at the built binary against a local Control Plane:
+
+```jsonc
+{
+  "mcpServers": {
+    "hakira": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["packages/hakira-mcp/dist/index.js"],
+      "env": {
+        "HAKIRA_API_URL": "http://localhost:3000",
+        "HAKIRA_WEB_URL": "http://localhost:5173",
+        "HAKIRA_TOKEN": "<dev-seed PAT>"
+      }
+    }
+  }
+}
+```
+
+Restart the client session after each rebuild (no mid-session reload). Fast inner loop without a client:
+
+```bash
+npm run build -w packages/hakira-mcp
+npx @modelcontextprotocol/inspector --cli node packages/hakira-mcp/dist/index.js --method tools/list
+```
+
+## Develop
+
+```bash
+npm run build -w packages/hakira-mcp   # tsc → dist/ (+ chmod +x the bin)
+npm test  -w packages/hakira-mcp       # unit + stdio smoke (build first for the smoke test)
+```
+
+All logging goes to **stderr** — stdout is the JSON-RPC channel.

package/dist/auth/credentials.d.ts

@@ -0,0 +1,12 @@
+/** Delete the cached credential. Called by the 401 path (clear + re-auth once). */
+export declare function clearCredentials(): void;
+/**
+ * Resolve a bearer token:
+ *   1. HAKIRA_TOKEN env set  → use it (path B, fully headless, no cache write).
+ *   2. cached credential for the current apiUrl → use it.
+ *   3. else run browser login(), cache, return.
+ * May throw AuthorizationRequiredError (headless) — the tool wrapper surfaces it.
+ */
+export declare function resolveToken(): Promise<string>;
+/** `hakira-mcp logout` subcommand body. */
+export declare function logout(): void;

package/dist/auth/credentials.js

@@ -0,0 +1,61 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { config } from '../config.js';
+import { log } from '../log.js';
+import { login } from './loopback.js';
+// Credential cache: ~/.hakira/credentials.json (chmod 600). resolveToken() is the
+// SINGLE entry point every authed CpClient call goes through (ticket S4).
+const HAKIRA_DIR = join(homedir(), '.hakira');
+const CRED_PATH = join(HAKIRA_DIR, 'credentials.json');
+function readCredentials() {
+    try {
+        if (!existsSync(CRED_PATH))
+            return null;
+        const parsed = JSON.parse(readFileSync(CRED_PATH, 'utf8'));
+        if (typeof parsed.access_token === 'string' && typeof parsed.api_url === 'string') {
+            return { access_token: parsed.access_token, api_url: parsed.api_url };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCredentials(creds) {
+    mkdirSync(HAKIRA_DIR, { recursive: true, mode: 0o700 });
+    const json = JSON.stringify(creds, null, 2);
+    writeFileSync(CRED_PATH, json, { mode: 0o600 });
+    chmodSync(CRED_PATH, 0o600); // belt-and-suspenders: umask can widen the create mode
+}
+/** Delete the cached credential. Called by the 401 path (clear + re-auth once). */
+export function clearCredentials() {
+    try {
+        rmSync(CRED_PATH, { force: true });
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * Resolve a bearer token:
+ *   1. HAKIRA_TOKEN env set  → use it (path B, fully headless, no cache write).
+ *   2. cached credential for the current apiUrl → use it.
+ *   3. else run browser login(), cache, return.
+ * May throw AuthorizationRequiredError (headless) — the tool wrapper surfaces it.
+ */
+export async function resolveToken() {
+    if (config.envToken)
+        return config.envToken;
+    const cached = readCredentials();
+    if (cached && cached.api_url === config.apiUrl)
+        return cached.access_token;
+    const token = await login();
+    writeCredentials({ access_token: token, api_url: config.apiUrl });
+    return token;
+}
+/** `hakira-mcp logout` subcommand body. */
+export function logout() {
+    clearCredentials();
+    log.info('Logged out — cleared cached credentials at ~/.hakira/credentials.json');
+}

package/dist/auth/loopback.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The client could not open a browser (SSH / CI / headless / spawn failed).
+ * Surfaced upward as a structured MCP result, NEVER a hang (00 §7, gotcha G8).
+ */
+export declare class AuthorizationRequiredError extends Error {
+    readonly authorize_url: string;
+    readonly code = "authorization_required";
+    constructor(authorizeUrl: string, message?: string);
+}
+/**
+ * Headless predicate. `HAKIRA_TOKEN` is handled earlier (resolveToken short-
+ * circuits on it), so this checks only the no-browser conditions.
+ */
+export declare function isHeadless(env?: NodeJS.ProcessEnv): boolean;
+/** Spawn the OS browser opener. Returns false (never throws) if the spawn fails. */
+export declare function openBrowser(url: string): boolean;
+export interface LoginOptions {
+    env?: NodeJS.ProcessEnv;
+    openBrowser?: (url: string) => boolean;
+}
+/**
+ * Run the full browser-login flow and return a fresh `hk_pat_…`.
+ * Throws `AuthorizationRequiredError` (never hangs) when the machine is headless
+ * or the browser could not be opened.
+ */
+export declare function login(opts?: LoginOptions): Promise<string>;

package/dist/auth/loopback.js

@@ -0,0 +1,178 @@
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { config } from '../config.js';
+import { log } from '../log.js';
+// Browser-login: RFC 8252 native-app loopback + PKCE (client half of spec §6.1).
+// The CP routes GET /mcp/authorize + POST /mcp/token are ticket 03 (00 §3 rows 4–5).
+const LOGIN_TIMEOUT_MS = 5 * 60_000;
+/**
+ * The client could not open a browser (SSH / CI / headless / spawn failed).
+ * Surfaced upward as a structured MCP result, NEVER a hang (00 §7, gotcha G8).
+ */
+export class AuthorizationRequiredError extends Error {
+    authorize_url;
+    code = 'authorization_required';
+    constructor(authorizeUrl, message) {
+        super(message ??
+            'Visit this URL to authorize Hakira on this machine (or set HAKIRA_TOKEN for headless / CI).');
+        this.name = 'AuthorizationRequiredError';
+        this.authorize_url = authorizeUrl;
+    }
+}
+/**
+ * Headless predicate. `HAKIRA_TOKEN` is handled earlier (resolveToken short-
+ * circuits on it), so this checks only the no-browser conditions.
+ */
+export function isHeadless(env = process.env) {
+    if (env.SSH_CONNECTION)
+        return true;
+    if (env.CI)
+        return true;
+    if (process.platform === 'linux' && !env.DISPLAY)
+        return true;
+    return false;
+}
+/** Spawn the OS browser opener. Returns false (never throws) if the spawn fails. */
+export function openBrowser(url) {
+    try {
+        const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+        const child = spawn(cmd, [url], {
+            detached: true,
+            stdio: 'ignore',
+            shell: process.platform === 'win32', // `start` is a shell builtin
+        });
+        child.on('error', () => { }); // async spawn errors must not crash the process
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function startLoopback(expectedState) {
+    return new Promise((resolveStart) => {
+        let resolveCode;
+        let rejectCode;
+        const codePromise = new Promise((res, rej) => {
+            resolveCode = res;
+            rejectCode = rej;
+        });
+        const server = http.createServer((req, res) => {
+            const reqUrl = new URL(req.url ?? '/', 'http://127.0.0.1');
+            if (reqUrl.pathname !== '/callback') {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+            const code = reqUrl.searchParams.get('code');
+            const state = reqUrl.searchParams.get('state');
+            if (!code || state !== expectedState) {
+                res.writeHead(400, { 'content-type': 'text/html' });
+                res.end('<h1>Authorization failed</h1><p>Invalid state — please retry.</p>');
+                rejectCode(new Error('state mismatch (possible CSRF) — aborting login'));
+                return;
+            }
+            res.writeHead(200, { 'content-type': 'text/html' });
+            res.end(SUCCESS_HTML);
+            resolveCode(code);
+        });
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            const port = typeof addr === 'object' && addr ? addr.port : 0;
+            resolveStart({
+                port,
+                close: () => server.close(),
+                waitForCode: () => new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => {
+                        reject(new AuthorizationRequiredError(buildAuthorizeUrl({ code_challenge: '', redirect_uri: '', state: '' }), 'Login timed out after 5 minutes. Re-run the tool to try again, or set HAKIRA_TOKEN.'));
+                    }, LOGIN_TIMEOUT_MS);
+                    codePromise.then((c) => {
+                        clearTimeout(timer);
+                        resolve(c);
+                    }, (e) => {
+                        clearTimeout(timer);
+                        reject(e);
+                    });
+                }),
+            });
+        });
+    });
+}
+function buildAuthorizeUrl(p) {
+    // `/mcp/authorize` is a CP route (mcp-auth-routes.ts), reached under the `/api`
+    // base — NOT a web-app SPA page. Build it from apiUrl, same as /mcp/token below.
+    const u = new URL(`${config.apiUrl}/mcp/authorize`);
+    u.searchParams.set('response_type', 'code');
+    if (p.code_challenge)
+        u.searchParams.set('code_challenge', p.code_challenge);
+    u.searchParams.set('code_challenge_method', 'S256');
+    if (p.redirect_uri)
+        u.searchParams.set('redirect_uri', p.redirect_uri);
+    if (p.state)
+        u.searchParams.set('state', p.state);
+    return u.toString();
+}
+/**
+ * Run the full browser-login flow and return a fresh `hk_pat_…`.
+ * Throws `AuthorizationRequiredError` (never hangs) when the machine is headless
+ * or the browser could not be opened.
+ */
+export async function login(opts = {}) {
+    const env = opts.env ?? process.env;
+    const open = opts.openBrowser ?? openBrowser;
+    // 1. PKCE
+    const codeVerifier = randomBytes(32).toString('base64url');
+    const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url');
+    const state = randomBytes(16).toString('base64url');
+    // Environment-detected headless → no loopback, no browser. Surface a base
+    // authorize URL the human can open on a browser-capable machine.
+    if (isHeadless(env)) {
+        throw new AuthorizationRequiredError(buildAuthorizeUrl({ code_challenge: codeChallenge, redirect_uri: '', state }));
+    }
+    // 2. loopback listener (OS picks the port)
+    const loopback = await startLoopback(state);
+    const redirectUri = `http://127.0.0.1:${loopback.port}/callback`;
+    const authorizeUrl = buildAuthorizeUrl({
+        code_challenge: codeChallenge,
+        redirect_uri: redirectUri,
+        state,
+    });
+    try {
+        // 3. open browser; a spawn failure is treated as headless
+        const opened = open(authorizeUrl);
+        if (!opened) {
+            throw new AuthorizationRequiredError(authorizeUrl);
+        }
+        log.info('Opened browser for authorization — waiting for approval…');
+        // 4. receive code on loopback (state validated inside the handler)
+        const code = await loopback.waitForCode();
+        // 5. exchange at CP (row 5) — NO bearer, public PKCE
+        const res = await fetch(`${config.apiUrl}/mcp/token`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                grant_type: 'authorization_code',
+                code,
+                code_verifier: codeVerifier,
+                redirect_uri: redirectUri,
+            }),
+        });
+        if (!res.ok) {
+            const detail = await res.text().catch(() => '');
+            throw new Error(`Token exchange failed (${res.status}): ${detail || 'invalid_grant'}`);
+        }
+        const json = (await res.json());
+        if (!json.access_token)
+            throw new Error('Token exchange returned no access_token');
+        log.info('Authorization complete.');
+        return json.access_token;
+    }
+    finally {
+        loopback.close();
+    }
+}
+const SUCCESS_HTML = `<!doctype html><html><head><meta charset="utf-8"><title>Hakira</title>
+<style>body{font-family:system-ui,-apple-system,sans-serif;display:grid;place-items:center;height:100vh;margin:0;background:#0b0b0f;color:#e8e8ec}
+.card{text-align:center;padding:2rem 3rem}h1{font-size:1.3rem;margin:0 0 .5rem}p{opacity:.7}</style></head>
+<body><div class="card"><h1>Authorization complete</h1><p>You can close this tab and return to your terminal.</p></div></body></html>`;

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+export declare const config: {
+    /** Control-Plane HTTP base (the §3 endpoint table + /mcp/authorize + /mcp/token). */
+    readonly apiUrl: string;
+    /** App host for human-facing SPA pages (e.g. `/billing` top-up). NOT CP routes. */
+    readonly webUrl: string;
+    /** Fallback PAT (00 §2 path B — fully headless, no browser, no cache). */
+    readonly envToken: string | undefined;
+};

package/dist/config.js

@@ -0,0 +1,21 @@
+// Runtime configuration for hakira-mcp. Pure + env-driven (spec §7 "Configurable
+// endpoints"). Read once at import; overridable in every deployment via env.
+//
+// Prod topology (confirmed 2026-09-22, ticket 06 R1 resolved): Netlify serves the
+// web-app at `app.hakira.io` and rewrites `/api/*` → the Control-Plane Railway
+// service (`netlify.toml`, `/api` stripped). There is NO `api.hakira.io` — the CP
+// has no custom domain of its own. So:
+//   • apiUrl = `https://app.hakira.io/api` — CP API base. ALL CP routes live here,
+//     including the browser-login `/mcp/authorize` + `/mcp/token` (they are Hono
+//     routes on the CP, not web-app pages).
+//   • webUrl = `https://app.hakira.io` — the human app host. Only SPA pages live
+//     here (e.g. `/billing`, the Polar top-up page). NOT for CP routes.
+// e2e always overrides via HAKIRA_API_URL / HAKIRA_WEB_URL.
+export const config = {
+    /** Control-Plane HTTP base (the §3 endpoint table + /mcp/authorize + /mcp/token). */
+    apiUrl: (process.env.HAKIRA_API_URL ?? 'https://app.hakira.io/api').replace(/\/+$/, ''),
+    /** App host for human-facing SPA pages (e.g. `/billing` top-up). NOT CP routes. */
+    webUrl: (process.env.HAKIRA_WEB_URL ?? 'https://app.hakira.io').replace(/\/+$/, ''),
+    /** Fallback PAT (00 §2 path B — fully headless, no browser, no cache). */
+    envToken: process.env.HAKIRA_TOKEN,
+};

package/dist/git/exec.d.ts

@@ -0,0 +1,23 @@
+/** A caller-supplied revision that must never reach git argv (F8). */
+export declare class InvalidGitRefError extends Error {
+    constructor(ref: string, reason: string);
+}
+/**
+ * Gate for every caller-supplied revision. `ref` reaches us from the coding
+ * agent's tool call — i.e. from an LLM that may be summarizing untrusted repo
+ * content — so a leading `-` (or whitespace/control bytes, which git refs cannot
+ * contain anyway) is refused loudly rather than handed to git. Belt-and-braces
+ * with the `--end-of-options` separator that `runGit` inserts.
+ */
+export declare function assertSafeRef(ref: string): string;
+/**
+ * Run `git <args>` in `root`, return trimmed stdout, or `null` on any failure
+ * (non-git folder, missing git, non-zero exit). stderr is suppressed.
+ *
+ * An invalid `userRef` THROWS (it is a caller bug, not a git failure) — the tool
+ * layer surfaces it as a clean client-side error.
+ */
+export declare function tryGit(root: string, args: string[], userRef?: string): string | null;
+/** Raw (unparsed) `git` invocation returning a Buffer — for `git archive`. */
+export declare function gitBuffer(root: string, args: string[], userRef?: string): Buffer;
+export declare function isGitRepo(root: string): boolean;

package/dist/git/exec.js

@@ -0,0 +1,75 @@
+import { execFileSync } from 'node:child_process';
+/**
+ * git's own end-of-options marker. Everything after it is a revision/path, never
+ * an option — so a `--output=…`-shaped revision is rejected by git as a bad
+ * object name instead of being honoured as a flag.
+ */
+const END_OF_OPTIONS = '--end-of-options';
+/** A caller-supplied revision that must never reach git argv (F8). */
+export class InvalidGitRefError extends Error {
+    constructor(ref, reason) {
+        super(`Invalid git ref ${JSON.stringify(ref)}: ${reason}.`);
+        this.name = 'InvalidGitRefError';
+    }
+}
+/**
+ * Gate for every caller-supplied revision. `ref` reaches us from the coding
+ * agent's tool call — i.e. from an LLM that may be summarizing untrusted repo
+ * content — so a leading `-` (or whitespace/control bytes, which git refs cannot
+ * contain anyway) is refused loudly rather than handed to git. Belt-and-braces
+ * with the `--end-of-options` separator that `runGit` inserts.
+ */
+export function assertSafeRef(ref) {
+    if (ref.length === 0)
+        throw new InvalidGitRefError(ref, 'it is empty');
+    if (ref.startsWith('-')) {
+        throw new InvalidGitRefError(ref, 'a ref may not start with "-" (git would read it as an option)');
+    }
+    if (/[\s\u0000-\u001f\u007f]/.test(ref)) {
+        throw new InvalidGitRefError(ref, 'it contains whitespace or control characters');
+    }
+    return ref;
+}
+/**
+ * Build the argv for one git call. `fixedArgs` are literals owned by this
+ * package; `userRef` — the ONE channel through which caller data may reach git —
+ * is validated and placed after `--end-of-options`, always last.
+ */
+function buildArgv(fixedArgs, userRef) {
+    if (fixedArgs.includes(END_OF_OPTIONS)) {
+        throw new Error('pass a caller-supplied revision via the userRef argument, not in fixedArgs');
+    }
+    return userRef === undefined ? fixedArgs : [...fixedArgs, END_OF_OPTIONS, assertSafeRef(userRef)];
+}
+/**
+ * Run `git <args>` in `root`, return trimmed stdout, or `null` on any failure
+ * (non-git folder, missing git, non-zero exit). stderr is suppressed.
+ *
+ * An invalid `userRef` THROWS (it is a caller bug, not a git failure) — the tool
+ * layer surfaces it as a clean client-side error.
+ */
+export function tryGit(root, args, userRef) {
+    const argv = buildArgv(args, userRef);
+    try {
+        return execFileSync('git', argv, {
+            cwd: root,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            maxBuffer: 64 * 1024 * 1024,
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** Raw (unparsed) `git` invocation returning a Buffer — for `git archive`. */
+export function gitBuffer(root, args, userRef) {
+    return execFileSync('git', buildArgv(args, userRef), {
+        cwd: root,
+        stdio: ['ignore', 'pipe', 'ignore'],
+        maxBuffer: 1024 * 1024 * 1024,
+    });
+}
+export function isGitRepo(root) {
+    return tryGit(root, ['rev-parse', '--is-inside-work-tree']) === 'true';
+}

package/dist/git/metadata.d.ts

@@ -0,0 +1,20 @@
+export interface GitMetadata {
+    commit_sha: string | null;
+    ref: string | null;
+    is_dirty: boolean;
+    remote_url: string | null;
+}
+/** The user's REAL git state — `commit_sha` is HEAD (or the resolved `ref`). */
+export declare function captureGitMetadata(root: string, ref?: string): GitMetadata;
+/**
+ * Changed-file list for `scope:'diff'`. A WORKING-TREE diff vs the merge-base
+ * with the default branch — so it naturally includes uncommitted edits to
+ * tracked files (the point; sidesteps Semgrep's dirty-tree limit, spec §9).
+ * Shipped as a prioritization HINT, not a hard allowlist (00 §3 row 8).
+ */
+export declare function computeChangedFiles(root: string, opts?: {
+    ref?: string;
+    base?: string;
+}): string[];
+/** Human summary for sessions.target_gist (00 §5). */
+export declare function buildTargetGist(meta: GitMetadata, scope: 'full' | 'diff', changedFiles: string[]): string;