@pungoyal/kite-cli 0.1.0

package/dist/core/ratelimit.js

@@ -0,0 +1,196 @@
+/**
+ * Client-side rate limiting, per endpoint category.
+ *
+ * Kite's published limits (https://kite.trade/docs/connect/v3/exceptions/):
+ *
+ *   Quote            1 req/sec     <- the binding constraint in practice
+ *   Historical       3 req/sec
+ *   Order placement  10 req/sec, 400/min, 5000/day
+ *   Everything else  10 req/sec
+ *
+ * The quote limit is what bites first: a naive per-symbol loop over a watchlist
+ * is ~1000x slower than one batched /quote/ltp call, which accepts 1000
+ * instruments. Batching is handled at the client layer; this module only
+ * enforces pacing.
+ */
+import { ExitCode, KiteCliError } from './errors.js';
+const LIMITS = {
+    quote: { perSecond: 1 },
+    historical: { perSecond: 3 },
+    order: { perSecond: 10 },
+    default: { perSecond: 10 },
+};
+/**
+ * A token bucket that refills continuously.
+ *
+ * Deliberately sized at capacity 1 burst beyond the sustained rate: Kite
+ * enforces its limits server-side with little tolerance, and a large burst
+ * allowance just converts a clean local wait into a 429.
+ */
+class TokenBucket {
+    tokens;
+    lastRefill;
+    ratePerMs;
+    capacity;
+    now;
+    queue = Promise.resolve();
+    constructor(perSecond, now) {
+        this.now = now;
+        this.ratePerMs = perSecond / 1000;
+        this.capacity = perSecond;
+        this.tokens = perSecond;
+        this.lastRefill = now();
+    }
+    refill() {
+        const t = this.now();
+        const elapsed = t - this.lastRefill;
+        if (elapsed > 0) {
+            this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.ratePerMs);
+            this.lastRefill = t;
+        }
+    }
+    /** Milliseconds until a token is available. */
+    delayForToken() {
+        this.refill();
+        if (this.tokens >= 1)
+            return 0;
+        return Math.ceil((1 - this.tokens) / this.ratePerMs);
+    }
+    /**
+     * Wait until a token is available, then consume it.
+     *
+     * Calls are serialised through a promise chain so that N concurrent callers
+     * are spaced correctly rather than all observing the same available token.
+     */
+    async acquire(signal) {
+        const run = this.queue.then(async () => {
+            for (;;) {
+                const wait = this.delayForToken();
+                if (wait === 0)
+                    break;
+                await sleep(wait, signal);
+            }
+            this.tokens -= 1;
+        });
+        // Keep the chain alive even if this acquisition rejects (e.g. aborted).
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new Error('Aborted'));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason ?? new Error('Aborted'));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+export const ORDER_LIMITS = {
+    perMinute: 400,
+    perDay: 5000,
+    /** Kite rejects further modifications after this many on one order. */
+    modificationsPerOrder: 25,
+};
+export class RateLimiter {
+    buckets = new Map();
+    orderCounters;
+    now;
+    constructor(now = () => Date.now()) {
+        this.now = now;
+        for (const [category, config] of Object.entries(LIMITS)) {
+            this.buckets.set(category, new TokenBucket(config.perSecond, now));
+        }
+        this.orderCounters = {
+            minuteWindowStart: now(),
+            minuteCount: 0,
+            dayKey: istDayKey(now()),
+            dayCount: 0,
+        };
+    }
+    async acquire(category, signal) {
+        // Enforce the documented order caps BEFORE consuming a token, so a runaway
+        // loop inside a long-running process is stopped locally with a clear error
+        // rather than firing an order Kite will reject with a 429 (which still
+        // counts against the cap).
+        if (category === 'order')
+            this.assertOrderCapacity();
+        const bucket = this.buckets.get(category) ?? this.buckets.get('default');
+        await bucket.acquire(signal);
+        if (category === 'order')
+            this.countOrder();
+    }
+    /**
+     * Roll the per-minute and per-IST-day order windows forward if they have
+     * elapsed. Shared by the pre-flight cap check and the post-acquire counter so
+     * the two never disagree about which window an order falls in.
+     */
+    rollOrderWindows() {
+        const t = this.now();
+        if (t - this.orderCounters.minuteWindowStart >= 60_000) {
+            this.orderCounters.minuteWindowStart = t;
+            this.orderCounters.minuteCount = 0;
+        }
+        const today = istDayKey(t);
+        if (today !== this.orderCounters.dayKey) {
+            this.orderCounters.dayKey = today;
+            this.orderCounters.dayCount = 0;
+        }
+    }
+    /**
+     * Refuse to place another order once a documented cap is reached.
+     *
+     * These counters reset each process run, so they cannot be authoritative
+     * across invocations of a short-lived CLI — this is a backstop against a
+     * runaway loop inside ONE long-running process (`kite watch`, a scripted
+     * batch, a library embedder), not a mirror of Zerodha's server-side
+     * accounting.
+     */
+    assertOrderCapacity() {
+        this.rollOrderWindows();
+        if (this.orderCounters.dayCount >= ORDER_LIMITS.perDay) {
+            throw new KiteCliError(`This process has placed ${ORDER_LIMITS.perDay} orders — Kite's documented daily cap. It resets at the next IST trading day.`, ExitCode.RateLimit);
+        }
+        if (this.orderCounters.minuteCount >= ORDER_LIMITS.perMinute) {
+            throw new KiteCliError(`This process has placed ${ORDER_LIMITS.perMinute} orders in the last minute — Kite's documented per-minute cap. Slow down and retry shortly.`, ExitCode.RateLimit);
+        }
+    }
+    /**
+     * Track the 400/min and 5000/day order caps (see {@link assertOrderCapacity},
+     * which enforces them before the order is sent).
+     */
+    countOrder() {
+        this.rollOrderWindows();
+        this.orderCounters.minuteCount += 1;
+        this.orderCounters.dayCount += 1;
+    }
+    /** Orders placed by this process in the current minute / IST day. */
+    orderUsage() {
+        return {
+            minute: this.orderCounters.minuteCount,
+            day: this.orderCounters.dayCount,
+        };
+    }
+    /** True if this process is approaching a documented order cap. */
+    nearOrderLimit() {
+        return (this.orderCounters.minuteCount >= ORDER_LIMITS.perMinute * 0.9 ||
+            this.orderCounters.dayCount >= ORDER_LIMITS.perDay * 0.9);
+    }
+}
+/** IST calendar day key (YYYY-MM-DD). Kite's day boundaries are IST, not UTC. */
+function istDayKey(epochMs) {
+    return new Intl.DateTimeFormat('en-CA', {
+        timeZone: 'Asia/Kolkata',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    }).format(new Date(epochMs));
+}

