@pungoyal/kite-cli 0.1.0

package/dist/core/auth.js

@@ -0,0 +1,220 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { ExitCode, KiteCliError, UsageError } from './errors.js';
+import { registerSecret } from './redact.js';
+/**
+ * The Kite Connect login handshake.
+ *
+ *   1. Open https://kite.zerodha.com/connect/login?v=3&api_key=...
+ *   2. User authenticates in their browser (including mandatory TOTP 2FA).
+ *   3. Kite redirects to the registered URL with ?request_token=...
+ *   4. POST /session/token with checksum = SHA256(api_key + request_token + api_secret)
+ *
+ * The CLI never sees the user's password or TOTP. We deliberately do not offer
+ * to store a TOTP seed: holding the 2FA secret alongside the API secret would
+ * collapse both factors into one, which is precisely what the SEBI 2FA mandate
+ * exists to prevent.
+ */
+/** checksum = SHA256(api_key + request_token + api_secret), hex. */
+export function computeChecksum(apiKey, requestToken, apiSecret) {
+    return createHash('sha256').update(`${apiKey}${requestToken}${apiSecret}`).digest('hex');
+}
+/**
+ * Postback checksum — note this is a DIFFERENT concatenation from the login
+ * checksum: SHA256(order_id + order_timestamp + api_secret).
+ */
+export function computePostbackChecksum(orderId, orderTimestamp, apiSecret) {
+    return createHash('sha256').update(`${orderId}${orderTimestamp}${apiSecret}`).digest('hex');
+}
+export function verifyPostbackChecksum(received, orderId, orderTimestamp, apiSecret) {
+    return safeCompare(received, computePostbackChecksum(orderId, orderTimestamp, apiSecret));
+}
+/**
+ * Constant-time string comparison that cannot throw.
+ *
+ * `timingSafeEqual` requires equal BYTE lengths and throws RangeError
+ * otherwise, so the length guard must be on the encoded buffers — not on
+ * `String.length`, which counts UTF-16 code units and can match while the byte
+ * lengths differ. Both call sites compare attacker-influenced input.
+ */
+export function safeCompare(a, b) {
+    const bufA = Buffer.from(a, 'utf8');
+    const bufB = Buffer.from(b, 'utf8');
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}
+export function buildLoginUrl(opts) {
+    const url = new URL(opts.endpoints.login);
+    // v=3 is required for a v3 session.
+    url.searchParams.set('v', '3');
+    url.searchParams.set('api_key', opts.apiKey);
+    // redirect_params is echoed back verbatim on the redirect, which gives us a
+    // CSRF state parameter even though Kite has no first-class `state`.
+    url.searchParams.set('redirect_params', `state=${opts.state}`);
+    return url.toString();
+}
+export function generateState() {
+    return randomBytes(16).toString('hex');
+}
+/**
+ * Run a one-shot loopback HTTP server to capture the request_token.
+ *
+ * Kite's developer console requires HTTPS for redirect URLs but explicitly
+ * permits plain http:// for localhost and 127.0.0.1, which is the standard
+ * pattern for native apps. We bind to 127.0.0.1 specifically (never 0.0.0.0),
+ * so the callback is not reachable from the network.
+ */
+export function waitForCallback(opts) {
+    let server;
+    let settled = false;
+    let timer;
+    const close = () => {
+        if (timer)
+            clearTimeout(timer);
+        server?.close();
+        server?.closeAllConnections?.();
+    };
+    const promise = new Promise((resolve, reject) => {
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            close();
+            fn();
+        };
+        const handler = (req, res) => {
+            const url = new URL(req.url ?? '/', `http://127.0.0.1:${opts.port}`);
+            if (url.pathname !== opts.path) {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end('Not found');
+                return;
+            }
+            const status = url.searchParams.get('status');
+            const requestToken = url.searchParams.get('request_token');
+            const receivedState = url.searchParams.get('state');
+            // Constant-time state comparison. A mismatch means this callback did not
+            // originate from the login we started.
+            //
+            // The length guard compares BYTE lengths, not string lengths: a string of
+            // 32 multi-byte characters has the same `.length` as our 32-char hex
+            // state but a different Buffer size, and timingSafeEqual throws
+            // RangeError on mismatched buffers. That would crash the callback server
+            // on input an attacker fully controls.
+            const stateOk = receivedState !== null && safeCompare(receivedState, opts.state);
+            if (!stateOk) {
+                respondHtml(res, 400, 'Login failed', 'State mismatch — this callback did not come from the login this CLI started.');
+                settle(() => reject(new KiteCliError('Login callback failed a CSRF state check.', ExitCode.Auth, 'Run `kite login` again, and complete it in a single browser session.')));
+                return;
+            }
+            if (status !== 'success' || !requestToken) {
+                respondHtml(res, 400, 'Login failed', 'Kite did not return a request token.');
+                settle(() => reject(new KiteCliError('Kite did not return a request token.', ExitCode.Auth)));
+                return;
+            }
+            registerSecret(requestToken);
+            respondHtml(res, 200, 'Logged in', 'You can close this tab and return to your terminal.');
+            settle(() => resolve({ requestToken }));
+        };
+        server = createServer(handler);
+        server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                settle(() => reject(new UsageError(`Port ${opts.port} is already in use.`, 'Set a different port with `kite config set redirectPort <port>`, and update the redirect URL in your Kite developer console to match.')));
+                return;
+            }
+            settle(() => reject(err));
+        });
+        server.listen(opts.port, '127.0.0.1');
+        const timeoutMs = opts.timeoutMs ?? 300_000;
+        timer = setTimeout(() => {
+            settle(() => reject(new KiteCliError(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for the browser callback.`, ExitCode.Auth, 'Run `kite login --manual` to paste the request token by hand instead.')));
+        }, timeoutMs);
+        timer.unref?.();
+    });
+    return { promise, close };
+}
+function respondHtml(res, status, title, detail) {
+    const body = `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>${escapeHtml(title)}</title>
+<style>
+  body { font-family: ui-sans-serif, system-ui, -apple-system, sans-serif; display: grid;
+         place-items: center; min-height: 100vh; margin: 0; background: #0f1115; color: #e6e8eb; }
+  .card { text-align: center; padding: 2.5rem 3rem; border-radius: 12px; background: #171a21;
+          box-shadow: 0 8px 32px rgba(0,0,0,.4); }
+  h1 { font-size: 1.25rem; margin: 0 0 .5rem; }
+  p { margin: 0; color: #9aa4b2; font-size: .925rem; }
+</style></head>
+<body><div class="card"><h1>${escapeHtml(title)}</h1><p>${escapeHtml(detail)}</p></div></body>
+</html>`;
+    res.writeHead(status, {
+        'Content-Type': 'text/html; charset=utf-8',
+        // This page is generated locally and references nothing external.
+        'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'",
+        'Cache-Control': 'no-store',
+        'Referrer-Policy': 'no-referrer',
+    });
+    res.end(body);
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => {
+        switch (char) {
+            case '&':
+                return '&amp;';
+            case '<':
+                return '&lt;';
+            case '>':
+                return '&gt;';
+            case '"':
+                return '&quot;';
+            default:
+                return '&#39;';
+        }
+    });
+}
+export function redirectUrlFor(port, path) {
+    return `http://127.0.0.1:${port}${path}`;
+}
+/**
+ * Open a URL in the user's default browser.
+ *
+ * The URL is passed as an argv element to a fixed binary, never through a
+ * shell, so a crafted URL cannot become command injection.
+ */
+export async function openBrowser(url) {
+    const { spawn } = await import('node:child_process');
+    let command;
+    let args;
+    switch (process.platform) {
+        case 'darwin':
+            command = 'open';
+            args = [url];
+            break;
+        case 'win32':
+            // start is a cmd builtin; the empty string is the window-title argument,
+            // without which a quoted URL is treated as the title.
+            command = 'cmd';
+            args = ['/c', 'start', '', url];
+            break;
+        default:
+            command = 'xdg-open';
+            args = [url];
+            break;
+    }
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(command, args, {
+                stdio: 'ignore',
+                detached: true,
+                shell: false,
+            });
+            child.on('error', () => resolve(false));
+            child.unref();
+            // spawn errors surface asynchronously; give it a moment before claiming success.
+            setTimeout(() => resolve(true), 250).unref?.();
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}

package/dist/core/client.d.ts

@@ -0,0 +1,76 @@
+import { type Dispatcher } from 'undici';
+import { z } from 'zod';
+import type { Endpoints } from './config.js';
+import { type RateCategory, RateLimiter } from './ratelimit.js';
+/**
+ * HTTP client for the Kite Connect v3 API.
+ *
+ * Transport notes that shaped this file:
+ *
+ *  - Kite is form-encoded everywhere EXCEPT /margins/* and /charges/orders,
+ *    which take JSON bodies. `json` vs `form` on RequestOptions selects.
+ *  - `X-Kite-Version: 3` is mandatory on every request.
+ *  - The sandbox serves all routes under an /oms prefix except /instruments.
+ *  - GTT passes JSON-encoded strings *inside form fields*, not a JSON body.
+ */
+export interface RequestOptions<S extends z.ZodType> {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    path: string;
+    category?: RateCategory;
+    query?: Record<string, string | number | boolean | undefined | string[]>;
+    /**
+     * Form fields. An array value is encoded as a REPEATED field
+     * (`isin=A&isin=B`), which is how Kite expects multi-valued form input —
+     * notably the holdings authorisation endpoint.
+     */
+    form?: Record<string, string | number | boolean | string[] | undefined>;
+    json?: unknown;
+    schema: S;
+    signal?: AbortSignal | undefined;
+    /** Skip the /oms sandbox prefix. Only /instruments needs this. */
+    noPrefix?: boolean;
+    /** Per-request timeout override, milliseconds. */
+    timeoutMs?: number;
+}
+export interface ClientOptions {
+    apiKey: string;
+    accessToken?: string | undefined;
+    endpoints: Endpoints;
+    limiter?: RateLimiter;
+    /** Print redacted request/response diagnostics to stderr. */
+    debug?: boolean;
+    onDebug?: (message: string) => void;
+    timeoutMs?: number;
+}
+/** Test hook: swap the dispatcher, e.g. for an undici MockAgent. */
+export declare function setDispatcher(d: Dispatcher | undefined): void;
+export declare class KiteClient {
+    readonly apiKey: string;
+    readonly endpoints: Endpoints;
+    readonly limiter: RateLimiter;
+    private accessToken;
+    private readonly debug;
+    private readonly onDebug;
+    private readonly timeoutMs;
+    constructor(opts: ClientOptions);
+    setAccessToken(token: string | undefined): void;
+    hasSession(): boolean;
+    private buildUrl;
+    private headers;
+    /** Perform a request and validate the `data` payload against `schema`. */
+    request<S extends z.ZodType>(opts: RequestOptions<S>): Promise<z.infer<S>>;
+    private toNetworkError;
+    private handleResponse;
+    /**
+     * Fetch a raw (non-JSON) body. Used only for the instrument dump, which is a
+     * gzipped CSV rather than an API envelope.
+     */
+    requestText(opts: {
+        path: string;
+        signal?: AbortSignal | undefined;
+        noPrefix?: boolean;
+        timeoutMs?: number;
+    }): Promise<string>;
+    /** Redacted diagnostics for `--debug`. Never includes the Authorization header. */
+    describe(): Record<string, unknown>;
+}

package/dist/core/client.js

@@ -0,0 +1,285 @@
+import { Agent, fetch, interceptors } from 'undici';
+import { z } from 'zod';
+import { ExitCode, hintForApiError, KiteApiError, KiteCliError, NetworkError } from './errors.js';
+import { RateLimiter } from './ratelimit.js';
+import { redact, redactString, registerSecret } from './redact.js';
+import { EnvelopeSchema, ErrorEnvelopeSchema } from './schemas.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * A shared dispatcher with sane timeouts.
+ *
+ * undici's defaults are far too permissive for a CLI: headersTimeout and
+ * bodyTimeout both default to 300 seconds, which would leave a user staring at
+ * a hung terminal.
+ *
+ * The retry policy is deliberately narrow. undici retries GET, HEAD, OPTIONS,
+ * PUT, DELETE and TRACE by default — but in this API PUT is "modify order" and
+ * DELETE is "cancel order". Kite caps modifications at 25 per order, and there
+ * is no idempotency key anywhere in the API, so an automatic retry of a mutating
+ * verb is a real-money bug. We retry reads only; every write is retried
+ * deliberately by the caller, or not at all.
+ */
+function createDispatcher() {
+    return new Agent({
+        connectTimeout: 5_000,
+        headersTimeout: 15_000,
+        bodyTimeout: 30_000,
+        keepAliveTimeout: 10_000,
+        connections: 8,
+    }).compose(interceptors.retry({
+        maxRetries: 3,
+        minTimeout: 300,
+        maxTimeout: 5_000,
+        timeoutFactor: 2,
+        retryAfter: true,
+        methods: ['GET', 'HEAD'],
+        statusCodes: [429, 500, 502, 503, 504],
+        errorCodes: ['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN', 'ENETUNREACH', 'EPIPE'],
+    }));
+}
+let sharedDispatcher;
+function dispatcher() {
+    sharedDispatcher ??= createDispatcher();
+    return sharedDispatcher;
+}
+/** Test hook: swap the dispatcher, e.g. for an undici MockAgent. */
+export function setDispatcher(d) {
+    sharedDispatcher = d;
+}
+export class KiteClient {
+    apiKey;
+    endpoints;
+    limiter;
+    accessToken;
+    debug;
+    onDebug;
+    timeoutMs;
+    constructor(opts) {
+        this.apiKey = opts.apiKey;
+        this.accessToken = opts.accessToken;
+        this.endpoints = opts.endpoints;
+        this.limiter = opts.limiter ?? new RateLimiter();
+        this.debug = opts.debug ?? false;
+        this.onDebug = opts.onDebug ?? ((m) => process.stderr.write(`${m}\n`));
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        // Register here rather than relying on the credential store to have done
+        // it. A token can reach the client by other routes — a library consumer
+        // constructing it directly, or a future code path — and an unregistered
+        // token survives redaction if it turns up somewhere no pattern matches
+        // (notably a Kite error message that echoes our input back).
+        registerSecret(this.accessToken);
+    }
+    setAccessToken(token) {
+        this.accessToken = token;
+        registerSecret(token);
+    }
+    hasSession() {
+        return Boolean(this.accessToken);
+    }
+    buildUrl(path, query, noPrefix) {
+        const prefix = noPrefix ? '' : this.endpoints.routePrefix;
+        const url = new URL(`${this.endpoints.api}${prefix}${path}`);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value === undefined)
+                    continue;
+                if (Array.isArray(value)) {
+                    // Repeated params, e.g. ?i=NSE:INFY&i=NSE:TCS
+                    for (const item of value)
+                        url.searchParams.append(key, item);
+                }
+                else {
+                    url.searchParams.append(key, String(value));
+                }
+            }
+        }
+        return url;
+    }
+    headers(extra) {
+        const headers = {
+            'X-Kite-Version': '3',
+            Accept: 'application/json',
+            'User-Agent': 'kite-cli',
+            ...extra,
+        };
+        if (this.accessToken) {
+            // NEVER log this header. It is `token <api_key>:<access_token>` and is
+            // attached to every request, making it the single likeliest leak path.
+            headers['Authorization'] = `token ${this.apiKey}:${this.accessToken}`;
+        }
+        return headers;
+    }
+    /** Perform a request and validate the `data` payload against `schema`. */
+    async request(opts) {
+        const category = opts.category ?? 'default';
+        await this.limiter.acquire(category, opts.signal);
+        const url = this.buildUrl(opts.path, opts.query, opts.noPrefix ?? false);
+        let body;
+        const extraHeaders = {};
+        if (opts.json !== undefined) {
+            body = JSON.stringify(opts.json);
+            extraHeaders['Content-Type'] = 'application/json';
+        }
+        else if (opts.form) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(opts.form)) {
+                if (value === undefined)
+                    continue;
+                if (Array.isArray(value)) {
+                    for (const item of value)
+                        params.append(key, item);
+                }
+                else {
+                    params.append(key, String(value));
+                }
+            }
+            body = params.toString();
+            extraHeaders['Content-Type'] = 'application/x-www-form-urlencoded';
+        }
+        const timeout = AbortSignal.timeout(opts.timeoutMs ?? this.timeoutMs);
+        // Compose the user's Ctrl-C signal with our deadline so both work.
+        const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
+        if (this.debug) {
+            this.onDebug(`→ ${opts.method} ${redactString(url.toString())}${body ? ` body=${redactString(body)}` : ''}`);
+        }
+        let response;
+        try {
+            // Use undici's own `fetch`, not the global one. The global fetch only
+            // began honouring the per-request `dispatcher` option in recent Node
+            // releases; on older supported versions it silently ignores it and uses
+            // the default agent — which would drop our timeouts and retry policy at
+            // runtime, and bypass MockAgent in tests. undici's fetch always honours
+            // it, so behaviour is identical on every supported Node version.
+            response = await fetch(url, {
+                method: opts.method,
+                headers: this.headers(extraHeaders),
+                body,
+                signal,
+                dispatcher: dispatcher(),
+            });
+        }
+        catch (err) {
+            throw this.toNetworkError(err, opts.method, url);
+        }
+        const text = await response.text();
+        if (this.debug) {
+            this.onDebug(`← ${response.status} ${redactString(text.slice(0, 2000))}`);
+        }
+        return this.handleResponse(response, text, opts.schema, url);
+    }
+    toNetworkError(err, method, url) {
+        if (err instanceof Error && err.name === 'TimeoutError') {
+            return new NetworkError(`Request timed out: ${method} ${redactString(url.pathname)}`, method === 'POST'
+                ? 'The order may still have been received. Run `kite orders list` to check before retrying.'
+                : 'Check your connection and retry.');
+        }
+        if (err instanceof Error && err.name === 'AbortError') {
+            return new KiteCliError('Cancelled.', ExitCode.Aborted);
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return new NetworkError(`Could not reach Kite: ${redactString(message)}`, 'Check your network connection.');
+    }
+    handleResponse(response, text, schema, url) {
+        let payload;
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            // A non-JSON body means an infrastructure error page, not the API.
+            if (!response.ok) {
+                throw new KiteApiError({
+                    message: `Kite returned HTTP ${response.status} with a non-JSON body.`,
+                    status: response.status,
+                    errorType: 'GeneralException',
+                    hint: hintForApiError(response.status, 'GeneralException'),
+                });
+            }
+            throw new KiteApiError({
+                message: `Could not parse Kite's response for ${redactString(url.pathname)}.`,
+                status: response.status,
+                errorType: 'DataException',
+            });
+        }
+        if (!response.ok) {
+            const parsed = ErrorEnvelopeSchema.safeParse(payload);
+            const message = parsed.success ? parsed.data.message : `HTTP ${response.status}`;
+            const errorType = parsed.success ? parsed.data.error_type : 'GeneralException';
+            throw new KiteApiError({
+                message: redactString(message),
+                status: response.status,
+                errorType,
+                hint: hintForApiError(response.status, errorType),
+            });
+        }
+        const envelope = EnvelopeSchema.safeParse(payload);
+        if (!envelope.success) {
+            throw new KiteApiError({
+                message: `Unexpected response shape from ${redactString(url.pathname)}.`,
+                status: response.status,
+                errorType: 'DataException',
+            });
+        }
+        // Kite can return HTTP 200 with status:"error" in the envelope.
+        if (envelope.data.status === 'error') {
+            const errorType = envelope.data.error_type ?? 'GeneralException';
+            throw new KiteApiError({
+                message: redactString(envelope.data.message ?? 'Unknown error'),
+                status: response.status,
+                errorType,
+                hint: hintForApiError(response.status, errorType),
+            });
+        }
+        const result = schema.safeParse(envelope.data.data);
+        if (!result.success) {
+            throw new KiteApiError({
+                message: `Kite's response did not match the expected shape for ${redactString(url.pathname)}.\n` +
+                    z.prettifyError(result.error),
+                status: response.status,
+                errorType: 'DataException',
+                hint: 'This usually means the API changed. Please open an issue at https://github.com/pungoyal/kite-cli/issues',
+            });
+        }
+        return result.data;
+    }
+    /**
+     * Fetch a raw (non-JSON) body. Used only for the instrument dump, which is a
+     * gzipped CSV rather than an API envelope.
+     */
+    async requestText(opts) {
+        await this.limiter.acquire('default', opts.signal);
+        const url = this.buildUrl(opts.path, undefined, opts.noPrefix ?? false);
+        const timeout = AbortSignal.timeout(opts.timeoutMs ?? 120_000);
+        const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'GET',
+                headers: this.headers(),
+                signal,
+                // undici's fetch (see request()) so the dispatcher is always honoured.
+                dispatcher: dispatcher(),
+            });
+        }
+        catch (err) {
+            throw this.toNetworkError(err, 'GET', url);
+        }
+        if (!response.ok) {
+            throw new KiteApiError({
+                message: `Could not download ${redactString(url.pathname)} (HTTP ${response.status}).`,
+                status: response.status,
+                errorType: 'GeneralException',
+                hint: hintForApiError(response.status, 'GeneralException'),
+            });
+        }
+        // fetch transparently decompresses gzip via Content-Encoding.
+        return response.text();
+    }
+    /** Redacted diagnostics for `--debug`. Never includes the Authorization header. */
+    describe() {
+        return redact({
+            apiKey: this.apiKey,
+            hasSession: this.hasSession(),
+            endpoints: this.endpoints,
+        });
+    }
+}