DEV Community: Konstantin Tarkus

How I bundle my codebase so ChatGPT can actually understand it

Konstantin Tarkus — Mon, 19 Jan 2026 10:21:57 +0000

LLM chat apps are great at answering questions — until you point them at a real codebase.

Once a project grows past a certain size, context becomes the bottleneck: too many files, too much noise, not enough structure.

I kept running into this while working with modern JS / Bun projects, so I built a small CLI to solve my own workflow problem.

The problem

Most LLM chat apps work best when:

context is linear
files are grouped by meaning, not size
references are precise (file + line)

But real repos are:

hierarchical
noisy
full of things the model doesn’t need

The result is vague or hallucinated answers.

The approach

Instead of feeding the whole repo, I generate an LLM-optimized snapshot:

code is bundled by domain (web, api, docs, etc.)
each bundle is indexed with file paths + line numbers
.gitignore is respected by default
no config needed to get started

The output is just plain text files — easy to upload or attach to ChatGPT, Gemini, or Claude.

That tool became srcpack.

How I actually use it

A few workflows where this has been surprisingly effective:

Exploring large repos – Asking “where does auth actually live?” or “what touches billing?”
Avoiding context limits – Instead of pasting files manually, I attach a focused bundle.
Sharing with non-technical teammates – I upload an LLM-friendly snapshot to Google Drive and share it.

PMs or designers can ask:

“What shipped this week?”
“What’s still in progress?”
“Which parts are risky?”

It acts like a lightweight, read-only AI interface to the codebase.

Example usage

npx srcpack # or bunx srcpack

That’s it — zero config by default.

Closing thought

I don’t think this is the final answer to LLM + codebase interaction, but it’s been a very practical improvement for day-to-day work.

Curious how others are handling large-repo context with LLMs — especially in fast-moving projects.

Two Timestamps, One Message: Why WebSocket Systems Need Both

Konstantin Tarkus — Wed, 08 Oct 2025 19:18:07 +0000

TL;DR: Using client-provided timestamps (meta.timestamp) for server-side logic like rate limiting or message ordering is a silent security bug. Server systems need their own authoritative timestamp (receivedAt) captured at ingress.

This article uses examples from bun-ws-router, a type-safe WebSocket router for Bun with Zod/Valibot validation, but the timestamp security principles apply to any real-time system.

The Problem

Picture this: Your real-time chat app is buzzing, the conversation is flying, and dashboards are green. Then out of nowhere a support ticket lands: "User @malicious_user blasted 500 messages in under a second, but your rate limiter never tripped."

You dig into the logs. Sure enough, that client sent 500 messages. But here's the kicker — each message claimed to be sent 5 seconds apart according to its timestamp. Your rate limiter believed the client and let them all through.

Sound far-fetched? It's not. This vulnerability exists in production systems right now.

Here's what a typical WebSocket message looks like:

{
  "type": "CHAT",
  "meta": {
    "timestamp": 1728432000000
  },
  "payload": {
    "text": "Hello!"
  }
}

That 1728432000000 value is just an epoch example — milliseconds since 1970, not a prediction from the future.

Quick question: Which timestamp should you use for rate limiting? For ordering messages in your database? For calculating request latency?

If you answered "the one in meta.timestamp", you've just introduced a security vulnerability. Let me show you why.

The Vulnerability

Here's the core issue: client-provided timestamps are untrusted input. You wouldn't trust a client to tell you their own user ID or permissions, right? Time is no different.

A malicious (or just buggy) client can:

1. Bypass Rate Limits

Watch how a clever attacker can speed-run your spam filter just by lying about time:

// ❌ VULNERABLE: Rate limiting using client time
router.onMessage(ChatMessage, (ctx) => {
  const lastMessageTime = cache.get(ctx.ws.data.userId);
  const timeSinceLastMessage = ctx.meta.timestamp - lastMessageTime;

  if (timeSinceLastMessage < 1000) {
    // Reject: too fast
    return;
  }

  // Attacker sends: meta.timestamp = Date.now() + 10000
  // Server thinks 10 seconds passed, allows message through
});

2. Reorder Messages

What if an attacker could make their messages appear before a moderator's warning? Or insert a message between two existing ones to change the context of a conversation?

It takes nothing more than a forged timestamp.

// ❌ VULNERABLE: Ordering by client time
router.onMessage(ChatMessage, async (ctx) => {
  await db.insert({
    roomId: ctx.payload.roomId,
    text: ctx.payload.text,
    receivedAt: ctx.meta.timestamp, // Attacker controls this
  });

  // Attacker sends timestamp from 5 minutes ago
  // Their message appears before recent mod warnings
  // "I didn't see the warning!" becomes a plausible excuse
});

3. Skew Analytics

Negative latency makes for funny screenshots — right up until it explodes your dashboards.

// ❌ VULNERABLE: Latency calculation using client time
router.onMessage(PingMessage, (ctx) => {
  const latency = Date.now() - ctx.meta.timestamp;
  metrics.recordLatency(latency);

  // Client sends timestamp from the future
  // Negative latency crashes your monitoring
});

4. Clock Drift (Non-Malicious)

Not every problem is malicious. Even well-behaved clients struggle with time, and their clocks tick away from server truth for all sorts of reasons:

Timezone chaos: A traveler brings yesterday's settings into today's room and every message looks stale
System clock drift: Commodity hardware drifts hundreds of milliseconds to a few seconds over days without a sync
Mobile devices: Phones with "Set time automatically" disabled can wander minutes or hours off course
Offline gaps: Disconnected clients queue messages, then reconnect with stale producer timestamps
Network latency: Slow links add seconds between creation and arrival, even when both clocks agree

Think of it like a wristwatch that loses a minute every month — annoying in real life, hazardous in distributed systems. I've chased bugs where a single misconfigured device skewed an entire chat history. They weren't attacking anything — their phone just had the wrong time. These real-world drifts are worth simulating in tests by overriding Date.now() or using sinon-style timers to inject skew on demand.

The Solution: Two Timestamps

The fix is simpler than you might think: use two different timestamps for two different purposes.

Think of it like the postal system. When you write a letter, you might write today's date at the top — that's your "producer time." But the post office stamps it with their own date when they receive it — that's their "ingress time." The post office doesn't trust your handwritten date for tracking packages. Neither should your server.

Real-time systems need two distinct timestamps with different trust levels:

1. Producer Time (`meta.timestamp`)

