@pungoyal/kite-cli 0.1.0

package/dist/core/schemas.js

@@ -0,0 +1,433 @@
+import { z } from 'zod';
+/**
+ * Runtime schemas for Kite API responses.
+ *
+ * Two rules govern everything here:
+ *
+ *  1. **Every object is loose.** Zerodha adds fields without notice; a strict
+ *     schema would turn a benign API addition into a broken CLI for every user.
+ *     We validate the fields we depend on and pass the rest through.
+ *
+ *  2. **`status` is never an enum.** The order docs list the known states and
+ *     then say verbatim "There may be other values as well." An exhaustive
+ *     union would reject real orders. We use `z.string()` plus named constants.
+ *
+ * Binary WebSocket frames are deliberately NOT validated here — they are
+ * fixed-length structs, parsed by hand in ticker.ts. Running 3000 instruments
+ * of full-mode ticks through a validator would be both the wrong tool and a
+ * real cost on the hot path.
+ */
+/** Kite wraps every successful response as { status: "success", data: ... }. */
+export const EnvelopeSchema = z.looseObject({
+    status: z.string(),
+    data: z.unknown().optional(),
+    message: z.string().optional(),
+    error_type: z.string().optional(),
+});
+export const ErrorEnvelopeSchema = z.looseObject({
+    status: z.literal('error'),
+    message: z.string().default('Unknown error'),
+    error_type: z.string().default('GeneralException'),
+});
+// ---------------------------------------------------------------------------
+// Session / user
+// ---------------------------------------------------------------------------
+export const SessionSchema = z.looseObject({
+    user_id: z.string(),
+    user_name: z.string().optional(),
+    user_shortname: z.string().optional(),
+    email: z.string().optional(),
+    user_type: z.string().optional(),
+    broker: z.string().optional(),
+    exchanges: z.array(z.string()).default([]),
+    products: z.array(z.string()).default([]),
+    order_types: z.array(z.string()).default([]),
+    access_token: z.string(),
+    public_token: z.string().optional(),
+    refresh_token: z.string().optional(),
+    login_time: z.string().optional(),
+});
+export const ProfileSchema = z.looseObject({
+    user_id: z.string(),
+    user_name: z.string().optional(),
+    user_shortname: z.string().optional(),
+    email: z.string().optional(),
+    user_type: z.string().optional(),
+    broker: z.string().optional(),
+    exchanges: z.array(z.string()).default([]),
+    products: z.array(z.string()).default([]),
+    order_types: z.array(z.string()).default([]),
+});
+const SegmentMarginSchema = z.looseObject({
+    enabled: z.boolean().optional(),
+    net: z.number().optional(),
+    available: z
+        .looseObject({
+        cash: z.number().optional(),
+        opening_balance: z.number().optional(),
+        live_balance: z.number().optional(),
+        intraday_payin: z.number().optional(),
+        adhoc_margin: z.number().optional(),
+        collateral: z.number().optional(),
+    })
+        .optional(),
+    utilised: z
+        .looseObject({
+        debits: z.number().optional(),
+        exposure: z.number().optional(),
+        m2m_realised: z.number().optional(),
+        m2m_unrealised: z.number().optional(),
+        option_premium: z.number().optional(),
+        payout: z.number().optional(),
+        span: z.number().optional(),
+        holding_sales: z.number().optional(),
+        turnover: z.number().optional(),
+        liquid_collateral: z.number().optional(),
+        stock_collateral: z.number().optional(),
+        delivery: z.number().optional(),
+    })
+        .optional(),
+});
+export const MarginsSchema = z.looseObject({
+    equity: SegmentMarginSchema.optional(),
+    commodity: SegmentMarginSchema.optional(),
+});
+// ---------------------------------------------------------------------------
+// Orders
+// ---------------------------------------------------------------------------
+/** Known terminal states. Not exhaustive — see the note at the top of this file. */
+export const ORDER_STATUS = {
+    Complete: 'COMPLETE',
+    Cancelled: 'CANCELLED',
+    Rejected: 'REJECTED',
+    Open: 'OPEN',
+    TriggerPending: 'TRIGGER PENDING',
+};
+export const TERMINAL_ORDER_STATUSES = new Set([
+    ORDER_STATUS.Complete,
+    ORDER_STATUS.Cancelled,
+    ORDER_STATUS.Rejected,
+]);
+export const OrderSchema = z.looseObject({
+    order_id: z.string(),
+    parent_order_id: z.string().nullish(),
+    exchange_order_id: z.string().nullish(),
+    status: z.string(),
+    status_message: z.string().nullish(),
+    status_message_raw: z.string().nullish(),
+    order_timestamp: z.string().nullish(),
+    exchange_timestamp: z.string().nullish(),
+    exchange_update_timestamp: z.string().nullish(),
+    variety: z.string().optional(),
+    exchange: z.string().optional(),
+    tradingsymbol: z.string().optional(),
+    instrument_token: z.number().optional(),
+    transaction_type: z.string().optional(),
+    order_type: z.string().optional(),
+    product: z.string().optional(),
+    validity: z.string().optional(),
+    price: z.number().optional(),
+    quantity: z.number().optional(),
+    trigger_price: z.number().optional(),
+    average_price: z.number().optional(),
+    pending_quantity: z.number().optional(),
+    filled_quantity: z.number().optional(),
+    disclosed_quantity: z.number().optional(),
+    cancelled_quantity: z.number().optional(),
+    tag: z.string().nullish(),
+    tags: z.array(z.string()).nullish(),
+    placed_by: z.string().optional(),
+    guid: z.string().nullish(),
+});
+export const TradeSchema = z.looseObject({
+    trade_id: z.string(),
+    order_id: z.string(),
+    exchange_order_id: z.string().nullish(),
+    tradingsymbol: z.string().optional(),
+    exchange: z.string().optional(),
+    instrument_token: z.number().optional(),
+    transaction_type: z.string().optional(),
+    product: z.string().optional(),
+    average_price: z.number().optional(),
+    quantity: z.number().optional(),
+    fill_timestamp: z.string().nullish(),
+    exchange_timestamp: z.string().nullish(),
+    order_timestamp: z.string().nullish(),
+});
+/**
+ * Place-order response.
+ *
+ * With `autoslice=true` the shape changes from an object to an ARRAY of up to
+ * 10 entries, where success and failure can coexist in a single response. This
+ * union models that; callers must handle both.
+ */
+export const PlaceOrderResultSchema = z.union([
+    z.looseObject({ order_id: z.string() }),
+    z.array(z.union([
+        z.looseObject({ order_id: z.string() }),
+        z.looseObject({
+            error: z.looseObject({
+                code: z.number().optional(),
+                error_type: z.string().optional(),
+                message: z.string().optional(),
+            }),
+        }),
+    ])),
+]);
+// ---------------------------------------------------------------------------
+// Portfolio
+// ---------------------------------------------------------------------------
+export const HoldingSchema = z.looseObject({
+    tradingsymbol: z.string(),
+    exchange: z.string(),
+    instrument_token: z.number().optional(),
+    isin: z.string().optional(),
+    product: z.string().optional(),
+    quantity: z.number().default(0),
+    t1_quantity: z.number().default(0),
+    realised_quantity: z.number().default(0),
+    opening_quantity: z.number().default(0),
+    collateral_quantity: z.number().default(0),
+    authorised_quantity: z.number().default(0),
+    average_price: z.number().default(0),
+    last_price: z.number().default(0),
+    close_price: z.number().default(0),
+    pnl: z.number().default(0),
+    day_change: z.number().default(0),
+    day_change_percentage: z.number().default(0),
+});
+export const PositionSchema = z.looseObject({
+    tradingsymbol: z.string(),
+    exchange: z.string(),
+    instrument_token: z.number().optional(),
+    product: z.string().optional(),
+    quantity: z.number().default(0),
+    overnight_quantity: z.number().default(0),
+    multiplier: z.number().default(1),
+    average_price: z.number().default(0),
+    close_price: z.number().default(0),
+    last_price: z.number().default(0),
+    value: z.number().default(0),
+    pnl: z.number().default(0),
+    m2m: z.number().default(0),
+    unrealised: z.number().default(0),
+    realised: z.number().default(0),
+    buy_quantity: z.number().default(0),
+    buy_price: z.number().default(0),
+    buy_value: z.number().default(0),
+    sell_quantity: z.number().default(0),
+    sell_price: z.number().default(0),
+    sell_value: z.number().default(0),
+    day_buy_quantity: z.number().default(0),
+    day_sell_quantity: z.number().default(0),
+});
+export const PositionsSchema = z.looseObject({
+    net: z.array(PositionSchema).default([]),
+    day: z.array(PositionSchema).default([]),
+});
+export const AuctionSchema = z.looseObject({
+    tradingsymbol: z.string(),
+    exchange: z.string(),
+    instrument_token: z.number().optional(),
+    auction_number: z.string().optional(),
+    quantity: z.number().optional(),
+    last_price: z.number().optional(),
+});
+// ---------------------------------------------------------------------------
+// Market data
+// ---------------------------------------------------------------------------
+const DepthEntrySchema = z.looseObject({
+    price: z.number().default(0),
+    quantity: z.number().default(0),
+    orders: z.number().default(0),
+});
+export const OhlcSchema = z.looseObject({
+    open: z.number().default(0),
+    high: z.number().default(0),
+    low: z.number().default(0),
+    close: z.number().default(0),
+});
+export const QuoteSchema = z.looseObject({
+    instrument_token: z.number(),
+    timestamp: z.string().nullish(),
+    last_trade_time: z.string().nullish(),
+    last_price: z.number().default(0),
+    last_quantity: z.number().optional(),
+    buy_quantity: z.number().optional(),
+    sell_quantity: z.number().optional(),
+    volume: z.number().optional(),
+    average_price: z.number().optional(),
+    oi: z.number().optional(),
+    oi_day_high: z.number().optional(),
+    oi_day_low: z.number().optional(),
+    net_change: z.number().optional(),
+    lower_circuit_limit: z.number().optional(),
+    upper_circuit_limit: z.number().optional(),
+    ohlc: OhlcSchema.optional(),
+    depth: z
+        .looseObject({
+        buy: z.array(DepthEntrySchema).default([]),
+        sell: z.array(DepthEntrySchema).default([]),
+    })
+        .optional(),
+});
+export const LtpQuoteSchema = z.looseObject({
+    instrument_token: z.number(),
+    last_price: z.number().default(0),
+});
+export const OhlcQuoteSchema = z.looseObject({
+    instrument_token: z.number(),
+    last_price: z.number().default(0),
+    ohlc: OhlcSchema.optional(),
+});
+/**
+ * Quote endpoints return a map keyed by "EXCHANGE:TRADINGSYMBOL". Instruments
+ * with no data — expired, invalid, or never traded — are simply ABSENT from the
+ * map rather than present with nulls. Callers must never assume presence.
+ */
+export const QuoteMapSchema = z.record(z.string(), QuoteSchema);
+export const LtpMapSchema = z.record(z.string(), LtpQuoteSchema);
+export const OhlcMapSchema = z.record(z.string(), OhlcQuoteSchema);
+/**
+ * Historical candles: [timestamp, open, high, low, close, volume] with an
+ * optional 7th open-interest element when oi=1 was requested.
+ */
+export const CandleSchema = z.tuple([z.string(), z.number(), z.number(), z.number(), z.number(), z.number()], z.number());
+export const CandlesSchema = z.looseObject({
+    candles: z.array(CandleSchema).default([]),
+});
+// ---------------------------------------------------------------------------
+// GTT
+// ---------------------------------------------------------------------------
+export const GttSchema = z.looseObject({
+    id: z.number(),
+    user_id: z.string().optional(),
+    parent_trigger: z.unknown().nullish(),
+    type: z.string(),
+    created_at: z.string().optional(),
+    updated_at: z.string().optional(),
+    expires_at: z.string().optional(),
+    status: z.string(),
+    condition: z.looseObject({
+        exchange: z.string(),
+        tradingsymbol: z.string(),
+        trigger_values: z.array(z.number()).default([]),
+        last_price: z.number().optional(),
+        instrument_token: z.number().optional(),
+    }),
+    orders: z
+        .array(z.looseObject({
+        exchange: z.string().optional(),
+        tradingsymbol: z.string().optional(),
+        product: z.string().optional(),
+        order_type: z.string().optional(),
+        transaction_type: z.string().optional(),
+        quantity: z.number().optional(),
+        price: z.number().optional(),
+        result: z.unknown().nullish(),
+    }))
+        .default([]),
+});
+export const GttCreateResultSchema = z.looseObject({ trigger_id: z.number() });
+// ---------------------------------------------------------------------------
+// Margins / charges calculator
+// ---------------------------------------------------------------------------
+export const OrderMarginSchema = z.looseObject({
+    type: z.string().optional(),
+    tradingsymbol: z.string().optional(),
+    exchange: z.string().optional(),
+    span: z.number().optional(),
+    exposure: z.number().optional(),
+    option_premium: z.number().optional(),
+    additional: z.number().optional(),
+    bo: z.number().optional(),
+    cash: z.number().optional(),
+    var: z.number().optional(),
+    total: z.number().optional(),
+    leverage: z.number().optional(),
+    charges: z
+        .looseObject({
+        transaction_tax: z.number().optional(),
+        transaction_tax_type: z.string().optional(),
+        exchange_turnover_charge: z.number().optional(),
+        sebi_turnover_charge: z.number().optional(),
+        brokerage: z.number().optional(),
+        stamp_duty: z.number().optional(),
+        total: z.number().optional(),
+        gst: z
+            .looseObject({
+            igst: z.number().optional(),
+            cgst: z.number().optional(),
+            sgst: z.number().optional(),
+            total: z.number().optional(),
+        })
+            .optional(),
+    })
+        .optional(),
+    pnl: z
+        .looseObject({
+        realised: z.number().optional(),
+        unrealised: z.number().optional(),
+    })
+        .optional(),
+});
+export const BasketMarginSchema = z.looseObject({
+    initial: OrderMarginSchema.optional(),
+    final: OrderMarginSchema.optional(),
+    orders: z.array(OrderMarginSchema).default([]),
+    charges: z.unknown().optional(),
+});
+// ---------------------------------------------------------------------------
+// Mutual funds (read-only: the current docs state order placement is not
+// available over the API, since it needs a bank debit)
+// ---------------------------------------------------------------------------
+export const MfHoldingSchema = z.looseObject({
+    folio: z.string().nullish(),
+    fund: z.string().optional(),
+    tradingsymbol: z.string(),
+    average_price: z.number().default(0),
+    last_price: z.number().default(0),
+    last_price_date: z.string().optional(),
+    pnl: z.number().default(0),
+    quantity: z.number().default(0),
+});
+export const MfOrderSchema = z.looseObject({
+    order_id: z.string(),
+    fund: z.string().optional(),
+    tradingsymbol: z.string().optional(),
+    status: z.string().optional(),
+    status_message: z.string().nullish(),
+    folio: z.string().nullish(),
+    order_timestamp: z.string().nullish(),
+    transaction_type: z.string().optional(),
+    quantity: z.number().nullish(),
+    amount: z.number().nullish(),
+    average_price: z.number().nullish(),
+});
+export const MfSipSchema = z.looseObject({
+    sip_id: z.string(),
+    tradingsymbol: z.string().optional(),
+    fund: z.string().optional(),
+    status: z.string().optional(),
+    instalment_amount: z.number().optional(),
+    instalments: z.number().optional(),
+    frequency: z.string().optional(),
+    next_instalment: z.string().nullish(),
+});
+// ---------------------------------------------------------------------------
+// Instruments (parsed from the daily CSV dump)
+// ---------------------------------------------------------------------------
+export const InstrumentSchema = z.looseObject({
+    instrument_token: z.number(),
+    exchange_token: z.number().optional(),
+    tradingsymbol: z.string(),
+    name: z.string().optional(),
+    last_price: z.number().optional(),
+    expiry: z.string().optional(),
+    strike: z.number().optional(),
+    tick_size: z.number().optional(),
+    lot_size: z.number().optional(),
+    instrument_type: z.string().optional(),
+    segment: z.string().optional(),
+    exchange: z.string(),
+});