package/dist/core/redact.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Secret redaction for anything that can reach a log, a terminal, or a crash
+ * report.
+ *
+ * The two highest-risk leak paths in this codebase, per the Kite API surface:
+ *
+ *   1. The `Authorization` header — it is literally `token <api_key>:<access_token>`
+ *      and is attached to every single request.
+ *   2. The WebSocket URL — `access_token` is a *query parameter*, so it appears
+ *      verbatim in `ws` error messages and stack traces.
+ *
+ * Everything printed in verbose/debug mode must pass through `redact()`.
+ * `test/redact.test.ts` asserts that a known token never survives.
+ */
+/**
+ * Register a literal secret value so it is scrubbed wherever it appears, even
+ * in contexts the pattern rules below do not anticipate (a Kite error message
+ * that echoes input, a third-party stack trace).
+ *
+ * Short values are ignored: scrubbing a 4-character string would mangle
+ * unrelated output for no security benefit.
+ */
+export declare function registerSecret(value: string | undefined | null): void;
+/** Test-only: drop all registered secrets. */
+export declare function clearRegisteredSecrets(): void;
+export declare const REDACTED = "[redacted]";
+/** Redact secrets from a string. Safe to call on arbitrary text. */
+export declare function redactString(input: string): string;
+/**
+ * Deeply redact a value of any shape. Objects are walked by key (secret keys
+ * have their values replaced wholesale) and strings are pattern-scrubbed.
+ *
+ * Cycles are handled; depth is capped to keep this cheap on the hot path.
+ */
+export declare function redact(value: unknown, depth?: number, seen?: WeakSet<object>): unknown;
+/**
+ * Redact credentials from a URL's query string.
+ *
+ * This exists specifically for the ticker: `wss://ws.kite.trade?api_key=..&access_token=..`
+ * must never be printed or embedded in an error. `api_key` is kept (it is
+ * semi-public and useful for debugging); `access_token` is not.
+ */
+export declare function redactUrl(url: string | URL): string;
+/**
+ * Mask a secret for display, showing only enough to identify which credential
+ * it is. Used by `kite config show` and login confirmations.
+ */
+export declare function maskSecret(value: string, visible?: number): string;

package/dist/core/redact.js