What: When the message was created (client's clock)
Set by: Client
Trust level: Low (untrusted input)
Use for: UI display, optimistic ordering, perceived latency

// Client code
client.send(
  ChatMessage,
  { text: "hello" },
  { meta: { timestamp: Date.now() } }, // Producer time
);

Note: In bun-ws-router, the client SDK auto-adds meta.timestamp if you don't provide one. This makes messages self-describing for UI purposes without requiring manual timestamp management.

Pro Tip: The normalization step (see specs/validation.md#normalization-rules) strips any attempt to inject reserved fields like receivedAt or clientId. Treat meta.timestamp as optional sugar — the server will add what it truly needs.

If a client omits it, the SDK falls back to Date.now(). On the server side, keep validating so wild values (hours in the future) trigger the guardrails you saw earlier.

2. Server Ingress Time (`ctx.receivedAt`)

What: When the server received the message (server's clock)
Set by: Server (before parsing)
Trust level: High (authoritative)
Use for: Rate limiting, ordering, TTL, audits

// Server code
router.onMessage(ChatMessage, (ctx) => {
  // ctx.receivedAt captured at message arrival (server clock)
  // ctx.meta.timestamp is client-provided (may be missing/skewed)

  // Use receivedAt for any server logic
  if (ctx.receivedAt - lastMessageTime < 1000) {
    // Rate limit based on server time
  }
});

When to Use Which Timestamp

Here's your cheat sheet:

Use Case	Field	Why	What Breaks If Wrong
Rate limiting	`ctx.receivedAt`	Server clock prevents manipulation	Attackers bypass limits
Message ordering (DB)	`ctx.receivedAt`	Consistent across all clients	Messages appear out of order
TTL / expiration	`ctx.receivedAt`	Server decides when things expire	Items expire at wrong times
Audit logs	`ctx.receivedAt`	Legal compliance needs server time	Logs can't be trusted in court
Deduplication windows	`ctx.receivedAt`	Prevents replay attacks	Duplicate processing
"Sent 5 minutes ago" (UI)	`meta.timestamp`	Shows user's perceived time	Confusing UI times
Optimistic UI ordering	`meta.timestamp`	Smooth UX before server confirms	Jumpy UI
Latency display	Both	`receivedAt - timestamp` (but validate)	Negative latency, bad metrics

Golden rule: If it affects server behavior (security, data integrity, business logic), use ctx.receivedAt. If it affects UI display (timestamps shown to users, perceived performance), use meta.timestamp.

Martin Kleppmann summed it up neatly in Designing Data-Intensive Applications: "Clocks are a poor substitute for causality." Dual timestamps let you model both — the causal order your server can trust, and the narrative order the user expects.

Correct Implementations

Rate Limiting

// ✅ SECURE: Rate limiting with server time
const rateLimits = new Map<string, number[]>();

router.onMessage(ChatMessage, (ctx) => {
  const userId = ctx.ws.data.userId;
  const timestamps = rateLimits.get(userId) || [];

  // Filter to last 60 seconds using SERVER time
  const recentMessages = timestamps.filter((t) => ctx.receivedAt - t < 60000);

  if (recentMessages.length >= 10) {
    ctx.send(ErrorMessage, {
      code: "RATE_LIMIT_EXCEEDED",
      message: "Too many messages (10/min limit)",
    });
    return;
  }

  // Record THIS message's server ingress time
  recentMessages.push(ctx.receivedAt);
  rateLimits.set(userId, recentMessages);

  // Process message...
});

Message Ordering

// ✅ SECURE: Database ordering by server time
router.onMessage(ChatMessage, async (ctx) => {
  await db.messages.insert({
    roomId: ctx.payload.roomId,
    text: ctx.payload.text,
    userId: ctx.ws.data.userId,

    // Server authoritative ordering
    receivedAt: ctx.receivedAt,

    // Client-provided for UI "sent at" display (optional)
    clientTimestamp: ctx.meta.timestamp,
  });

  // Query always orders by receivedAt (server time)
  const messages = await db.messages
    .where({ roomId: ctx.payload.roomId })
    .orderBy("receivedAt", "desc")
    .limit(50);
});

Pair that with storage tuned for temporal queries: index on (receivedAt DESC, userId) or (receivedAt DESC, clientId) so recent events stream efficiently. UUID v7 connection IDs from ctx.ws.data.clientId already encode time bits, and combining them with receivedAt keeps hot paths cache-friendly (see specs/rules.md#performance for rationale).

Latency Metrics (Defensive)

Even for latency measurement — where client time seems necessary — you need defensive validation:

// ✅ SECURE: Latency with validation
router.onMessage(PingMessage, (ctx) => {
  if (ctx.meta.timestamp) {
    const latency = ctx.receivedAt - ctx.meta.timestamp;

    // Validate reasonable range (prevent future timestamps)
    if (latency >= 0 && latency < 60000) {
      metrics.recordLatency(latency);
    } else {
      // Log suspicious timestamp for investigation
      console.warn(
        `Invalid timestamp from ${ctx.ws.data.clientId}: latency=${latency}ms`,
      );
      metrics.increment("timestamp.invalid_latency");
    }
  }

  // Reply with server time for client-side latency calculation
  ctx.send(PongMessage, {
    serverTime: ctx.receivedAt,
  });
});

Why the validation? Without it, a client sending a future timestamp produces negative latency, which crashes most monitoring systems. Ask me how I know.

Broadcasting with Origin Tracking

// ✅ SECURE: Broadcasts use server time for persistence, client time for UI
import { z } from "zod";
import { WebSocketRouter, createMessageSchema } from "bun-ws-router/zod";
import { publish } from "bun-ws-router/zod/publish";

const { messageSchema } = createMessageSchema(z);
const ChatBroadcast = messageSchema("CHAT_BROADCAST", {
  id: z.string(),
  text: z.string(),
});

router.onMessage(ChatMessage, async (ctx) => {
  // Store with server time for authoritative ordering
  const messageId = await db.messages.insert({
    roomId: ctx.payload.roomId,
    text: ctx.payload.text,
    userId: ctx.ws.data.userId,
    receivedAt: ctx.receivedAt, // Server time for ordering
  });

  // Broadcast to room subscribers
  publish(
    ctx.ws,
    `room:${ctx.payload.roomId}`,
    ChatBroadcast,
    { id: messageId, text: ctx.payload.text }, // Payload only
    { origin: "userId" }, // Injects meta.senderId from ws.data.userId
  );

  // publish() auto-injects meta.timestamp (producer time for UI)
  // publish() also validates the message schema before sending
  // Server logic MUST use ctx.receivedAt, not this timestamp
});

When you fan out messages, order on receivedAt before calling publish() so downstream subscribers (AND your analytics pipeline) ingest events in a consistent order — specs/router.md calls this out in the context-building phase.


## Implementation Notes

### Capture `receivedAt` Early

Timing matters. Capture the timestamp as early as possible — before parsing, before validation, at the moment bytes arrive:

// Capture timestamp at message ingress, BEFORE parsing
const receivedAt = Date.now();

try {
  const parsedMessage = JSON.parse(message);
  // ... validation, normalization, handler dispatch

  const ctx = {
    ws,
    receivedAt, // Authoritative server ingress time
    meta: parsedMessage.meta, // Contains optional client timestamp
    // ...
  };
} catch (error) {
  // Errors don't affect receivedAt accuracy
}

Why before parsing? If JSON parsing takes 50ms (it shouldn't, but sometimes it does), you don't want that delay affecting your rate limiter's perception of time. Need more precision? Pair Date.now() with process.hrtime.bigint() (Bun exposes it too) to capture microsecond deltas without trusting the client's clock.

Make Client Timestamp Optional

// Schema: meta.timestamp is optional
const ChatMessage = messageSchema(
  "CHAT",
  { text: z.string() },
  { timestamp: z.number().optional() }, // Client may omit
);

router.onMessage(ChatMessage, (ctx) => {
  // Server logic uses receivedAt (always present)
  const now = ctx.receivedAt;

  // UI display uses client time if available
  const displayTime = ctx.meta.timestamp ?? ctx.receivedAt;

  // For latency calculation, handle missing timestamp gracefully
  const latency = ctx.meta.timestamp
    ? ctx.receivedAt - ctx.meta.timestamp
    : null;
});

Edge case: What if a client on a slow mobile network sends a message that takes 10 seconds to arrive? Their meta.timestamp will be 10 seconds behind ctx.receivedAt. This is expected — network latency is real. Your UI can show "sent 10 seconds ago" while your rate limiter uses the actual arrival time.

Network partitions exaggerate this further: after a flaky connection heals you might see bursts of messages whose producer time lags minutes behind ingress. Use receivedAt to anchor deduplication windows — const cutoff = ctx.receivedAt - 30_000 — so replayed batches still fall inside a predictable server-defined horizon.

// Deduplicate messages that reappear within 30 seconds of ingress
const windowStart = ctx.receivedAt - 30_000;
const duplicate = await db.messages.findFirst({
  userId: ctx.ws.data.userId,
  checksum: ctx.meta.correlationId,
  receivedAt: { gte: windowStart },
});

if (duplicate) return; // Ignore replayed payload

Normalize Reserved Keys

This is a critical security boundary. Clients shouldn't be able to spoof server-generated fields.

// Security: Strip reserved server-only keys before validation
function normalizeInboundMessage(raw: unknown): unknown {
  if (!raw || typeof raw !== "object") return raw;

  const msg = raw as Record<string, unknown>;

  // Ensure meta exists
  if (!msg.meta || typeof msg.meta !== "object") {
    msg.meta = {};
  }

  // Strip reserved keys (clients cannot set these)
  const meta = msg.meta as Record<string, unknown>;
  delete meta.clientId; // Connection identity (server-only)
  delete meta.receivedAt; // Server timestamp (server-only)
  delete meta.senderId; // Origin tracking (server-only, set by publish())

  return msg;
}

Security tip: In bun-ws-router, this normalization happens automatically before schema validation. If a malicious client tries to send meta.receivedAt, it's stripped before your handler sees it. This prevents clients from faking server timestamps.

Error Handling for Suspicious Timestamps

When you detect timestamp manipulation, how should you respond?

import { z } from "zod";
import { createMessageSchema } from "bun-ws-router/zod";

const { messageSchema, ErrorMessage, ErrorCode } = createMessageSchema(z);

router.onMessage(ChatMessage, (ctx) => {
  // Check for obviously suspicious timestamps
  if (ctx.meta.timestamp) {
    const drift = ctx.receivedAt - ctx.meta.timestamp;

    if (drift < -5000) {
      // More than 5 seconds in the future = likely manipulation
      ctx.send(ErrorMessage, {
        code: ErrorCode.VALIDATION_FAILED,
        message: "Invalid timestamp",
      });
      return;
    }

    if (drift > 300000) {
      // More than 5 minutes stale = possible replay attack
      console.warn(`Stale message from ${ctx.ws.data.userId}: ${drift}ms old`);
      // You might allow it but flag for monitoring
    }
  }

  // Process normally...
});

Don't reject messages too aggressively — some clock skew is normal. But logging anomalies helps you detect patterns of abuse.

That response code lines up with error-handling.md: transport issues become VALIDATION_FAILED, leaving business logic free to return domain-specific errors.

Testing and Monitoring

Test Clock Skew in Unit Tests

Don't wait for production to discover timestamp issues. Test them.

Pro Tip: Fake time deliberately. In Bun or Jest you can jest.spyOn(Date, "now").mockReturnValue(Date.now() + 5000) (or use Sinon fake timers) to simulate clients that think it's the future, then verify your safeguards still trip.

import { describe, test, expect, beforeEach } from "bun:test";

describe("Rate limiting with clock skew", () => {
  test("rejects messages even if client lies about timestamp", () => {
    const rateLimiter = new RateLimiter();
    const userId = "test-user";

    // Send 10 messages in rapid succession
    for (let i = 0; i < 10; i++) {
      const message = {
        type: "CHAT",
        meta: {
          // Client lies: claims each message is 5 seconds apart
          timestamp: Date.now() + i * 5000,
        },
        payload: { text: `Message ${i}` },
      };

      const ctx = {
        receivedAt: Date.now(), // Server truth: all arrive at once
        meta: message.meta,
        payload: message.payload,
        ws: { data: { userId } },
      };

      // Should reject after rate limit threshold
      const result = rateLimiter.checkLimit(ctx);
      if (i < 10) expect(result).toBe(true);
      else expect(result).toBe(false);
    }
  });

  test("handles missing client timestamp gracefully", () => {
    const ctx = {
      receivedAt: Date.now(),
      meta: {}, // No timestamp from client
      payload: { text: "Hello" },
      ws: { data: { userId: "test" } },
    };

    // Should work fine without client timestamp
    expect(() => handleMessage(ctx)).not.toThrow();
  });
});

Monitor Timestamp Drift

Set up alerts for suspicious patterns:

import { metrics } from "./monitoring";

router.onMessage(ChatMessage, (ctx) => {
  if (ctx.meta.timestamp) {
    const drift = ctx.receivedAt - ctx.meta.timestamp;

    // Record drift for monitoring
    metrics.recordTimestampDrift(drift);

    // Alert on suspicious patterns
    if (drift < -1000) {
      // Client timestamp is in the future
      console.warn(`Future timestamp from ${ctx.ws.data.userId}: ${drift}ms`);
      metrics.increment("timestamp.future_dated");
    } else if (drift > 60000) {
      // Message is more than 1 minute old
      console.warn(`Stale timestamp from ${ctx.ws.data.userId}: ${drift}ms`);
      metrics.increment("timestamp.stale");
    }
  }
});

Pro tip: Pipe receivedAt - (ctx.meta.timestamp ?? ctx.receivedAt) into your metrics pipeline. The Android Open Source Project's docs note that devices can drift several seconds between syncs, so alert if your P95 crosses 5000–10000ms, or if future-dated counts spike — it likely means clients lost NTP or users disabled automatic time.

Performance: UUID v7 + Timestamp Indexing

If you're storing messages in a database, pair server timestamps with UUID v7 for efficient time-ordered queries:

import { uuidv7 } from "uuidv7";

router.onMessage(ChatMessage, async (ctx) => {
  // UUID v7 embeds timestamp in the ID itself
  const messageId = uuidv7();

  await db.messages.insert({
    id: messageId, // Contains timestamp in first 48 bits
    roomId: ctx.payload.roomId,
    text: ctx.payload.text,
    receivedAt: ctx.receivedAt, // Separate timestamp for queries
  });

  // Index on (roomId, receivedAt) for fast chronological queries
  // The UUID v7 ID allows efficient sorting without the index
});

Why this matters: In high-throughput systems, you can query by time range using either the UUID v7 prefix OR the receivedAt index. This gives you flexibility without sacrificing performance.

UI Best Practices

Display "Sent At" Time

// Client receives message
client.on(ChatBroadcast, (msg) => {
  const sentAt = msg.meta.timestamp ? new Date(msg.meta.timestamp) : new Date(); // Fallback to "now" if missing

  ui.renderMessage({
    text: msg.payload.text,
    sentAt: formatRelativeTime(sentAt), // "5 minutes ago"
  });
});

<!-- Svelte component -->
Sent {formatRelativeTime(message.meta?.timestamp ?? message.receivedAt)}

Optimistic Ordering

// Client optimistically orders by local time
const messages = [
  { text: "Hello", timestamp: Date.now() - 5000 },
  { text: "World", timestamp: Date.now() },
];

// Display ordered by client time (smooth UX)
messages.sort((a, b) => a.timestamp - b.timestamp);

// Server re-orders by receivedAt for persistence
// (eventual consistency reconciliation)

Common Mistakes to Avoid

Here are the timestamp bugs I see most often:

1. Using client time for expirations

// Pitfall: Client controls when things expire
if (Date.now() - ctx.meta.timestamp > TTL) {
  /* ... */
}

// Fix: Server owns TTL windows
if (Date.now() - ctx.receivedAt > TTL) {
  /* ... */
}

2. Sorting by client time in queries

// Pitfall: Messages appear out of order
.orderBy('meta.timestamp')

// Fix: Consistent server-side ordering
.orderBy('receivedAt')

3. Forgetting to validate latency calculations

// Pitfall: Can produce negative numbers
const latency = ctx.receivedAt - ctx.meta.timestamp;

// Fix: Validate range
const latency =
  ctx.meta.timestamp &&
  ctx.receivedAt - ctx.meta.timestamp >= 0 &&
  ctx.receivedAt - ctx.meta.timestamp < 60000
    ? ctx.receivedAt - ctx.meta.timestamp
    : null;

4. Using client time in audit logs

// Pitfall: Unreliable for compliance
auditLog.append({ action: "DELETE", time: ctx.meta.timestamp });

// Fix: Server time is legally defensible
auditLog.append({ action: "DELETE", time: ctx.receivedAt });

5. Baking client time into IDs

// Pitfall: Sortable IDs depend on client honesty
const id = `${ctx.meta.timestamp}-${ctx.ws.data.userId}`;

// Fix: Use server clocks for order, client data for context
const id = `${ctx.receivedAt}-${ctx.ws.data.userId}`; // or UUID v7 + receivedAt

Audit your codebase: Search for .timestamp in your WebSocket handlers. If it's used in any conditional logic (if, while, comparisons), double-check that it shouldn't be receivedAt instead. Grep tricks like rg "meta\\.timestamp" server/handlers surface subtle trust bugs fast.

Key Takeaways

Never trust client time for server logic — Rate limiting, ordering, TTL, audits must use server time (ctx.receivedAt)
Client time is for display only — "Sent 5 minutes ago" UI labels can use meta.timestamp
Capture and label server time early — Take it at ingress, keep the name (receivedAt) consistent everywhere
Make client timestamp optional — Not all clients need to send it; server provides fallback
Validate when mixing times — If calculating latency from client time, validate reasonable ranges
Test clock skew scenarios — Don't wait for production bugs; write tests that simulate malicious and misconfigured clients
Monitor timestamp drift — Alert on anomalies like future-dated timestamps or extreme staleness

Beyond WebSockets

This isn't just a WebSocket quirk. The same "trust ingress time, display producer time" pattern shows up anywhere untrusted producers attach clocks to their data:

HTTP APIs: Request timestamps (from client logs) vs. server processing time (from access logs)
Event streams: Event creation time (Kafka message timestamp) vs. ingestion time (when it hit your consumer)
IoT systems: Sensor reading time (from device clock) vs. gateway arrival time (from edge server)
Log aggregation: Application log time (when the log was written) vs. collector receipt time (when it reached your SIEM)
Mobile analytics: Event capture time (on device) vs. batch upload time (when the device synced)

In every case, the pattern is the same: producer time for user context, ingress time for system decisions.

Conclusion

Here's the uncomfortable truth: If your real-time system uses client timestamps for anything beyond UI display, you probably have a security bug. Maybe it hasn't been exploited yet. Maybe your users are honest and their clocks are accurate. But "probably" and "maybe" aren't good security models.

The fix is straightforward: capture server time at ingress (ctx.receivedAt), use it for all server logic, and treat client time (meta.timestamp) as untrusted UI metadata. Your rate limiter will actually work. Your audit logs will be defensible. Your message ordering will be consistent.

Take 10 minutes today to audit your WebSocket handlers. Search for .timestamp or meta.timestamp in your codebase. If you see it used in comparisons, rate limiting, expiration logic, or database ordering, you've found a bug worth fixing.

Quick audit question: where does your server still trust client time today, and what breaks if that trust evaporates?

Time is tricky in distributed systems. But with two timestamps — one trusted, one not — you can build systems that are both secure and user-friendly.

References

Clock drift in practice: Android Open Source Project, "Time Synchronization" (mobile devices can drift seconds between syncs)
Replay attacks: OWASP guide
Distributed systems time: Martin Kleppmann, Designing Data-Intensive Applications (Chapter 8: "The Trouble with Distributed Systems")
Vector clocks: Leslie Lamport, "Time, Clocks, and the Ordering of Events in a Distributed System" (classic background)

GitHub Security Notifications for Discord

Konstantin Tarkus — Sun, 28 Sep 2025 09:39:03 +0000

A practical guide for setting up automated security notifications from GitHub repositories to Discord channels.

Why Security Notifications Matter

Security events in your repositories need immediate attention. This guide helps you configure automated notifications so your team stays informed about:

Vulnerability discoveries and fixes
Security feature bypasses or disabled protections
Unauthorized access changes
Secret leaks and scanning results

Important Security Limitations

⚠️ Discord Webhook Security Notice:

Discord webhooks have no built-in authentication mechanism
Anyone with the webhook URL can send messages to your channel
There is no way to verify that messages come from GitHub
Treat webhook URLs as secrets and never expose them publicly

Discord Setup

1. Create a Private Security Channel

Right-click your Discord server → Create Channel
Name: #security (or #security-alerts)
Type: Text Channel
Private Channel: ✅ Enable
Permissions: Only security team members

2. Generate Webhook URL

Channel Settings → Integrations → Webhooks → New Webhook
Name: GitHub Security
Avatar: Upload GitHub logo (optional)
Copy Webhook URL → Save for GitHub configuration

GitHub Configuration

1. Repository Webhooks

Navigate to: Settings → Webhooks → Add webhook

Payload URL: [Your Discord webhook URL]/github
Content type: application/json
Secret: [Optional - validates requests FROM GitHub, but Discord cannot verify signatures]
SSL verification: Enable SSL verification

⚠️ Important: GitHub secrets only validate that webhooks come FROM GitHub to prevent spoofing. Discord webhooks have NO signature validation capability - Discord accepts any properly formatted request to the webhook URL. For signature validation, use a proxy service between GitHub and Discord.

2. Critical Security Events

Enable these events for immediate notification:

☑️ Code scanning alerts - Code scanning alert created, fixed in branch, or closed
☑️ Secret scanning alerts - Secrets scanning alert created, resolved, reopened, validated, or publicly leaked
☑️ Secret scanning alert locations - Secrets scanning alert location created
☑️ Dependabot alerts - Dependabot alert auto_dismissed, auto_reopened, created, dismissed, reopened, fixed, or reintroduced
☑️ Repository vulnerability alerts - (Note: Being deprecated, use Dependabot alerts)
☑️ Security and analyses - When security features are enabled/disabled
☑️ Repository advisories - Security advisories published for the repo

3. Access Control Events

Enable for access monitoring:

☑️ Branch protection configurations - All protections enabled/disabled
☑️ Branch protection rules - Individual rules created/edited/deleted
☑️ Collaborator add, remove, or changed - Team member access changes
☑️ Deploy keys - Deployment key additions/removals
☑️ Visibility changes - Repository made public/private

4. Security Bypass Events

Enable for policy compliance:

☑️ Dismissal requests for code scanning alerts - Alert dismissal tracking
☑️ Dismissal requests for secret scanning alerts - Secret dismissal tracking
☑️ Bypass requests for push rulesets - Push rule bypass requests
☑️ Bypass requests for secret scanning push protections - Secret push bypass

Best Practices

Channel Management

Keep the security channel private and restricted
Add only security team members and repository maintainers
Use thread discussions for detailed investigation
Pin important security policies and contacts

Notification Hygiene

Start with critical events only, expand gradually
Review and tune notifications weekly for first month
Document response procedures for each alert type
Set up on-call rotation for critical alerts

Response Workflows

Acknowledge alerts within 15 minutes during business hours (organizational policy)
Assign owner for each security issue
Use GitHub issue templates for security incident tracking
Post resolution summaries back to the channel

Note: Response times are organizational recommendations based on industry standards for critical security incidents, not technical requirements from GitHub or Discord.

Testing Your Setup

Configure the webhook in your repository
Make a simple change (e.g., push a commit or create an issue)
Check Discord channel for the notification
Note: The GitHub "Test" button returns a 400 error because GitHub's test payload format doesn't match Discord's expected message schema. This is normal - the webhook is working correctly.
For security events, try creating a test file with a fake API key to trigger secret scanning

Event Priority Levels

🚨 Critical (Immediate Response Required)

Secret scanning alerts (publicly leaked)
Code scanning alerts (high/critical severity)
Repository vulnerability alerts (high/critical CVEs)
Security features disabled

⚠️ High (Response Within Hours)

Dependabot alerts (high/critical)
Branch protection disabled
Unauthorized collaborator changes
Deploy key modifications

ℹ️ Medium (Monitor and Review)

Security bypass requests
Alert dismissal requests
Branch protection rule changes
Completed security scans

Advanced Configuration (Optional)

Multiple Repositories

For teams managing multiple repositories:

Use organization-level webhooks for centralized management
Create separate channels for different severity levels (#security-critical, #security-info)
Start simple: same webhook for all repos, then customize as needed

Simple Enhancements

GitHub Actions: Filter events before sending to Discord (example: only notify for public repos)
Discord Bots: Use bots for two-way communication (acknowledge alerts from Discord)
Monitoring: Set up a simple daily/weekly summary of security events

Troubleshooting

Webhook not triggering:

Verify webhook URL format includes /github suffix (required for GitHub integration)
Check GitHub webhook delivery logs in Settings → Webhooks → Recent Deliveries
Ensure Discord channel permissions allow webhook posts
Note: GitHub's "test" payload will show a 400 error - this is normal

Missing notifications:

Review selected events in GitHub webhook configuration
Test with a simple push event first
Check Discord server notification settings

Too many notifications:

Start with critical events only
Use Discord thread mode for detailed discussions
Consider time-based filtering for non-critical events
Discord rate limit: ~5 requests per 2 seconds per webhook

Security Best Practices

Webhook URL Protection

Never expose webhook URLs in client-side code or public repositories
Store webhook URLs in environment variables or secure secret management systems
Rotate webhook URLs quarterly or immediately if exposed
Use .gitignore to exclude any files containing webhook URLs

Webhook Rotation Procedure

Create new webhook in Discord (keep old one active)
Update GitHub webhook configuration with new URL
Test new webhook with a commit or issue
Once confirmed working, delete old Discord webhook
Document rotation in security log

Additional Security Measures

Consider using a proxy service between GitHub and Discord for additional validation
Implement monitoring for unusual webhook activity patterns
Use Discord bots with proper authentication for sensitive operations
Restrict channel access to security team members only

Security Reminder: Discord webhooks cannot authenticate senders. Any service or person with the webhook URL can post messages. This is a fundamental limitation of Discord's webhook system.

🚨 Critical: If a webhook URL is ever exposed or leaked, rotate it immediately. Exposed webhook URLs are compromised security credentials.

Browser Auto-Open: Seamless OAuth UX for CLI Tools

Konstantin Tarkus — Wed, 20 Aug 2025 17:36:34 +0000

Picture this: you're setting up a new CLI tool, and it needs to authenticate with GitHub. Instead of hunting for API keys or copying tokens, the tool simply opens your browser, you click "Authorize," and you're done. That magic moment — when the browser opens automatically — transforms OAuth from a technical hurdle into a delightful experience.

But getting that browser launch right is harder than it looks. Different operating systems, edge cases with headless environments, custom browser preferences, and security considerations all conspire to turn a simple open() call into a complex engineering challenge.

The Art of Opening Browsers Cross-Platform

Opening a browser sounds trivial until you realize every operating system does it differently. macOS uses open, Windows wants start, and Linux fragments across xdg-open, gnome-open, and countless others. Then there's WSL, where you need to reach back to Windows. And don't forget about users with custom default browsers or those running in Docker containers.

The open package has become the de facto standard for handling this complexity, abstracting away platform differences with a simple API:

import open from "open";

// Opens in the user's default browser
await open("https://github.com/login/oauth/authorize?...");

// Force a specific browser
await open(url, { app: { name: "firefox" } });

// Non-blocking for better UX
open(url, { wait: false });

Under the hood, open handles an impressive array of edge cases. It detects WSL and uses powershell.exe to launch Windows browsers. It respects the BROWSER environment variable for Linux users who've customized their setup. It even handles spaces in URLs and special characters that would break naive implementations.

Smart Defaults with Escape Hatches

The key to great developer experience is making the common case trivial while keeping the complex cases possible. In oauth-callback, browser launching is enabled by default but fully configurable:

// Default behavior - just works
const result = await getAuthCode({
  authorizationUrl: "https://oauth.example.com/authorize?...",
});

// Disable for CI/headless environments
const result = await getAuthCode({
  authorizationUrl: url,
  openBrowser: false, // User must manually open the URL
});

// Custom browser handling
const result = await getAuthCode({
  authorizationUrl: url,
  openBrowser: false,
});
// Implement your own logic
await myCustomBrowserLauncher(url);

This flexibility becomes crucial in different environments. CI systems often run headless, so automatic browser launching would fail. Some users prefer copying URLs to browsers on different machines. Others might be running in containers or SSH sessions where browser access is impossible.

Handling Launch Failures Gracefully

Browser launching can fail for numerous reasons: the system might be headless, the user might have unusual configurations, or security policies might block the operation. Rather than crashing, provide a fallback:

async function launchBrowser(url: string, options: GetAuthCodeOptions) {
  if (!options.openBrowser) {
    console.log(`Please open this URL in your browser:\n${url}`);
    return;
  }

  try {
    await open(url);
    console.log("Opening browser...");
  } catch (error) {
    // Fallback to manual URL opening
    console.log("Could not open browser automatically.");
    console.log(`Please open this URL manually:\n${url}`);
  }
}

Some tools go further, displaying QR codes for mobile authentication or providing platform-specific instructions when automatic launching fails. The GitHub CLI, for example, offers to wait if you need to switch to a different device.

Non-Blocking for Better Performance

A subtle but important detail: browser launching should never block your OAuth flow. Users might take time to authenticate, the browser might be slow to start, or they might ignore the prompt entirely. Your server should be ready immediately:

export async function getAuthCode(options: GetAuthCodeOptions) {
  const server = createCallbackServer();

  try {
    // Start server first
    await server.start({
      port: options.port,
      hostname: options.hostname,
    });

    // Launch browser without waiting
    if (options.openBrowser) {
      // Don't await - let it run in parallel
      open(options.authorizationUrl).catch(() => {
        // Log but don't fail
        console.log("Note: Could not open browser automatically");
      });
    }

    // Server is ready regardless of browser status
    const result = await server.waitForCallback(
      options.callbackPath,
      options.timeout,
    );

    return result;
  } finally {
    await server.stop();
  }
}

This pattern ensures your callback server is always ready, even if the browser takes 10 seconds to launch or fails entirely. Users who manually copy the URL won't face race conditions, and automated testing remains reliable.

Testing Without Real Browsers

Automated testing shouldn't spawn actual browser windows. The openBrowser flag enables test-friendly behavior:

// In tests
const mockProvider = new MockOAuthProvider();

const result = await getAuthCode({
  authorizationUrl: mockProvider.authUrl,
  openBrowser: false, // Prevent browser launch
  port: 0, // Use random available port
});

// Simulate the OAuth callback programmatically
await mockProvider.completeAuth({
  code: "test-auth-code",
  state: "test-state",
});

expect(result.code).toBe("test-auth-code");

For integration with Model Context Protocol servers or other automation scenarios, you might want programmatic control:

export const browserAuth = () => ({
  async authenticate(params: AuthenticateParams) {
    const options = {
      authorizationUrl: params.url,
      openBrowser: process.env.CI ? false : true,
      timeout: params.timeout,
    };

    if (!options.openBrowser) {
      // MCP client handles URL display
      await params.onAuthUrl(params.url);
    }

    return getAuthCode(options);
  },
});

Security Considerations

Browser launching introduces several security considerations worth addressing:

1. URL Validation: Always validate authorization URLs before opening them. Malicious URLs could lead to phishing or execute local protocols:

function validateAuthUrl(url: string): void {
  const parsed = new URL(url);

  // Only allow HTTPS (with localhost exception for testing)
  if (
    parsed.protocol !== "https:" &&
    !(parsed.protocol === "http:" && parsed.hostname === "localhost")
  ) {
    throw new Error("Authorization URL must use HTTPS");
  }

  // Prevent file:// and other dangerous protocols
  if (!["http:", "https:"].includes(parsed.protocol)) {
    throw new Error("Invalid protocol in authorization URL");
  }
}

2. Command Injection: When spawning browser processes, always use array arguments rather than string concatenation to prevent command injection:

// WRONG - vulnerable to injection
exec(`open ${url}`);

// RIGHT - safe from injection
spawn("open", [url]);

3. User Consent: Consider warning users before opening browsers, especially if the URL isn't from a trusted source:

if (options.requireConfirmation) {
  const answer = await prompt("Open browser for authentication? (y/n): ");
  if (answer.toLowerCase() !== "y") {
    console.log(`Please open this URL manually:\n${url}`);
    return;
  }
}

Platform-Specific Enhancements

Different platforms offer unique opportunities to enhance the browser-opening experience:

macOS: Use AppleScript for more control:

// Open in a specific browser window
await runAppleScript(`
  tell application "Google Chrome"
    open location "${url}"
    activate
  end tell
`);

Windows: Leverage PowerShell for WSL compatibility:

if (isWSL()) {
  // Use PowerShell to open in Windows from WSL
  await exec(`powershell.exe -Command "Start '${url}'"`);
}

Linux: Respect desktop environment preferences:

const openers = [
  process.env.BROWSER,
  "xdg-open",
  "gnome-open",
  "kde-open",
].filter(Boolean);

for (const opener of openers) {
  try {
    await spawn(opener, [url]);
    break;
  } catch {
    // Try next opener
  }
}

Real-World Patterns

Leading CLI tools have evolved consistent patterns for browser-based authentication:

GitHub CLI shows the authorization URL and offers to wait if you're authenticating on another device:

? Where do you want to authenticate?
> Login in browser
  Paste authentication token

Vercel CLI provides clear feedback about what's happening:

> Opening browser for authentication...
> If browser doesn't open, visit:
> https://vercel.com/cli/login/...

Google Cloud SDK handles headless environments elegantly:

Go to the following link in your browser:
    https://accounts.google.com/o/oauth2/auth?...

Enter authorization code:

These patterns share common principles: clear communication, graceful fallbacks, and respect for user preferences.

Conclusion

Browser auto-opening might seem like a minor feature, but it's the difference between a tool that feels modern and one that feels clunky. By handling platform differences, providing smart defaults, failing gracefully, and respecting security boundaries, you create an authentication experience that users barely notice — the highest compliment for developer tools.

The oauth-callback library encapsulates these best practices in a simple API. Whether you're building a CLI tool, desktop application, or automation script, proper browser handling transforms OAuth from a necessary evil into a smooth, professional experience.

Remember: the best authentication is the one users don't have to think about. Make it automatic when possible, manual when necessary, and always clear about what's happening. Your users will thank you with their continued engagement rather than authentication abandonment.

Ready to implement seamless OAuth in your CLI tool? Check out oauth-callback for production-ready browser handling, cross-platform support, and battle-tested edge case management.

Building a Localhost OAuth Callback Server in Node.js

Konstantin Tarkus — Mon, 18 Aug 2025 10:38:36 +0000

When building CLI tools or desktop applications that integrate with OAuth providers, you face a unique challenge: how do you capture the authorization code when there's no public-facing server to receive the callback? The answer lies in a clever technique that's been right under our noses — spinning up a temporary localhost server to catch the OAuth redirect.

This tutorial walks through building a production-ready OAuth callback server that works across Node.js, Deno, and Bun. We'll cover everything from the basic HTTP server setup to handling edge cases that trip up most implementations.

Understanding the OAuth Callback Flow

Before diving into code, let's clarify what we're building. In a typical OAuth 2.0 authorization code flow, your application redirects users to an authorization server (like GitHub or Google), where they grant permissions. The authorization server then redirects back to your application with an authorization code.

For web applications, this redirect goes to a public URL. But for CLI tools and desktop apps, we use a localhost UR — typically http://localhost:3000/callback. The OAuth provider redirects to this local address, and our temporary server captures the authorization code from the query parameters.

This approach is explicitly blessed by OAuth 2.0 for Native Apps (RFC 8252) and is used by major tools like the GitHub CLI and Google's OAuth libraries.

Setting Up the Basic HTTP Server

The first step is creating an HTTP server that can listen on localhost. Modern JavaScript runtimes provide different APIs for this, but we can abstract them behind a common interface using Web Standards Request and Response objects.

interface CallbackServer {
  start(options: ServerOptions): Promise<void>;
  waitForCallback(path: string, timeout: number): Promise<CallbackResult>;
  stop(): Promise<void>;
}

function createCallbackServer(): CallbackServer {
  // Runtime detection
  if (typeof Bun !== "undefined") return new BunCallbackServer();
  if (typeof Deno !== "undefined") return new DenoCallbackServer();
  return new NodeCallbackServer();
}

Each runtime implementation follows the same pattern: create a server, listen for requests, and resolve a promise when the callback arrives. Here's the Node.js version that bridges between Node's http module and Web Standards:

class NodeCallbackServer implements CallbackServer {
  private server?: http.Server;
  private callbackPromise?: {
    resolve: (result: CallbackResult) => void;
    reject: (error: Error) => void;
  };

  async start(options: ServerOptions): Promise<void> {
    const { createServer } = await import("node:http");

    return new Promise((resolve, reject) => {
      this.server = createServer(async (req, res) => {
        const request = this.nodeToWebRequest(req, options.port);
        const response = await this.handleRequest(request);

        res.writeHead(
          response.status,
          Object.fromEntries(response.headers.entries()),
        );
        res.end(await response.text());
      });

      this.server.listen(options.port, options.hostname, resolve);
      this.server.on("error", reject);
    });
  }

  private nodeToWebRequest(req: http.IncomingMessage, port: number): Request {
    const url = new URL(req.url!, `http://localhost:${port}`);
    const headers = new Headers();

    for (const [key, value] of Object.entries(req.headers)) {
      if (typeof value === "string") {
        headers.set(key, value);
      }
    }

    return new Request(url.toString(), {
      method: req.method,
      headers,
    });
  }
}

The beauty of this approach is that once we convert to Web Standards, the actual request handling logic is identical across all runtimes.

Capturing the OAuth Callback

The heart of our server is the callback handler. When the OAuth provider redirects back, we need to extract the authorization code (or error) from the query parameters:

private async handleRequest(request: Request): Promise<Response> {
  const url = new URL(request.url);

  if (url.pathname === this.callbackPath) {
    const params: CallbackResult = {};

    // Extract all query parameters
    for (const [key, value] of url.searchParams) {
      params[key] = value;
    }

    // Resolve the waiting promise
    if (this.callbackPromise) {
      this.callbackPromise.resolve(params);
    }

    // Return success page to the browser
    return new Response(this.generateSuccessHTML(), {
      status: 200,
      headers: { "Content-Type": "text/html" }
    });
  }

  return new Response("Not Found", { status: 404 });
}

Notice how we capture all query parameters, not just the authorization code. OAuth providers send additional information like state for CSRF protection, and error responses include error and error_description fields. Our implementation preserves everything for maximum flexibility.

Handling Timeouts and Cancellation

Real-world OAuth flows can fail in numerous ways. Users might close the browser, deny permissions, or simply walk away. Our server needs robust timeout and cancellation handling:

async waitForCallback(path: string, timeout: number): Promise<CallbackResult> {
  this.callbackPath = path;

  return new Promise((resolve, reject) => {
    let isResolved = false;

    // Set up timeout
    const timer = setTimeout(() => {
      if (!isResolved) {
        isResolved = true;
        reject(new Error(`OAuth callback timeout after ${timeout}ms`));
      }
    }, timeout);

    // Wrap resolve/reject to handle cleanup
    const wrappedResolve = (result: CallbackResult) => {
      if (!isResolved) {
        isResolved = true;
        clearTimeout(timer);
        resolve(result);
      }
    };

    this.callbackPromise = {
      resolve: wrappedResolve,
      reject: (error) => {
        if (!isResolved) {
          isResolved = true;
          clearTimeout(timer);
          reject(error);
        }
      }
    };
  });
}

Supporting AbortSignal enables programmatic cancellation, essential for GUI applications where users might close a window mid-flow:

if (signal) {
  if (signal.aborted) {
    throw new Error("Operation aborted");
  }

  const abortHandler = () => {
    this.stop();
    if (this.callbackPromise) {
      this.callbackPromise.reject(new Error("Operation aborted"));
    }
  };

  signal.addEventListener("abort", abortHandler);
}

Providing User Feedback

When users complete the OAuth flow, they see a browser page indicating success or failure. Instead of a blank page or cryptic message, provide clear feedback with custom HTML:

function generateCallbackHTML(
  params: CallbackResult,
  templates: Templates,
): string {
  if (params.error) {
    // OAuth error - show error page
    return templates.errorHtml
      .replace(/{{error}}/g, params.error)
      .replace(/{{error_description}}/g, params.error_description || "");
  }

  // Success - show confirmation
  return (
    templates.successHtml ||
    `
    <html>
      <body style="font-family: system-ui; padding: 2rem; text-align: center;">
        <h1>✅ Authorization successful!</h1>
        <p>You can now close this window and return to your terminal.</p>
      </body>
    </html>
  `
  );
}

For production applications, consider adding CSS animations, auto-close functionality, or deep links back to your desktop application.

Security Considerations

While localhost servers are inherently more secure than public endpoints, several security measures are crucial:

1. Bind to localhost only: Never bind to 0.0.0.0 or public interfaces. This prevents network-based attacks:

this.server.listen(port, "localhost"); // NOT "0.0.0.0"

2. Validate the state parameter: OAuth's state parameter prevents CSRF attacks. Generate it before starting the flow and validate it in the callback:

const state = crypto.randomBytes(32).toString("base64url");
const authUrl = `${provider}/authorize?state=${state}&...`;

// In callback handler
if (params.state !== expectedState) {
  throw new Error("State mismatch - possible CSRF attack");
}

3. Close the server immediately: Once you receive the callback, shut down the server to minimize the attack surface:

const result = await server.waitForCallback("/callback", 30000);
await server.stop(); // Always cleanup

4. Use unpredictable ports when possible: If your OAuth provider supports dynamic redirect URIs, use random high ports to prevent port-squatting attacks.

Putting It All Together

Here's a complete example that ties everything together:

import { createCallbackServer } from "./server";
import { spawn } from "child_process";

export async function getAuthCode(authUrl: string): Promise<string> {
  const server = createCallbackServer();

  try {
    // Start the server
    await server.start({
      port: 3000,
      hostname: "localhost",
      successHtml: "<h1>Success! You can close this window.</h1>",
      errorHtml: "<h1>Error: {{error_description}}</h1>",
    });

    // Open the browser
    const opener =
      process.platform === "darwin"
        ? "open"
        : process.platform === "win32"
          ? "start"
          : "xdg-open";
    spawn(opener, [authUrl], { detached: true });

    // Wait for callback
    const result = await server.waitForCallback("/callback", 30000);

    if (result.error) {
      throw new Error(`OAuth error: ${result.error_description}`);
    }

    return result.code!;
  } finally {
    // Always cleanup
    await server.stop();
  }
}

// Usage
const code = await getAuthCode(
  "https://github.com/login/oauth/authorize?" +
    "client_id=xxx&redirect_uri=http://localhost:3000/callback",
);

Best Practices and Next Steps

Building a robust OAuth callback server requires attention to detail, but the patterns are consistent across implementations. Key takeaways:

Use Web Standards APIs for cross-runtime compatibility
Handle all error cases including timeouts and user cancellation
Provide clear user feedback with custom success/error pages
Implement security measures like state validation and localhost binding
Clean up resources by always stopping the server after use

This localhost callback approach has become the de facto standard for OAuth in CLI tools. Libraries like oauth-callback provide production-ready implementations with additional features like automatic browser detection, token persistence, and PKCE support.

Modern OAuth is moving toward even better solutions like Device Code Flow for headless environments and Dynamic Client Registration for eliminating pre-shared secrets. But for now, the localhost callback server remains the most widely supported and user-friendly approach for bringing OAuth to command-line tools.

Ready to implement OAuth in your CLI tool? Check out the complete oauth-callback library for a battle-tested implementation that handles all the edge cases discussed here.

This tutorial is part of a series on modern authentication patterns. Follow @koistya for more insights on building secure, user-friendly developer tools.

Why Your CLI Tool Needs OAuth (Not API Keys)

Konstantin Tarkus — Mon, 18 Aug 2025 09:58:09 +0000

Remember the last time you installed a CLI tool and it asked for your API key? You probably hunted through documentation, navigated to some settings page, generated a key, then carefully copied it into a config file. Now multiply that friction by every user of your tool.

There's a better way, and it's been hiding in plain sight.

The API Key Problem Nobody Talks About

API keys seem simple on the surface. Generate once, use forever. But that simplicity masks serious problems that compound as your tool gains adoption.

First, there's the security nightmare. Users paste API keys into dotfiles, commit them to repositories, share them in documentation. Once leaked, an API key becomes a permanent liability — there's no way to know who has it or where it's been copied. Unlike passwords that users might change periodically, API keys tend to live forever in forgotten config files.

Then there's the user experience disaster. Finding where to generate an API key requires navigating documentation that varies wildly between services. GitHub hides them under Developer Settings. Notion requires creating an integration. Slack needs an entire app configuration. Each service has its own maze, and your users have to navigate them all.

But the real killer? API keys can't adapt. They're static credentials with fixed permissions. Need to request additional scopes? Your users must generate a new key. Want to implement granular permissions? Too bad — it's all or nothing. And forget about temporary access or delegation; API keys weren't designed for modern authorization patterns.

OAuth: The Solution That's Already Everywhere

OAuth isn't new technology — it's the authentication standard that already powers most of the web. When you click "Sign in with Google" or authorize a GitHub integration, you're using OAuth. The difference is that most CLI developers haven't realized how perfectly it fits their needs.

Here's what happens when your CLI uses OAuth: A user runs your command, their browser opens, they click "Authorize," and they're done. No hunting for settings pages. No copying cryptic strings. No permanent credentials stored on disk.

The security benefits are immediate. OAuth tokens expire automatically, reducing the blast radius of any leak. Refresh tokens allow seamless re-authentication without user intervention. And when a user revokes access through the service's UI, it takes effect immediately — no orphaned API keys floating around.

But the real magic is in the flexibility. Need read-only access initially but write access for certain operations? OAuth handles incremental authorization naturally. Want to access multiple services? OAuth makes it seamless. Building a tool for teams? OAuth tokens can carry user identity, enabling proper audit trails and access control.

Making It Work in Practice

The technical implementation is surprisingly straightforward. Your CLI spins up a temporary local server, opens the user's browser to the OAuth authorization URL, and waits for the callback. When the user authorizes, the service redirects back to localhost with an authorization code. Your CLI exchanges that code for tokens and shuts down the server.

import { getAuthCode } from "oauth-callback";

const result = await getAuthCode(
  "https://github.com/login/oauth/authorize?" +
    new URLSearchParams({
      client_id: process.env.CLIENT_ID,
      redirect_uri: "http://localhost:3000/callback",
      scope: "repo user",
    }),
);

// Exchange code for tokens
const tokens = await exchangeCodeForTokens(result.code);

Modern libraries handle the complexity. Automatic browser launching, secure token storage, refresh token rotation — it's all solved problems. Tools like oauth-callback provide production-ready implementations that work across Node.js, Deno, and Bun.

For services supporting Dynamic Client Registration, you don't even need pre-registered credentials. Your CLI can register itself on the fly, eliminating the chicken-and-egg problem of distributing client secrets.

The Future Is Already Here

Major CLI tools are already making this shift. The GitHub CLI uses OAuth for authentication. Vercel's CLI leverages browser-based auth flows. Model Context Protocol servers are standardizing on OAuth for secure access to AI tools.

The ecosystem is ready. Every major platform supports OAuth. Libraries exist for every language. Browser automation is a solved problem. The only thing holding us back is inertia — the assumption that CLI tools must use API keys because that's how it's always been done.

Your users deserve better than managing a keychain of API credentials. They deserve authentication that's secure by default, that respects principle of least privilege, and that just works. OAuth delivers all of that, today.

Stop asking your users for API keys. Start using OAuth. Your users — and your security team — will thank you.

Ready to implement OAuth in your CLI tool? Check out oauth-callback, a lightweight library that handles the entire flow with just a few lines of code.

# Why I Built MCP Client Generator (And Why You Should Care)

Konstantin Tarkus — Wed, 13 Aug 2025 14:23:23 +0000

⚠️ Upfront disclaimer: This is an early prototype exploring new approaches to API integration. It's not production-ready, but I'm sharing it to gather feedback from developers facing similar challenges.

Picture this: You're building with AI coding assistants like Claude or GitHub Copilot, and they're using MCP tools to interact with your services. But here's the catch – inefficient tool usage can dramatically increase your token costs. A single poorly optimized loop calling APIs could burn through tokens faster than you expect.

I learned this the hard way. My AI assistant was making individual API calls in a loop, consuming tokens at an alarming rate. That's when I realized: we need a better way to interact with MCP servers – one that's both cost-effective and developer-friendly.

The Hidden Cost of AI Tool Usage

You know the drill – you need to connect to GitHub, Notion, Linear, and multiple other services. Each one has its own SDK quirks, authentication dance, and type definitions that may or may not be up-to-date. But there's a bigger problem:

When AI agents use MCP tools inefficiently, your costs can escalate quickly.

Instead of letting AI assistants make hundreds of individual tool calls, what if we could generate efficient, batched automation scripts? What if we could have type-safe clients that encourage best practices? What if authentication could just... work?

That's when I discovered the potential of the Model Context Protocol (MCP) and decided to build something to solve this problem.

The Integration Challenge Many Developers Face

Whether you're a solo developer automating your workflow or part of a startup building integrations, you've likely encountered this scenario:

Create GitHub issues from Notion pages
Sync tasks with Linear for bug tracking
Move data between multiple platforms
Do it all with proper TypeScript support

The traditional approach? Install multiple SDKs, manage different authentication flows, deal with various error handling patterns, and hope everything stays in sync. Oh, and don't forget to create OAuth applications for each service – complete with client IDs and secrets that you'll need to manage securely.

The boilerplate accumulates quickly.

Enter MCP Client Generator: A Prototype

Here's what I'm experimenting with:

import { notion, github, linear } from "./lib/mcp-client";

// One command will generate all of this with full type safety
const page = await notion.createPage({
  title: "Bug Report: Login Issues",
  content: "Users are reporting authentication failures...",
});

const issue = await github.createIssue({
  title: page.title,
  body: page.content,
});

await linear.createIssue({
  title: `Bug: ${page.title}`,
  description: `GitHub Issue: ${issue.html_url}`,
  teamId: "engineering",
});

That's the goal. Three services, fully typed, with a single configuration file:

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "linear": {
      "type": "sse",
      "url": "https://mcp.linear.app/sse"
    }
  }
}

The Authentication Reality

Here's what I'm exploring: simplified OAuth setup where possible.

Traditional approach:

Go to GitHub's developer settings
Create a new OAuth app
Configure redirect URIs
Copy client ID and secret
Repeat for each service
Manage secrets securely
Handle token refresh logic
Deal with different OAuth flows per service

The idealized MCP approach (when fully implemented):

Run npx mcp-client-gen
Configure your MCP server endpoints
Authenticate through browser redirect
Tokens stored locally for reuse

Reality check: This relies on RFC 7591 Dynamic Client Registration, which:

Isn't universally supported - Many services don't allow dynamic registration
Has security implications - Some orgs prohibit dynamic client creation
Still requires browser auth - You'll be redirected to approve access
Needs secure token storage - We handle refresh, but you manage security

For services without dynamic registration, you'll still need to create OAuth apps manually and provide credentials in your config.

The Potential for Cost Optimization

The Efficiency Problem: When using AI assistants with APIs, inefficient patterns can increase costs. For example, making 100 individual API calls instead of batched requests means more tokens for tool invocations, responses, and error handling.

The Proposed Solution: Generate automation scripts using MCP Client Generator that could:

Batch operations efficiently
Use proper pagination
Cache responses when appropriate
Provide type safety to prevent errors that trigger retries

While I don't have exact metrics yet (the tool is still in development), the potential for cost reduction is significant based on the difference between individual vs batched API operations.

Potential Use Cases

Cross-Platform Data Sync: Scripts that keep GitHub issues and Notion project pages in sync, automatically updating status changes across platforms.

Automated Reporting: Weekly reports pulling data from GitHub (commits, PRs), Jira (completed tickets), and Slack (team activity), then creating summaries in Notion.

Incident Response: When monitoring systems detect issues, automatically create Slack threads, open GitHub issues, and update status pages with proper context.

Content Pipeline: Write technical content in one platform and cross-post to Dev.to, LinkedIn, and company blogs with platform-specific formatting.

Current State & Roadmap

Actually Implemented (You can test these today)

✅ CLI interface and configuration parsing
✅ Interactive prompts with smart defaults
✅ Basic scaffolding for client generation
✅ Multiple config format support (.mcp.json, .cursor/, .vscode/)

Not Yet Working (Under Development)

❌ MCP server introspection (cannot connect to servers yet)
❌ OAuth authentication (no auth flow implemented)
❌ Type generation from live servers (uses mocks currently)
❌ Error handling and retry logic
❌ Streaming support

Reality check: The core generation pipeline exists, but it doesn't actually connect to MCP servers yet. Think of it as a foundation waiting for the protocol implementation.

Prerequisites (Current)

MCP servers must support HTTP transport
Servers need proper schema exposure
Node.js 18+ or Bun runtime

Performance Considerations

Initial connection overhead (estimated ~200ms)
Type generation at build time (not runtime)
Tree-shakable output for optimal bundle size

Addressing Common Questions

"Why not just use existing SDKs?"

This is a valid point. Traditional SDKs are mature and well-tested. However, they present challenges when you need:

Unified patterns across multiple services
Consistent authentication handling
Type safety that stays in sync with API changes
Integration with AI coding assistants

MCP Client Generator aims to complement, not replace, existing SDKs. It's specifically designed for scenarios requiring unified access to multiple MCP-enabled services.

When to stick with traditional SDKs

Production systems requiring battle-tested reliability
Complex operations that need SDK-specific optimizations
Single service integration where you don't need cross-platform consistency
Teams with existing SDK expertise and established patterns

When this tool might help (once complete)

Prototyping multi-service integrations quickly
AI-assisted development where consistent patterns reduce token usage
Small teams managing many integrations without dedicated expertise per SDK
Exploratory projects testing MCP capabilities

"What's the learning curve?"

Fair question. While MCP itself is new, the generated clients use familiar JavaScript/TypeScript patterns. If you can use an SDK, you can use the generated clients. The main learning curve is understanding MCP configuration, which we're working to simplify with better documentation and examples.

"What about existing integration platforms?"

Tools like Zapier, n8n, and Make excel at no-code workflows. MCP Client Generator targets a different need:

Type safety in your code
Custom business logic
Direct API access without middleware
Integration with your existing codebase
Cost-effective high-volume operations

"Is dynamic client registration secure?"

RFC 7591 Dynamic Client Registration is an OAuth 2.1 standard with both benefits and risks:

Security benefits:

Clients register with limited scopes
Short-lived, refreshable tokens
No hardcoded secrets in code
Unique registration per application

Security considerations:

Token storage: Generated clients store tokens locally - secure your development environment
Scope creep: Dynamic registration might request broader permissions than needed
Audit trails: Harder to track dynamically created clients in your OAuth provider
Organizational policies: Many enterprises prohibit dynamic registration

Best practice: Use dynamic registration for development/prototyping. For production, consider traditional OAuth apps with proper secret management (environment variables, secret stores, etc.).

Always review security implications for your specific use case and comply with your organization's security policies.

"What if MCP doesn't achieve widespread adoption?"

A legitimate concern. MCP is emerging technology currently supported by:

Claude Desktop - Anthropic's desktop app with MCP support
Cline (formerly Claude Dev) - VS Code extension using MCP
Continue.dev - Open-source AI code assistant
Official MCP servers - GitHub repo includes filesystem, GitHub, GitLab, Slack, and Google Drive implementations

The ecosystem is small but growing. Even if adoption remains limited, the code generation patterns have value beyond MCP. The project could adapt to other protocols if needed.

"How do you handle API changes and maintenance?"

The maintenance challenge is real. Here's the proposed approach:

Regeneration workflow: Run mcp-client-gen again to update types when APIs change
Version pinning: Lock to specific MCP server versions in your config
Git diff review: Generated code changes are reviewable like any dependency update
Fallback strategy: Keep previous generated versions if servers break compatibility

Reality check: This adds a build step and requires you to manage regeneration. It's a tradeoff between automation and control.

Why I'm Sharing This Prototype Now

AI-assisted development is changing how we build integrations, but the tooling hasn't caught up. I'm sharing this early prototype to:

Validate the problem: Do others face similar multi-service integration challenges?
Gather feedback: What would make this actually useful?
Find collaborators: Who wants to help build this?

This isn't a launch – it's an invitation to experiment together.

What's Next

Immediate priorities:

Complete MCP protocol implementation
Robust server introspection
Comprehensive error handling
Streaming support for real-time APIs
Plugin system for custom transformations

But I'm most interested in community input on priorities.

How You Can Help

For Developers

Test the proof of concept: Try npx mcp-client-gen and share feedback
Contribute to development:
- MCP server introspection
- Authentication flows
- Error handling patterns
- Test coverage

For Potential Users

Share your use cases: What MCP servers do you need?
Provide feedback: What would make this useful for your workflow?
Help with documentation: Explain concepts to newcomers

For MCP Server Implementers

Feedback on approach: What patterns work best?
Schema standards: How should servers expose capabilities?

Get Started

# Try the interactive mode
npx mcp-client-gen

# Or quick mode with defaults
npx mcp-client-gen -y

NPM: npmjs.com/package/mcp-client-gen
GitHub: github.com/kriasoft/mcp-client-gen
Issues: Report bugs or request features
Discussions: Join the conversation

The Vision

I believe we're at an inflection point in API integration, especially with AI-assisted development. While traditional SDKs remain valuable, there's room for new approaches that better serve modern development workflows.

The future I'm building toward:

Configuration-driven service connections
Type safety as a default
Abstracted authentication complexity
Efficient clients for both AI and human developers

This is an early-stage project with ambitious goals. If you're interested in shaping how developers interact with MCP services, I'd love your input and collaboration.

The MCP Client Generator is MIT licensed and available on GitHub. If this project helps you build amazing integrations, consider sponsoring the development to support continued progress.

Zero-Wait PR Previews: The Pre-Configured Slots Pattern

Konstantin Tarkus — Fri, 25 Jul 2025 11:46:25 +0000

Zero-Wait PR Previews: The Pre-Configured Slots Pattern

Ever waited for PR preview environments to spin up? Yeah, me too. Here's a pattern that changed the game for our team: pre-configured deployment slots with deterministic routing.

The Problem

Traditional PR preview workflows go something like this:

Open PR
CI/CD provisions a new environment
Wait... ⏳
Deploy code
Wait some more... ⏳
Finally get your preview URL

The provisioning step is the killer. Whether you're using Kubernetes namespaces, cloud functions, or edge workers, creating resources takes time.

The Solution: Pre-Configured Slots

What if we flipped the script? Instead of creating environments on-demand, we pre-configure a fixed set of deployment slots:

tokyo    🔗 https://tokyo.example.com
paris    🔗 https://paris.example.com
london   🔗 https://london.example.com
berlin   🔗 https://berlin.example.com
sydney   🔗 https://sydney.example.com
madrid   🔗 https://madrid.example.com
moscow   🔗 https://moscow.example.com
cairo    🔗 https://cairo.example.com
dubai    🔗 https://dubai.example.com
rome     🔗 https://rome.example.com

Then use a deterministic hash to map PR numbers to slots:

- uses: kriasoft/pr-codename@v1
  id: pr

- run: wrangler deploy --env ${{ steps.pr.outputs.codename }}

PR #1234 always maps to tokyo. PR #1235 always maps to paris. No provisioning, no waiting.

How It Works

The magic happens in three parts:

1. Pre-Configure Your Slots

First, set up your deployment slots. Here's a Cloudflare Workers example:

# wrangler.toml
[env.tokyo]
name = "preview-tokyo"
route = "tokyo.example.com/*"

[env.paris]
name = "preview-paris"
route = "paris.example.com/*"

[env.london]
name = "preview-london"
route = "london.example.com/*"

# ... repeat for all slots

2. Deterministic Mapping

The PR Codename Action uses a simple hash function to consistently map PR numbers to slot names:

const words = ["tokyo", "paris", "london", "berlin" /* ... */];
const index = prNumber % words.length;
return words[index];

The above is just an example, in reality it uses FNV-1a hashing algorithm.

3. Deploy to the Slot

Your GitHub Action workflow becomes dead simple:

name: Deploy PR Preview

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: kriasoft/pr-codename@v1
        id: pr

      - name: Deploy to slot
        run: |
          npm ci
          npm run build
          wrangler deploy --env ${{ steps.pr.outputs.codename }}

      - name: Comment PR
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '🚀 Preview deployed to https://${{ steps.pr.outputs.codename }}.example.com'
            })

The Benefits

This pattern isn't just a neat trick; it fundamentally changes the rhythm of your development cycle.

🚀 Zero-Wait Deploys
The biggest win. By eliminating the on-demand provisioning step, deployments start immediately. What used to be a 2-3 minute coffee break is now a 30-second task. Your developers stay in the flow, and your pipeline gets a whole lot faster.

🔗 URLs You Can Actually Share
Forget long, ugly, auto-generated URLs. With this pattern, PR #1234 always maps to https://tokyo.example.com. This URL is:

Memorable: You can actually remember it.
Shareable: Perfect for dropping in a Slack channel, a Jira ticket, or even saying out loud during a Zoom call. No more "Hey, can you find that preview link for me?"
Bookmarkable: QA testers and product managers can bookmark slots for features they're tracking.

💰 No More Cloud Bill Surprises
Dynamic environments are notorious for leaving behind orphaned resources that quietly drain your budget. With a fixed number of slots, your infrastructure costs become predictable. You know exactly what's running, and you never have to hunt down forgotten preview apps again.

🧹 Cleanup? What Cleanup?
When a PR is merged or closed, there's no complex teardown script to run. The slot simply becomes available for the next PR. You can even have a workflow that automatically deploys the main branch to the slot to keep it fresh. It's a self-cleaning system.

Real-World Considerations

How Many Slots?

We've found 10-15 slots work well for most teams. The math:

10 slots + 50 open PRs = each slot serves ~5 PRs
Only the latest deployment to each slot is accessible
Most teams only actively review a handful of PRs at once

Collision Handling

Yes, PRs can map to the same slot. PR #1 and PR #11 both map to the same environment with 10 slots. This means newer deployments overwrite older ones—so if you're reviewing PR #1 and someone pushes PR #11, your preview disappears.

In practice, this works for many teams because:

Developers typically work on recent PRs
Old PR previews naturally expire
You can always trigger a redeploy to refresh

When slots don't work well: Large teams, high PR velocity, or when multiple people need to review the same PR simultaneously.

Database & Stateful Services

The biggest challenge with any preview environment is handling databases and stateful services. With slots, you have a few options:

Shared database: Fast and cheap, but schema migrations from one PR can break others
Database per slot: Better isolation, but requires seeding data for each slot
Database branching services: Tools like Neon offer instant database branches (premium option)

For simple stateless apps, this isn't an issue. For complex apps with databases, it's the main implementation challenge.

Security Notes

Use environment-specific secrets for each slot
Consider adding basic auth to preview domains
Implement automatic cleanup for stale deployments

Beyond Basic Previews

This pattern unlocks some cool possibilities:

Persistent Test Environments: QA can bookmark specific slots for testing.

A/B Testing: Map feature flags to slots for instant switching.

Geographic Testing: Actually deploy slots to different regions.

Try It Yourself

Getting started is pretty straightforward:

Install the action:

   - uses: kriasoft/pr-codename@v1
     id: pr

Use the codename in your deploy:

   deploy --env ${{ steps.pr.outputs.codename }}

Enjoy instant PR previews 🚀

The full source is on GitHub if you want to customize the word list or hashing algorithm.

Slots vs On-Demand: Quick Comparison

Before you dive in, it's worth understanding how the pre-configured slots pattern stacks up against the traditional on-demand ephemeral environments. While this post focuses on slots, knowing the trade-offs helps you make the right choice for your team.

Factor	Pre-Configured Slots	On-Demand Ephemeral
Setup Speed	⭐⭐⭐⭐⭐ Instant (pre-warmed)	⭐⭐⭐ Takes minutes (provisioning)
Cost Predictability	⭐⭐⭐⭐⭐ Fixed monthly cost	⭐⭐ Variable usage-based
Scalability	⭐⭐ Hard limit on concurrent PRs	⭐⭐⭐⭐⭐ Scales with team size
Isolation	⭐⭐ PRs can overwrite each other	⭐⭐⭐⭐⭐ Each PR gets own environment
Production Fidelity	⭐⭐⭐ Prone to environment drift	⭐⭐⭐⭐⭐ Clean slate every time
Maintenance	⭐⭐⭐⭐ Simple for basic apps	⭐⭐ Complex (build) / ⭐⭐⭐⭐ (buy)
Developer Experience	⭐⭐ Can be confusing/frustrating	⭐⭐⭐⭐⭐ Smooth parallel workflows

Best for Slots: Small teams, simple apps, tight budgets

Best for On-Demand: Growing teams, complex apps, quality-focused

Nothing prevents you from mixing both approaches — use slots for rapid prototyping and on-demand for critical features.

Wrapping Up

Sometimes the best optimization is avoiding work altogether. By pre-configuring deployment slots and using deterministic routing, we eliminated the biggest bottleneck in our PR workflow.

Give it a shot and let me know how it works for your team. Happy deploying!

What patterns have you used for PR previews? Drop a comment below 👇 always curious to hear different approaches!

From idea to 1.1k+ lines: Building a real library with Claude Code

Konstantin Tarkus — Thu, 24 Jul 2025 21:03:14 +0000

Yesterday I went down a rabbit hole and ended up building not one, but two complete projects with Claude Code. Figured I'd share what happened and some tricks I picked up along the way.

What I Actually Built (in one day)

So I started with this annoying problem: our preview deployments have URLs like pr-1234-feature-xyz-staging.k8s.example.com. Nobody can remember these things, and sharing them in Slack is painful.

Project 1: Codenames Library
A TypeScript library that turns numbers into consistent, memorable names. PR #1234 always becomes london, PR #5678 always becomes tokyo, etc.

The scope got a bit out of hand:

Core hashing algorithm (FNV-1a) for deterministic output
77+ ESM package exports with full TypeScript definitions
12 themed word lists (cities, animals, colors, etc.) in 5 different sizes each
Comprehensive test coverage for all combinations
CLI tool with codenames and cn aliases
Zero dependencies (because I'm apparently that person)
Works everywhere: Node, Bun, Deno, browsers

Project 2: PR Codename Action
Then I thought "hey, what if this just worked automatically?" So I built a GitHub Action that comments a codename on every new PR.

Combined stats: ~100 files across both repos, published NPM package + GitHub Marketplace action

The Tricks That Actually Worked

1. CLAUDE.md is your secret weapon

Honestly, this changed everything. I wrote out exactly how I wanted the code to look upfront - TypeScript style, no comments, Bun for runtime, zero deps if possible. Claude Code just... followed it religiously across every single file. No manual cleanup needed.

# Technology Stack
- **Runtime**: Bun
- **Language**: TypeScript  
- **Build**: Zero dependencies preferred

# Coding Principles
- Write lean, clear, and efficient code
- NO COMMENTS unless explicitly requested

The consistency was wild. Every file had identical structure, naming conventions, export patterns. Like having a really obsessive junior dev who never gets tired.

2. Delegate the boring searches

Instead of grep-ing around manually, I just asked Claude Code to figure stuff out:

"Find all the files importing from cities and update them to use the new API"

It autonomously searched, analyzed, and came back with exactly what needed changing. Saved probably 2 hours of manual detective work.

3. Batch everything you can

Claude Code can run multiple commands at once. Instead of asking for git status, waiting, then asking for git diff, just ask for both. Same with file reads, tests, whatever. Much faster workflow.

4. Let it handle the repetitive nightmare stuff

I needed 60 individual TypeScript files (12 themes × 5 sizes each). My brain started melting just thinking about it. Claude Code churned them all out with perfect consistency - proper exports, types, JSDoc, the works.

5. The todo system is clutch for big tasks

✅ Core hashing algorithm
✅ Generate 60 theme files  
⏳ Build CLI interface
⏳ Write tests for everything
⏳ GitHub Action implementation

Keeps you sane when juggling multiple moving pieces.

6. Be specific about your actual use case

Don't ask for generic stuff. I said: "PR 1234 needs to always become 'london' and PR 5678 always becomes 'tokyo' - same input, same output, every time." This helped Claude Code understand I needed deterministic hashing, not random generation.

How It Actually Went Down

Morning: Started with the codenames library idea. Spent 30 minutes writing a solid CLAUDE.md file with all my requirements.

Midday: Core hashing algorithm was done in about 2 hours. Had deterministic output working perfectly - same PR number always maps to same city name.

Afternoon: This is where things got crazy. Generated all 60 theme files, built the CLI, added comprehensive tests. The repetitive stuff that would normally take days.

Evening: Realized I could make this even easier to use, so I built the GitHub Action. Simple workflow file that auto-comments codenames on new PRs.

Late evening: Documentation, final polish, published both to NPM and GitHub Marketplace.

The Weird Stuff That Surprised Me

Everything was consistent. Like, unnaturally consistent. Every single file had identical exports patterns, TypeScript types, JSDoc formatting, variable naming conventions. Zero manual cleanup needed anywhere.

Error handling just appeared. I mentioned wanting it "production-ready" and suddenly every function had proper input validation, helpful error messages, edge case handling. I didn't specify any of that stuff.

The package.json got gnarly. 77+ export paths with proper ESM mappings, TypeScript declarations, multi-runtime support (Node/Bun/Deno). Claude Code just handled all the complexity without breaking a sweat.

What I Ended Up With

Codenames Library:

Published NPM package: npm install codenames
Full TypeScript support with proper IntelliSense
Works everywhere: Node, Bun, Deno, browsers
Zero dependencies (because apparently I have trust issues)
Comprehensive test coverage

GitHub Action:

Published to GitHub Marketplace
Auto-comments codenames on new PRs
Simple one-liner setup in your workflow

Both are actually being used in production now. Our preview URLs went from pr-1234-feature-branch-k8s-staging.example.com to london.example.com. Much easier to share with the team.

The Real Takeaway

Look, Claude Code didn't just write code for me. It maintained perfect consistency across ~100 files and followed every weird convention I specified. The stuff that normally takes a week of careful, tedious work was done in a day with zero inconsistencies.

If you're doing anything complex, spend 30 minutes upfront writing a solid CLAUDE.md with your requirements and coding standards. Claude Code will follow them religiously, and you'll save hours of manual cleanup later.

Also, the Task tool is genuinely useful - it's like having a senior dev who can instantly understand your entire codebase and tell you exactly what needs changing.

Anyone else gone down similar rabbit holes with Claude Code? Would love to hear what you've built!

Try it yourself:

P.S. - Our Slack channels are now full of people saying "check out the tokyo environment" instead of trying to copy-paste insane URLs. Small wins, but they add up. 🎯

Building UsagePilot: Why I'm Creating an AI Token Metering SDK for Multi-Tenant SaaS

Konstantin Tarkus — Sat, 12 Jul 2025 16:56:12 +0000

A year ago, I was knee-deep in launching a B2B SaaS tool that leaned hard on OpenAI's APIs for smart features like automated report generation. At first, it felt like magic — our users loved the AI boost. But then the bills started rolling in. What began as a manageable $300 monthly OpenAI tab ballooned to over $3,000 in just four months as we scaled to a reasonably good number of active users.

The real kicker? I had zero visibility into who was driving those costs. Was it our enterprise clients running massive data analyses, or a handful of hobbyist users experimenting wildly? We had three fixed monthly pricing tiers, so I was basically footing the bill for the heavy hitters with revenue from the casual crowd. It hit me like a ton of bricks: if we didn't fix this, our margins would evaporate, and we'd be another AI startup burned by unchecked costs.

That frustration sparked a deep dive into the world of AI usage tracking. Turns out, I'm not alone — plenty of SaaS founders are grappling with the same "AI tax." But the tools out there? They left me wanting. That's why I rolled up my sleeves and started building UsagePilot, an open-core SDK tailored for multi-tenant SaaS apps. Let me walk you through the journey, the gaps I uncovered, and how I'm tackling them head-on.

Uncovering the Multi-Tenant Blind Spot

I spent late nights poring over docs for tools like Helicone, Langfuse, Portkey.ai, and even enterprise beasts like Datadog's LLM Observability. On paper, they sounded perfect: token counting, cost breakdowns, real-time dashboards. Helicone's proxy setup was a breeze — just swap your API endpoint, and boom, you're logging everything. Langfuse impressed with its open-source tracing for complex chains, and Portkey's gateway handled a whopping 250+ providers with slick features like caching and failover.

But here's where the cracks showed: none were truly built for multi-tenant SaaS chaos. Picture this — you've got a shared backend serving hundreds of customers (tenants) simultaneously. Each request needs pristine isolation: track tokens for Tenant A's chat completions without leaking into Tenant B's analytics. Langfuse, for all its strengths, relies on a global singleton in their SDK, forcing clunky workarounds like per-request client swaps or metadata hacks. It's workable, but messy, especially at scale where concurrency bites back.

Helicone? Their proxy treats your app as one giant entity. You can tag requests with user IDs, but true tenant dashboards or isolated quotas? Forget it—it's more bolt-on than baked-in. Portkey comes closest with virtual keys and metadata filtering, but even they stop short of seamless billing workflows or embeddable per-tenant views. And don't get me started on the big APM players like New Relic or Datadog; they're powerhouse for overall monitoring but feel like overkill for AI-specific metering, with pricing that spirals as your data grows.

The pattern was clear: these tools excel at observability for internal teams debugging their own AI experiments. But for SaaS folks like me, who need to turn AI usage into fair, revenue-aligned billing? It was like using a Swiss Army knife to carve a statue—possible, but far from ideal.

From Frustration to Foundation: Prioritizing Billing-Grade Precision

After patching together a Frankenstein setup with Langfuse and custom scripts (which broke twice during peak hours), I hit my breaking point. Why wasn't there a tool that treated billing as the North Star? Observability is great for devs, but invoicing demands unyielding accuracy — no "close enough" estimates when customer trust (and your revenue) is on the line.

That's the genesis of UsagePilot: a lightweight, runtime-agnostic SDK that puts multi-tenancy and billing-grade tracking front and center. I drew inspiration from the best bits of competitors — Helicone's easy proxy vibes, Langfuse's tracing depth, Portkey's broad provider support—while fixing their SaaS blind spots.

At its heart, UsagePilot enforces tenant context via typed dimensions, making isolation feel natural:

import { UsagePilot } from "usagepilot";
import { PostgresStorage } from "usagepilot/postgres";

type Dimensions = {
  user_id: string;
  organization_id?: string;
  feature?: "chat" | "analysis"; // For granular breakdowns
};

export const usage = new UsagePilot<Dimensions>({
  storage: new PostgresStorage({
    batchSize: 50, // Smaller batches for quicker flushes in high-traffic apps
    flushInterval: 60_000, // Every minute to keep data fresh
  }),
});

This isn't just syntax sugar—it's compile-time safety ensuring you never forget a tenant ID. Integrating with AI calls? Dead simple, wrapping your fetch to auto-capture context from headers:

import { createOpenAI } from "@ak-sdk/openai";
import { streamText } from "ai";

export const openAI = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  fetch: usage.createFetch((req) => ({
    user_id: req.headers.get("x-user-id") || "anonymous",
    organization_id: req.headers.get("x-org-id"),
    feature: req.headers.get("x-feature"),
  })),
});

const stream = await streamText({
  model: openAI("gpt-4o"),
  prompt: "Analyze this quarterly report...",
  headers: {
    "x-user-id": "u123",
    "x-org-id": "o456",
    "x-feature": "analysis",
  },
});

No manual logging hassles—just seamless interception. And for accuracy? I went pluggable all the way: model-specific tokenizers (bye-bye tiktoken mismatches for Claude or Gemini) ensure penny-perfect counts, pulling from provider APIs where possible and falling back to vetted alternatives.

Hard-Won Lessons on Scale

Building this wasn't smooth sailing. My v1 prototype tanked under simulated load—every token event triggered a DB hit, choking our Postgres instance. The fix? Intelligent batching: buffer in memory, flush on thresholds, but update in-memory quotas instantly for real-time enforcement. It slashed overhead by 85% while keeping things snappy for edge deploys on Vercel or Cloudflare.

Another eye-opener: AI costs aren't uniform. Input tokens? Predictable, your prompts set the baseline. Outputs? Wild cards, especially in streaming where verbosity varies. One user's verbose essay generator cost us $50 in a day before we added per-request caps. Then there's model evolution — same prompt on GPT-4o today might chew fewer tokens than six months ago due to optimizations. Tracking historical trends became essential, not optional.

Through it all, I leaned on real stories from other founders. One shared how unchecked AI usage tanked their runway; another how misattributed costs sparked customer churn. These anecdotes shaped UsagePilot into more than code — a toolkit for turning AI from a liability into a profit center.

Open-Core: Free Foundations, Paid Power-Ups

Sustainability mattered too. Inspired by Supabase and Grafana, I went open-core under MIT: the SDK, storage adapters, and core metering are free forever, fostering community tweaks for new providers. But for SaaS magic? Paid tiers unlock Stripe/Chargebee syncs (usage to invoices in one flow), embeddable tenant dashboards, and enterprise extras like SSO.

It's a win-win: devs prototype freely, businesses scale confidently. Free tier caps at 100k events/month with basic Postgres; Pro ($49/mo) bumps to 5M events plus billing hooks; Enterprise gets custom everything.

Peering Ahead: From Tokens to AI Economics

UsagePilot is still in early development, and I'm planning to push more updates as I get closer to v1. Next up: full Anthropic/Google support, anomaly alerts (spot that rogue user early), and quality-cost correlations (link token spend to output scores for smarter optimizations). The dream? Evolve beyond tokens to meter GPU hours, image gens, or voice processing — whatever the AI future throws at us.

But the real thrill is connecting with other SaaS makers and exchanging ideas on what optimal AI token usage tracking needs to look like. If you're wrestling AI costs in your SaaS, hit me up. Share your war stories — what's your biggest metering headache? The GitHub's open, and I'm building in public, iterating on real feedback. Let's make AI profitable, not painful.

Konstantin is a principal engineer, crafting tools like UsagePilot to tame AI chaos in SaaS. Track the project on GitHub (github.com/usagepilot), snag it via NPM (npmjs.com/package/usagepilot), or follow updates on X (@usagepilot). Got a tale of AI billing woes? DM me — I'm all ears.

React Starter Kit v3.0: A Complete Stack Overhaul

Konstantin Tarkus — Mon, 30 Jun 2025 02:11:09 +0000

After years of maintaining React Starter Kit and watching the JavaScript ecosystem evolve, I've decided to completely overhaul the project with a new tech stack that reflects where web development is heading in 2025.

This wasn't a casual weekend refactor. Every single technology choice was carefully evaluated based on real-world performance, developer experience, and long-term sustainability. Here's what changed and why.

The Old Stack vs The New

Before:

Material-UI for components
Custom routing solution
Yarn package manager
Firebase/Firestore database
Express-style backend
CSS-in-JS with Emotion

After:

ShadCN UI + Tailwind CSS v4
TanStack Router
Bun runtime and package manager
Neon PostgreSQL + Cloudflare Hyperdrive + Drizzle ORM
Hono framework with tRPC
Utility-first CSS

Why These Changes Matter

Bun: Beyond Just Speed

Everyone talks about Bun being fast, but that's only part of the story. What sold me was the unified toolchain experience. Instead of juggling npm/yarn + node + various build tools, Bun handles everything from package management to running TypeScript files directly.

The real game-changer? No more package-lock.json conflicts during team development. Bun's lockfile is actually readable, and installation is consistently fast across different machines and CI environments.

# Before: Multiple tools
npm install
node --loader tsx src/server.ts
npx tsx build.ts

# After: One tool
bun install
bun run src/server.ts
bun run build.ts

ShadCN UI: Own Your Components

Material-UI served us well, but I grew tired of fighting with component customization. Need a button that looks slightly different? Good luck overriding those nested CSS classes.

ShadCN UI flips this model. Instead of installing a massive component library, you copy the exact components you need into your codebase. Want to modify the Button component? Just edit the file. No more wrestling with theme overrides or CSS specificity wars.

The components are built on Radix UI primitives, so you still get accessibility and behavior handled correctly, but the styling is completely under your control.

TanStack Router: Type Safety Meets Simplicity

React Router has been the standard for years, but TanStack Router brings something revolutionary: complete type safety for your entire routing system.

// This is all type-safe, including params and search
export const Route = createFileRoute("/dashboard/$orgId")({
  component: Dashboard,
  loader: async ({ params }) => {
    // params.orgId is typed automatically
    return fetchOrganization(params.orgId);
  },
  validateSearch: z.object({
    tab: z.enum(["overview", "members", "settings"]).optional(),
  }),
});

File-based routing means your route structure matches your folder structure. No more maintaining separate route configurations that drift out of sync with your actual pages.

Neon + Drizzle: Edge-Native Database

Firebase was fine for prototyping, but the vendor lock-in and pricing model became problematic for serious applications. Neon gives you a real SQL database with a caching layer via Cloudflare Hyperdrive edge locations worldwide.

Drizzle ORM deserves special mention here. Unlike Prisma, which generates a massive client that can't run at the edge, Drizzle is lightweight and edge-compatible. The query syntax feels natural if you know SQL, but you get full TypeScript safety.

// Drizzle queries are just functions
const users = await db
  .select()
  .from(user)
  .where(eq(user.organizationId, orgId))
  .limit(10);

Tailwind CSS v4: Zero Runtime, Maximum Performance

I'll admit, I was skeptical of Tailwind for years. It looked like inline styles with extra steps. But after building several projects with it, the productivity gains are undeniable.

Version 4 addresses my biggest concern: runtime performance. The new CSS-in-JS engine has zero runtime overhead while still giving you dynamic styling capabilities.

/* Tailwind v4 with CSS variables */
@theme {
  --color-primary: #0f172a;
  --color-primary-foreground: #f8fafc;
}

[data-theme="dark"] {
  --color-primary: #f8fafc;
  --color-primary-foreground: #0f172a;
}

The best part? You stop context-switching between CSS files and components. The styles are co-located with the markup, making components easier to understand and maintain.

Hono + tRPC: The Perfect API Stack

Express has been around forever, but it wasn't built for modern deployment targets like Cloudflare Workers. Hono is designed from the ground up for edge runtimes while maintaining familiar patterns.

Combined with tRPC, you get end-to-end type safety without code generation. Change your API schema, and TypeScript immediately tells you everywhere in your frontend that needs updating.

// Backend
export const userRouter = router({
  me: protectedProcedure.query(async ({ ctx }) => {
    return getUserById(ctx.session.userId);
  }),
});

// Frontend - fully typed
const { data: user } = api.user.me.useQuery();
//    ^? User | undefined

Performance Improvements

The numbers speak for themselves:

Build times: 3x faster with Bun + Vite
Bundle size: 40% smaller with tree-shaking and ShadCN components
Cold start: Sub-100ms with Cloudflare Workers
Database queries: 60% faster with edge-located D1

But beyond raw performance, the developer experience improvements are where this stack really shines.

Migration Path

This is essentially a v2.0 release. If you're using the old stack, you don't need to migrate immediately. But for new projects, I'd recommend starting with this modern foundation.

The learning curve isn't steep if you're already familiar with React. Most concepts translate directly:

React components work the same way
State management with Jotai is simpler than Redux
TanStack Router feels familiar if you've used file-based routing
Tailwind classes are self-explanatory

What's Next

This refactor positions React Starter Kit for the next phase of web development. Edge computing isn't a future trend—it's happening now. Global latency matters more than ever, and users expect sub-second page loads regardless of where they're located.

The tools in this stack are all designed with edge deployment in mind. They're lightweight, fast, and compatible with modern serverless platforms.

I'm excited to see what the community builds with this foundation. The old stack served us well, but it's time to embrace the future of web development.

Try out the new React Starter Kit at github.com/kriasoft/react-starter-kit.

What do you think about these technology choices? Have you tried any of these tools in your own projects? Let me know in the comments below.

Preventing Race Conditions in Node.js with Distributed Locks

Konstantin Tarkus — Wed, 18 Jun 2025 18:20:33 +0000

Picture this: Your payment processing service is humming along perfectly until Black Friday hits. Suddenly, customers are getting charged twice for the same order. Your support tickets are exploding, and your CEO is asking uncomfortable questions.

What happened? Race conditions happened.

When multiple Node.js processes try to modify the same resource simultaneously, chaos ensues. But there's a solution: distributed locks.

What Are Race Conditions?

A race condition occurs when multiple processes access shared resources concurrently, leading to unpredictable results. In distributed Node.js applications, this commonly happens with:

Payment processing (double charges)
Job processing (duplicate work)
Database migrations (corruption)
Rate limiting (bypass protection)

The Solution: Distributed Locks

Distributed locks ensure only one process can access a critical section at a time, even across multiple servers. Think of it as a "Do Not Disturb" sign for your code.

SyncGuard: Simple Distributed Locking

Let's see how to implement distributed locks using SyncGuard, a TypeScript library that supports both Redis and Firestore backends.

Installation

npm install syncguard @google-cloud/firestore
# or for Redis
npm install syncguard ioredis

Basic Usage: Preventing Double Payments

import { createLock } from "syncguard/firestore";
import { Firestore } from "@google-cloud/firestore";

const db = new Firestore();
const lock = createLock(db);

const processPayment = async (paymentId: string) => {
  // The lock function automatically manages acquire/release
  await lock(
    async () => {
      const payment = await getPayment(paymentId);

      // Critical section - only one process can execute this
      if (payment.status === "pending") {
        await chargeCustomer(payment);
        await updatePaymentStatus(paymentId, "completed");
      }
      // If another process already processed it, we safely skip
    },
    { 
      key: `payment:${paymentId}`,
      ttlMs: 60000, // Lock expires in 60 seconds
      timeoutMs: 5000 // Wait max 5 seconds to acquire
    }
  );
};

Manual Lock Control for Complex Scenarios

Sometimes you need more control over lock lifetime:

const generateReport = async () => {
  const result = await lock.acquire({
    key: "daily-report",
    ttlMs: 300000, // 5 minutes
    timeoutMs: 10000 // Wait up to 10 seconds
  });

  if (result.success) {
    try {
      await processLargeDataset();

      // Extend lock if processing takes longer
      const extended = await lock.extend(result.lockId, 300000);
      if (!extended) {
        throw new Error("Failed to extend lock - aborting");
      }

      await generateAndSaveReport();
    } finally {
      await lock.release(result.lockId);
    }
  } else {
    console.log("Report already being generated:", result.error);
  }
};

Multiple Backend Support

SyncGuard works with different storage backends:

// Firestore (great for serverless)
import { createLock } from "syncguard/firestore";
const firestoreLock = createLock(new Firestore());

// Redis (maximum performance)
import { createLock } from "syncguard/redis";
const redisLock = createLock(redisClient);

// Custom backend
import { createLock } from "syncguard";
const customLock = createLock(myBackend);

Real-World Patterns

Job Queue Processing

const processJob = async (jobId: string) => {
  await lock(
    async () => {
      const job = await getJob(jobId);
      if (job.status === "pending") {
        await executeJob(job);
        await markJobComplete(jobId);
      }
      // Already processed? No problem - idempotent!
    },
    { key: `job:${jobId}`, ttlMs: 300000 }
  );
};

Rate Limiting

const checkRateLimit = async (userId: string) => {
  const result = await lock.acquire({
    key: `rate:${userId}`,
    ttlMs: 60000, // 1 minute window
    timeoutMs: 0, // Fail immediately
    maxRetries: 0
  });

  if (!result.success) {
    throw new Error("Rate limit exceeded");
  }

  // Don't release - let it expire for rate limiting
  return performOperation(userId);
};

Key Benefits

✅ Bulletproof concurrency - No more race conditions

✅ Automatic cleanup - Locks expire even if processes crash

✅ Multiple backends - Choose Redis for speed or Firestore for simplicity

✅ TypeScript first - Full type safety and great DX

✅ Zero dependencies for core package

Best Practices

Keep critical sections short - Don't hold locks longer than necessary
Set appropriate TTLs - Balance safety vs. availability
Handle lock failures gracefully - Always have a fallback strategy
Use descriptive lock keys - Make debugging easier
Monitor lock contention - High contention indicates bottlenecks

Conclusion

Race conditions are silent killers in distributed Node.js applications. Distributed locks provide a simple, effective solution that can save you from costly bugs and angry customers.

SyncGuard makes implementing distributed locks trivial with its clean API and multiple backend support. Whether you're processing payments, managing job queues, or coordinating microservices, distributed locks should be in your toolkit.

Ready to lock down your race conditions? Check out SyncGuard on GitHub and never worry about duplicate payments again! 🔒

Want to dive deeper? Join our Discord community for discussions and support.

DEV Community: Konstantin Tarkus

How I bundle my codebase so ChatGPT can actually understand it

The problem

The approach

How I actually use it

Example usage

Links

Closing thought

Two Timestamps, One Message: Why WebSocket Systems Need Both

The Problem

The Vulnerability

1. Bypass Rate Limits

2. Reorder Messages

3. Skew Analytics

4. Clock Drift (Non-Malicious)

The Solution: Two Timestamps

1. Producer Time (meta.timestamp)

2. Server Ingress Time (ctx.receivedAt)

When to Use Which Timestamp

Correct Implementations

Rate Limiting

Message Ordering

Latency Metrics (Defensive)

Broadcasting with Origin Tracking

Make Client Timestamp Optional

Normalize Reserved Keys

Error Handling for Suspicious Timestamps

Testing and Monitoring

Test Clock Skew in Unit Tests

Monitor Timestamp Drift

Performance: UUID v7 + Timestamp Indexing

UI Best Practices

Display "Sent At" Time

Optimistic Ordering

Common Mistakes to Avoid

1. Using client time for expirations

2. Sorting by client time in queries

3. Forgetting to validate latency calculations

4. Using client time in audit logs

5. Baking client time into IDs

Key Takeaways

Beyond WebSockets

Conclusion

References

GitHub Security Notifications for Discord

Why Security Notifications Matter

Important Security Limitations

Discord Setup

1. Create a Private Security Channel

2. Generate Webhook URL

GitHub Configuration

1. Repository Webhooks

2. Critical Security Events

3. Access Control Events

4. Security Bypass Events

Best Practices

Channel Management

Notification Hygiene

Response Workflows

Testing Your Setup

Event Priority Levels

🚨 Critical (Immediate Response Required)

⚠️ High (Response Within Hours)

ℹ️ Medium (Monitor and Review)

Advanced Configuration (Optional)

Multiple Repositories

Simple Enhancements

Troubleshooting

Security Best Practices

Webhook URL Protection

Webhook Rotation Procedure

Additional Security Measures

Browser Auto-Open: Seamless OAuth UX for CLI Tools

The Art of Opening Browsers Cross-Platform

Smart Defaults with Escape Hatches

Handling Launch Failures Gracefully

Non-Blocking for Better Performance

Testing Without Real Browsers

Security Considerations

Platform-Specific Enhancements

1. Producer Time (`meta.timestamp`)

2. Server Ingress Time (`ctx.receivedAt`)