package/dist/core/secretstore.d.ts

@@ -0,0 +1,11 @@
+export declare function encryptToFile(secrets: Record<string, string>, passphrase: string): Promise<void>;
+export declare function decryptFromFile(passphrase: string): Promise<Record<string, string> | null>;
+export declare function deleteCredentialFile(): Promise<void>;
+/**
+ * Constant-time string comparison, for any future passphrase confirmation.
+ *
+ * Length is compared on the encoded buffers, not on String.length —
+ * timingSafeEqual throws RangeError on mismatched byte lengths, and UTF-16
+ * code-unit counts can match while byte lengths do not.
+ */
+export declare function safeEqual(a: string, b: string): boolean;

package/dist/core/secretstore.js

@@ -0,0 +1,138 @@
+import { createCipheriv, createDecipheriv, randomBytes, scrypt as scryptCb, timingSafeEqual } from 'node:crypto';
+import { chmod, readFile, unlink, writeFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { ExitCode, KiteCliError } from './errors.js';
+import { configDir, credentialsFile, ensurePrivateDir } from './paths.js';
+const scrypt = promisify(scryptCb);
+/**
+ * Encrypted-file credential store.
+ *
+ * This is the fallback for machines with no usable OS keyring — headless Linux
+ * without D-Bus, containers, some CI runners. It is strictly worse than the
+ * keyring (the passphrase has to come from somewhere) but strictly better than
+ * the plaintext files that gh, aws, and stripe all fall back to.
+ *
+ * Format: a JSON header, a newline, then base64 ciphertext.
+ * The header is bound as AES-GCM additional authenticated data, so an attacker
+ * cannot downgrade the KDF parameters without failing decryption.
+ */
+/** OWASP-recommended scrypt parameters. ~270ms on an M-series laptop. */
+const KDF = {
+    N: 2 ** 17,
+    r: 8,
+    p: 1,
+    keylen: 32,
+    // Node's default maxmem is 32MB; scrypt at N=2^17,r=8 needs 128*N*r = 134MB
+    // and throws without this. A silent, confusing failure if you miss it.
+    maxmem: 256 * 1024 * 1024,
+};
+async function deriveKey(passphrase, salt, params) {
+    return scrypt(passphrase, salt, KDF.keylen, {
+        N: params.N,
+        r: params.r,
+        p: params.p,
+        maxmem: KDF.maxmem,
+    });
+}
+export async function encryptToFile(secrets, passphrase) {
+    const salt = randomBytes(16);
+    const nonce = randomBytes(12);
+    const key = await deriveKey(passphrase, salt, KDF);
+    const header = {
+        v: 1,
+        kdf: 'scrypt',
+        N: KDF.N,
+        r: KDF.r,
+        p: KDF.p,
+        salt: salt.toString('base64'),
+        nonce: nonce.toString('base64'),
+    };
+    const headerJson = JSON.stringify(header);
+    const cipher = createCipheriv('aes-256-gcm', key, nonce);
+    // Bind the header so KDF parameters cannot be tampered with.
+    cipher.setAAD(Buffer.from(headerJson, 'utf8'));
+    const ciphertext = Buffer.concat([cipher.update(Buffer.from(JSON.stringify(secrets), 'utf8')), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const payload = `${headerJson}\n${Buffer.concat([ciphertext, tag]).toString('base64')}\n`;
+    await ensurePrivateDir(configDir());
+    const path = credentialsFile();
+    await writeFile(path, payload, { mode: 0o600, encoding: 'utf8' });
+    if (process.platform !== 'win32') {
+        await chmod(path, 0o600);
+    }
+}
+export async function decryptFromFile(passphrase) {
+    let raw;
+    try {
+        raw = await readFile(credentialsFile(), 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    const newlineAt = raw.indexOf('\n');
+    if (newlineAt === -1) {
+        throw new KiteCliError('Credential file is corrupt (no header).', ExitCode.Failure);
+    }
+    const headerJson = raw.slice(0, newlineAt);
+    const body = raw.slice(newlineAt + 1).trim();
+    let header;
+    try {
+        header = JSON.parse(headerJson);
+    }
+    catch {
+        throw new KiteCliError('Credential file is corrupt (bad header).', ExitCode.Failure);
+    }
+    if (header.v !== 1 || header.kdf !== 'scrypt') {
+        throw new KiteCliError(`Unsupported credential file version. Re-run \`kite login\` to rewrite it.`, ExitCode.Failure);
+    }
+    const salt = Buffer.from(header.salt, 'base64');
+    const nonce = Buffer.from(header.nonce, 'base64');
+    const key = await deriveKey(passphrase, salt, {
+        N: header.N,
+        r: header.r,
+        p: header.p,
+    });
+    const blob = Buffer.from(body, 'base64');
+    if (blob.length < 17) {
+        throw new KiteCliError('Credential file is corrupt (truncated).', ExitCode.Failure);
+    }
+    const ciphertext = blob.subarray(0, blob.length - 16);
+    const tag = blob.subarray(blob.length - 16);
+    const decipher = createDecipheriv('aes-256-gcm', key, nonce);
+    decipher.setAAD(Buffer.from(headerJson, 'utf8'));
+    decipher.setAuthTag(tag);
+    try {
+        const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return JSON.parse(plaintext.toString('utf8'));
+    }
+    catch {
+        // GCM authentication failed: wrong passphrase, or the file was tampered
+        // with. We cannot distinguish the two, and should not try to.
+        throw new KiteCliError('Could not decrypt credentials — wrong passphrase, or the file was modified.', ExitCode.Auth, 'Re-run `kite login` to rewrite the credential file.');
+    }
+}
+export async function deleteCredentialFile() {
+    try {
+        await unlink(credentialsFile());
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+}
+/**
+ * Constant-time string comparison, for any future passphrase confirmation.
+ *
+ * Length is compared on the encoded buffers, not on String.length —
+ * timingSafeEqual throws RangeError on mismatched byte lengths, and UTF-16
+ * code-unit counts can match while byte lengths do not.
+ */
+export function safeEqual(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);
+}

package/dist/core/session.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+/**
+ * Non-secret session metadata.
+ *
+ * The access token itself lives in the OS keyring; only its expiry and the
+ * identity it belongs to are stored here. That split lets `kite whoami` show
+ * who you are and when your session dies without unlocking the keyring, and
+ * lets `kite logout` drop the token without touching the API secret.
+ */
+export declare const SessionMetaSchema: z.ZodObject<{
+    userId: z.ZodString;
+    userName: z.ZodOptional<z.ZodString>;
+    broker: z.ZodOptional<z.ZodString>;
+    env: z.ZodString;
+    apiKey: z.ZodString;
+    expiresAt: z.ZodString;
+    loginTime: z.ZodOptional<z.ZodString>;
+    exchanges: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    products: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type SessionMeta = z.infer<typeof SessionMetaSchema>;
+export declare function loadSessionMeta(): Promise<SessionMeta | null>;
+export declare function saveSessionMeta(meta: SessionMeta): Promise<void>;
+export declare function clearSessionMeta(): Promise<void>;
+/**
+ * Kite access tokens expire at 06:00 IST the following day — a regulatory
+ * requirement, not a configurable session length.
+ *
+ * This is a floor, not a guarantee: a master logout from Kite web invalidates
+ * the token immediately, and there is no way to detect that except by getting a
+ * 403. Callers must treat TokenException as authoritative regardless of what
+ * this says.
+ */
+export declare function nextTokenExpiry(now?: Date): Date;
+export declare function isExpired(meta: SessionMeta, now?: Date): boolean;
+/** Human-readable time remaining, e.g. "4h 12m". */
+export declare function timeUntilExpiry(meta: SessionMeta, now?: Date): string;