@@ -0,0 +1,181 @@
+/**
+ * Secret redaction for anything that can reach a log, a terminal, or a crash
+ * report.
+ *
+ * The two highest-risk leak paths in this codebase, per the Kite API surface:
+ *
+ *   1. The `Authorization` header — it is literally `token <api_key>:<access_token>`
+ *      and is attached to every single request.
+ *   2. The WebSocket URL — `access_token` is a *query parameter*, so it appears
+ *      verbatim in `ws` error messages and stack traces.
+ *
+ * Everything printed in verbose/debug mode must pass through `redact()`.
+ * `test/redact.test.ts` asserts that a known token never survives.
+ */
+/** Values registered at runtime for exact-match scrubbing. */
+const registeredSecrets = new Set();
+/**
+ * Register a literal secret value so it is scrubbed wherever it appears, even
+ * in contexts the pattern rules below do not anticipate (a Kite error message
+ * that echoes input, a third-party stack trace).
+ *
+ * Short values are ignored: scrubbing a 4-character string would mangle
+ * unrelated output for no security benefit.
+ */
+export function registerSecret(value) {
+    if (typeof value === 'string' && value.length >= 8) {
+        registeredSecrets.add(value);
+    }
+}
+/** Test-only: drop all registered secrets. */
+export function clearRegisteredSecrets() {
+    registeredSecrets.clear();
+}
+export const REDACTED = '[redacted]';
+/** Key names whose values are always secret, matched case-insensitively. */
+const SECRET_KEYS = new Set([
+    'authorization',
+    'api_secret',
+    'apisecret',
+    'access_token',
+    'accesstoken',
+    'request_token',
+    'requesttoken',
+    'refresh_token',
+    'refreshtoken',
+    'public_token',
+    'publictoken',
+    'enctoken',
+    'checksum',
+    'password',
+    'totp',
+    'x-kite-session',
+]);
+const PATTERNS = [
+    // Authorization: token api_key:access_token  (header form, any casing)
+    [/\b(authorization\s*:\s*)(?:token\s+)?\S+/gi, `$1${REDACTED}`],
+    // token <key>:<secret> appearing bare, e.g. inside a serialized headers object
+    [/\btoken\s+[A-Za-z0-9_-]{4,}:[A-Za-z0-9_-]{6,}/g, `token ${REDACTED}`],
+    // Any secret-ish key in a query string or form body: access_token=xxxx
+    [
+        /\b(api_secret|access_token|request_token|refresh_token|public_token|enctoken|checksum|password|totp)=[^&\s"']+/gi,
+        `$1=${REDACTED}`,
+    ],
+    // JSON form: "access_token": "xxxx"
+    [
+        /("(?:api_secret|access_token|request_token|refresh_token|public_token|enctoken|checksum|password|totp)"\s*:\s*)"[^"]*"/gi,
+        `$1"${REDACTED}"`,
+    ],
+];
+/** Redact secrets from a string. Safe to call on arbitrary text. */
+export function redactString(input) {
+    let out = input;
+    for (const [pattern, replacement] of PATTERNS) {
+        out = out.replace(pattern, replacement);
+    }
+    // Exact-match pass last, so registered values are caught even where no
+    // pattern applied.
+    for (const secret of registeredSecrets) {
+        if (secret && out.includes(secret)) {
+            out = out.split(secret).join(REDACTED);
+        }
+    }
+    return out;
+}
+/**
+ * Deeply redact a value of any shape. Objects are walked by key (secret keys
+ * have their values replaced wholesale) and strings are pattern-scrubbed.
+ *
+ * Cycles are handled; depth is capped to keep this cheap on the hot path.
+ */
+export function redact(value, depth = 0, seen = new WeakSet()) {
+    if (depth > 12)
+        return '[truncated]';
+    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((item) => redact(item, depth + 1, seen));
+    }
+    if (value instanceof Error) {
+        return {
+            name: value.name,
+            message: redactString(value.message),
+            stack: value.stack ? redactString(value.stack) : undefined,
+        };
+    }
+    if (value instanceof Headers) {
+        const out = {};
+        value.forEach((v, k) => {
+            out[k] = SECRET_KEYS.has(k.toLowerCase()) ? REDACTED : redactString(v);
+        });
+        return out;
+    }
+    if (value instanceof URL) {
+        return redactUrl(value);
+    }
+    // Types with no own enumerable properties must be handled before the generic
+    // Object.entries walk below, which would otherwise flatten them to `{}`.
+    // Dates matter most: tick timestamps flow straight into `kite watch --json`.
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? null : value.toISOString();
+    }
+    if (value instanceof Map) {
+        return redact(Object.fromEntries(value), depth + 1, seen);
+    }
+    if (value instanceof Set) {
+        return redact([...value], depth + 1, seen);
+    }
+    if (value instanceof RegExp) {
+        return value.toString();
+    }
+    if (Buffer.isBuffer(value)) {
+        return `[buffer ${value.length} bytes]`;
+    }
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        out[key] = SECRET_KEYS.has(key.toLowerCase()) ? REDACTED : redact(item, depth + 1, seen);
+    }
+    return out;
+}
+/**
+ * Redact credentials from a URL's query string.
+ *
+ * This exists specifically for the ticker: `wss://ws.kite.trade?api_key=..&access_token=..`
+ * must never be printed or embedded in an error. `api_key` is kept (it is
+ * semi-public and useful for debugging); `access_token` is not.
+ */
+export function redactUrl(url) {
+    let parsed;
+    try {
+        parsed = typeof url === 'string' ? new URL(url) : url;
+    }
+    catch {
+        // Not a parseable URL — fall back to pattern scrubbing.
+        return redactString(String(url));
+    }
+    const copy = new URL(parsed.toString());
+    for (const key of [...copy.searchParams.keys()]) {
+        if (SECRET_KEYS.has(key.toLowerCase())) {
+            copy.searchParams.set(key, REDACTED);
+        }
+    }
+    if (copy.password)
+        copy.password = REDACTED;
+    return copy.toString();
+}
+/**
+ * Mask a secret for display, showing only enough to identify which credential
+ * it is. Used by `kite config show` and login confirmations.
+ */
+export function maskSecret(value, visible = 4) {
+    if (value.length <= visible)
+        return '*'.repeat(8);
+    return `${'*'.repeat(8)}${value.slice(-visible)}`;
+}