@joshski/dust 0.1.101 → 0.1.102

package/dist/env-config.d.ts

@@ -10,11 +10,13 @@
  * - DEBUG: Pattern for stdout debug logging (comma-separated wildcards)
  * - DUST_LOG_DIR: Override default log directory location
  * - DUST_LOG_FILE: Inherited log file path for child processes
+ * - DUST_LOG_FORMAT: Output format ('json' for JSON Lines, 'text' for human-readable)
  */
 export interface LoggingConfig {
     debug: string | undefined;
     logDir: string | undefined;
     logFile: string | undefined;
+    logFormat: 'json' | 'text' | undefined;
 }
 /**
  * Dustbucket connection configuration.

package/dist/filesystem-emulator.js

@@ -48,7 +48,7 @@ function createFileSystemEmulator(tree = {}, flatFiles) {
     creationTimes.set(path, nextCreationTime++);
   }
   return {
-    exists: (path) => paths.has(path),
+    exists: paths.has.bind(paths),
     isDirectory: (path) => paths.has(path) && !files.has(path),
     readFile: async (path) => {
       if (!files.has(path)) {

package/dist/logging/index.d.ts

@@ -46,8 +46,17 @@
  * No external dependencies.
  */
 import type { LoggingConfig } from '../env-config';
+import { type LogEntry } from './match';
 import { type LogSink } from './sink';
-export type LogFn = (...messages: unknown[]) => void;
+export type { LogEntry };
+/**
+ * Optional context object for structured logging.
+ * Fields are passed through to JSON output as-is.
+ */
+export interface LogContext {
+    [key: string]: unknown;
+}
+export type LogFn = (message: string, context?: LogContext) => void;
 export interface LoggerOptions {
     /**
      * Per-logger file routing override.

package/dist/logging/match.d.ts

@@ -4,6 +4,18 @@
  * Parses a DEBUG-style string (comma-separated, `*` wildcards)
  * and tests logger names against it. No side effects.
  */
+/**
+ * Structured log entry for JSON output.
+ * Required fields: ts, logger, level, msg
+ * Additional context fields are passed through as-is.
+ */
+export interface LogEntry {
+    ts: string;
+    logger: string;
+    level: 'info';
+    msg: string;
+    [key: string]: unknown;
+}
 /**
  * Parse a DEBUG expression string into an array of RegExp matchers.
  * Returns an empty array when the input is empty or undefined.
@@ -14,6 +26,14 @@ export declare function parsePatterns(debug: string | undefined): RegExp[];
  */
 export declare function matchesAny(name: string, patterns: RegExp[]): boolean;
 /**
- * Format a log line with ISO timestamp and logger name.
+ * Format a log line with ISO timestamp and logger name (text format).
  */
 export declare function formatLine(name: string, messages: unknown[]): string;
+/**
+ * Format a log entry as a JSON line (JSON Lines format).
+ */
+export declare function formatJsonLine(entry: LogEntry): string;
+/**
+ * Create a LogEntry from logger name, message, and optional context.
+ */
+export declare function createLogEntry(name: string, message: string, context?: Record<string, unknown>): LogEntry;

package/dist/logging.js

@@ -20,6 +20,19 @@ function formatLine(name, messages) {
   return `${new Date().toISOString()} [${name}] ${text}
 `;
 }
+function formatJsonLine(entry) {
+  return JSON.stringify(entry) + `
+`;
+}
+function createLogEntry(name, message, context) {
+  return {
+    ts: new Date().toISOString(),
+    logger: name,
+    level: "info",
+    msg: message,
+    ...context
+  };
+}
 
 // lib/logging/sink.ts
 import { appendFileSync, mkdirSync } from "node:fs";
@@ -101,9 +114,10 @@ function createLoggingService(options) {
       } else if (typeof loggerOptions?.file === "string") {
         perLoggerSink = getOrCreateFileSink(loggerOptions.file);
       }
-      return (...messages) => {
+      const useJsonFormat = config.logFormat === "json";
+      return (message, context) => {
         init();
-        const line = formatLine(name, messages);
+        const line = useJsonFormat ? formatJsonLine(createLogEntry(name, message, context)) : formatLine(name, [message, ...context ? [context] : []]);
         if (perLoggerSink !== undefined) {
           if (perLoggerSink !== null) {
             perLoggerSink.write(line);
@@ -126,7 +140,8 @@ var defaultService = createLoggingService({
   config: {
     debug: process.env.DEBUG,
     logDir: process.env.DUST_LOG_DIR,
-    logFile: process.env.DUST_LOG_FILE
+    logFile: process.env.DUST_LOG_FILE,
+    logFormat: process.env.DUST_LOG_FORMAT === "json" ? "json" : process.env.DUST_LOG_FORMAT === "text" ? "text" : undefined
   }
 });
 var enableFileLogs = defaultService.enableFileLogs.bind(defaultService);

package/dist/proxy/claude-api-proxy.d.ts

@@ -21,6 +21,7 @@
  *     → Returns response to container
  * ```
  */
+import { type HelperTokenState } from './helper-token';
 export interface ClaudeApiProxyDependencies {
     homedir: () => string;
     readFileSync: (path: string, encoding: 'utf-8') => string;
@@ -99,6 +100,31 @@ export interface ErrorResponse {
  * Build a 401 response for when no OAuth token is available.
  */
 export declare function buildNoTokenResponse(): ErrorResponse;
+/**
+ * Build a 401 response for when the helper token is invalid or expired.
+ */
+export declare function buildInvalidHelperTokenResponse(): ErrorResponse;
+/**
+ * Extract the helper token from incoming request headers.
+ * Checks both Authorization header (Bearer token) and x-api-key header.
+ */
+export declare function extractHelperToken(headers: Record<string, string | string[] | undefined>): string | null;
+/**
+ * Validate the incoming helper token against the issued token.
+ */
+export declare function validateHelperToken(incomingToken: string | null, state: HelperTokenState, now?: number): boolean;
+/**
+ * Get the current helper token, rotating if needed.
+ * Returns the new state and the token string.
+ */
+export declare function getOrRefreshHelperToken(state: HelperTokenState, now?: number): {
+    state: HelperTokenState;
+    token: string;
+};
+/**
+ * Build a success response containing the helper token.
+ */
+export declare function buildTokenResponse(token: string): ProxyResponse;
 /**
  * Build a 502 response for when the upstream request fails.
  */
@@ -106,11 +132,18 @@ export declare function buildUpstreamErrorResponse(error: unknown): ErrorRespons
 /**
  * Handle a proxy request and return a platform-agnostic response.
  * This is the pure core of the proxy logic, separated from HTTP plumbing.
+ *
+ * When helperTokenState is provided, incoming requests must include a valid
+ * helper token in the Authorization or x-api-key header.
  */
-export declare function handleProxyRequest(request: ProxyRequest, dependencies: ClaudeApiProxyDependencies): Promise<ProxyResponse>;
+export declare function handleProxyRequest(request: ProxyRequest, dependencies: ClaudeApiProxyDependencies, helperTokenState?: HelperTokenState, now?: number): Promise<ProxyResponse>;
 /**
  * Creates a Claude API proxy server.
  * The server accepts HTTP requests and forwards them to the Anthropic API
  * with the OAuth token injected.
+ *
+ * The server maintains helper token state and provides a `/token` endpoint
+ * that returns the current helper token. All other requests must include
+ * a valid helper token in the Authorization or x-api-key header.
  */
 export declare function createClaudeApiProxyServer(dependencies?: ClaudeApiProxyDependencies): Promise<ClaudeApiProxyServer>;

package/dist/proxy/git-credential-proxy.d.ts

@@ -20,6 +20,8 @@
 import type { spawn as nodeSpawn } from 'node:child_process';
 export interface GitCredentialProxyDependencies {
     spawn: typeof nodeSpawn;
+    /** Real user HOME directory — used when the process HOME has been overridden */
+    userHome?: string;
 }
 export interface GitCredentials {
     username: string;

package/dist/proxy/helper-token.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Helper Token Module
+ *
+ * Pure functional module for generating and validating short-TTL helper tokens.
+ * These tokens let containerized Claude Code authenticate with the host OAuth gateway.
+ *
+ * When running Claude Code in Docker containers, the real OAuth token should never
+ * enter the container environment. Instead, the container fetches a synthetic
+ * "helper token" from the host gateway. The gateway validates this helper token
+ * before injecting the real OAuth token upstream.
+ */
+/**
+ * Time-to-live for helper tokens in milliseconds.
+ * Tokens expire after this duration and must be regenerated.
+ */
+export declare const HELPER_TOKEN_TTL_MS = 60000;
+/**
+ * Represents a generated helper token with its issue time.
+ */
+export interface HelperToken {
+    token: string;
+    issuedAt: number;
+}
+/**
+ * State object tracking the current helper token.
+ */
+export interface HelperTokenState {
+    current: HelperToken | null;
+}
+/**
+ * Generate a synthetic helper token that mimics the Claude API key format.
+ * The token is cryptographically random and follows the pattern: sk-ant-api03-...
+ *
+ * @param now - Current timestamp in milliseconds (defaults to Date.now())
+ * @returns A HelperToken containing the token string and issue time
+ */
+export declare function generateHelperToken(now?: number): HelperToken;
+/**
+ * Check if a token matches the issued token and is within its TTL.
+ *
+ * @param token - The token string to validate
+ * @param issued - The HelperToken that was issued
+ * @param now - Current timestamp in milliseconds (defaults to Date.now())
+ * @param ttlMs - Time-to-live in milliseconds (defaults to HELPER_TOKEN_TTL_MS)
+ * @returns true if the token is valid, false otherwise
+ */
+export declare function isHelperTokenValid(token: string, issued: HelperToken, now?: number, ttlMs?: number): boolean;
+/**
+ * Create a new helper token state object.
+ * The state starts with no current token.
+ *
+ * @returns A new HelperTokenState with null current token
+ */
+export declare function createHelperTokenState(): HelperTokenState;
+/**
+ * Rotate the helper token state by generating a new token.
+ * Returns a new state object with the new token (immutable).
+ *
+ * @param state - The current helper token state
+ * @param now - Current timestamp in milliseconds (defaults to Date.now())
+ * @returns A new HelperTokenState with a fresh token
+ */
+export declare function rotateHelperToken(state: HelperTokenState, now?: number): HelperTokenState;
+/**
+ * Check if the current helper token in state is valid.
+ * Returns false if there is no current token.
+ *
+ * @param state - The helper token state to check
+ * @param now - Current timestamp in milliseconds (defaults to Date.now())
+ * @param ttlMs - Time-to-live in milliseconds (defaults to HELPER_TOKEN_TTL_MS)
+ * @returns true if the current token exists and is within TTL
+ */
+export declare function isCurrentTokenValid(state: HelperTokenState, now?: number, ttlMs?: number): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.101",
+  "version": "0.1.102",
   "description": "Flow state for AI coding agents",
   "type": "module",
   "bin": {