@vellumai/credential-executor 0.11.10 → 0.11.11-staging.1

package/node_modules/@vellumai/service-contracts/package.json

@@ -26,7 +26,8 @@
     "./error": "./src/error.ts",
     "./reactions": "./src/reactions.ts",
     "./guardian-requests": "./src/guardian-requests.ts",
-    "./platform-credential": "./src/platform-credential.ts"
+    "./platform-credential": "./src/platform-credential.ts",
+    "./plan-credit": "./src/plan-credit.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/service-contracts/src/__tests__/plan-credit.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  extraCreditUsd,
+  planCreditUsedFraction,
+  usageGrantRatio,
+} from "../plan-credit.js";
+
+describe("usageGrantRatio", () => {
+  test("reads the used share and clamps to 0..1", () => {
+    expect(usageGrantRatio(20, 9.1)).toBeCloseTo(0.545);
+    expect(usageGrantRatio(20, 0)).toBe(1);
+    expect(usageGrantRatio(20, 25)).toBe(0);
+  });
+
+  test("has no reading without both figures or with nothing granted", () => {
+    expect(usageGrantRatio(null, 5)).toBeNull();
+    expect(usageGrantRatio(20, null)).toBeNull();
+    expect(usageGrantRatio(0, 0)).toBeNull();
+  });
+});
+
+describe("planCreditUsedFraction", () => {
+  test("prefers the ratio whatever the plan", () => {
+    expect(planCreditUsedFraction(20, 9.1, "base")).toBeCloseTo(0.545);
+    expect(planCreditUsedFraction(20, 9.1, null)).toBeCloseTo(0.545);
+  });
+
+  test("treats a Pro plan with nothing granted as fully spent", () => {
+    expect(planCreditUsedFraction(0, 0, "pro")).toBe(1);
+    expect(planCreditUsedFraction(0, null, "pro")).toBe(1);
+  });
+
+  test("gives a base or unknown plan with nothing granted no reading", () => {
+    expect(planCreditUsedFraction(0, 0, "base")).toBeNull();
+    expect(planCreditUsedFraction(0, 0, null)).toBeNull();
+    expect(planCreditUsedFraction(null, null, "pro")).toBeNull();
+  });
+});
+
+describe("extraCreditUsd", () => {
+  test("nets unused grant credit out of the balance to the cent", () => {
+    expect(extraCreditUsd(42.17, 9.1)).toBe(33.07);
+    expect(extraCreditUsd(34.65, 9.1)).toBe(25.55);
+  });
+
+  test("never goes below zero", () => {
+    expect(extraCreditUsd(5, 9.1)).toBe(0);
+    expect(extraCreditUsd(-2.5, 0)).toBe(0);
+  });
+});

package/node_modules/@vellumai/service-contracts/src/index.ts

@@ -28,6 +28,7 @@ export * from "./rpc.js";
 export * from "./trust-rules.js";
 export * from "./ingress.js";
 export * from "./no-response.js";
+export * from "./plan-credit.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

package/node_modules/@vellumai/service-contracts/src/plan-credit.ts

@@ -0,0 +1,66 @@
+/**
+ * Plan-credit derivations shared by the assistant runtime's `platform credits`
+ * route and the web client's usage meter, so both read the billing summary's
+ * grant figures the same way and can never quote different readings.
+ */
+
+export type BillingPlanId = "base" | "pro";
+
+function clamp01(value: number): number {
+  if (!Number.isFinite(value) || value < 0) {
+    return 0;
+  }
+  return value > 1 ? 1 : value;
+}
+
+/**
+ * How much of the usage credit an account was granted it has already used:
+ * the granted total less what is still unused, over that total. The initial
+ * $5 grant burns 0 to 100% as it is spent, and a further grant grows the total
+ * so the bar drops back. Null when nothing was ever granted, or when the
+ * platform reports neither figure, which has no honest reading rather than a
+ * full or empty bar.
+ */
+export function usageGrantRatio(
+  totalUsd: number | null,
+  availableUsd: number | null,
+): number | null {
+  if (totalUsd == null || availableUsd == null || totalUsd <= 0) {
+    return null;
+  }
+  return clamp01((totalUsd - availableUsd) / totalUsd);
+}
+
+/**
+ * The plan-credit reading with the plan's fallback applied. The grant figures
+ * count only unexpired grants, so a Pro subscription whose grants total
+ * nothing has used or expired everything it was granted (a full bar, with
+ * nothing scheduled to refill it), while a base plan in that position was
+ * never granted anything (no reading). An unknown plan gets the ratio when
+ * the figures allow one and no fallback otherwise.
+ */
+export function planCreditUsedFraction(
+  totalUsd: number | null,
+  availableUsd: number | null,
+  planId: BillingPlanId | null,
+): number | null {
+  const ratio = usageGrantRatio(totalUsd, availableUsd);
+  if (ratio != null) {
+    return ratio;
+  }
+  if (planId === "pro" && totalUsd != null && totalUsd <= 0) {
+    return 1;
+  }
+  return null;
+}
+
+/**
+ * Credit bought or earned on top of the plan-included grants: the balance less
+ * whatever is still unused on those grants, never below zero, to the cent.
+ */
+export function extraCreditUsd(
+  balanceUsd: number,
+  availableUsd: number,
+): number {
+  return Math.round(Math.max(0, balanceUsd - availableUsd) * 100) / 100;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/credential-executor",
-  "version": "0.11.10",
+  "version": "0.11.11-staging.1",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/transport.test.ts

@@ -163,6 +163,10 @@ describe("health probes", () => {
     expect(src).toMatch(/\/readyz/);
     // Health server uses Bun.serve on a dedicated port, not the socket
     expect(src).toMatch(/startHealthServer\(\s*healthPort/);
+    // Kubelet httpGet targets the pod IP, so the probe listener must not
+    // bind loopback-only. Credential routes are gated with isLoopbackAddress.
+    expect(src).not.toMatch(/hostname:\s*"127\.0\.0\.1"/);
+    expect(src).toMatch(/isLoopbackAddress\(/);
   });
 
   test("getHealthPort defaults to 8090", () => {

package/src/http/loopback-address.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  isCesHttpProbePath,
+  isLoopbackAddress,
+} from "./loopback-address.js";
+
+describe("isLoopbackAddress", () => {
+  test("accepts IPv4 loopback", () => {
+    expect(isLoopbackAddress("127.0.0.1")).toBe(true);
+    expect(isLoopbackAddress("127.0.0.2")).toBe(true);
+  });
+
+  test("accepts IPv6 loopback and IPv4-mapped loopback", () => {
+    expect(isLoopbackAddress("::1")).toBe(true);
+    expect(isLoopbackAddress("::ffff:127.0.0.1")).toBe(true);
+  });
+
+  test("rejects non-loopback addresses", () => {
+    expect(isLoopbackAddress("10.0.0.1")).toBe(false);
+    expect(isLoopbackAddress("192.168.1.10")).toBe(false);
+    expect(isLoopbackAddress("8.8.8.8")).toBe(false);
+    expect(isLoopbackAddress("::ffff:10.0.0.1")).toBe(false);
+    expect(isLoopbackAddress("2001:db8::1")).toBe(false);
+  });
+});
+
+describe("isCesHttpProbePath", () => {
+  test("matches kubelet probe paths only", () => {
+    expect(isCesHttpProbePath("/healthz")).toBe(true);
+    expect(isCesHttpProbePath("/readyz")).toBe(true);
+    expect(isCesHttpProbePath("/v1/credentials")).toBe(false);
+    expect(isCesHttpProbePath("/v1/logs/export")).toBe(false);
+  });
+});

package/src/http/loopback-address.ts

@@ -0,0 +1,25 @@
+/**
+ * Strict loopback check for CES HTTP peers: 127.0.0.0/8 and ::1.
+ * IPv4-mapped IPv6 (`::ffff:127.0.0.1`) is treated as IPv4.
+ */
+export function isLoopbackAddress(addr: string): boolean {
+  const v4Mapped = addr.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
+  const normalized = v4Mapped ? v4Mapped[1] : addr;
+
+  if (normalized.includes(".")) {
+    const parts = normalized.split(".").map(Number);
+    if (
+      parts.length !== 4 ||
+      parts.some((p) => Number.isNaN(p) || p < 0 || p > 255)
+    ) {
+      return false;
+    }
+    return parts[0] === 127;
+  }
+
+  return normalized.toLowerCase() === "::1";
+}
+
+export function isCesHttpProbePath(pathname: string): boolean {
+  return pathname === "/healthz" || pathname === "/readyz";
+}

package/src/main.ts

@@ -51,6 +51,7 @@ import {
   type CredentialRouteDeps,
 } from "./http/credential-routes.js";
 import { handleLogExportRoute } from "./http/log-export-routes.js";
+import { isLoopbackAddress } from "./http/loopback-address.js";
 import { handleMetadataRoute } from "./http/metadata-routes.js";
 import { CES_MIGRATIONS } from "./migrations/registry.js";
 import { runCesMigrations } from "./migrations/runner.js";
@@ -246,9 +247,12 @@ function startHealthServer(
   signal: AbortSignal,
   credentialDeps: CredentialRouteDeps | null,
 ): ReturnType<typeof Bun.serve> {
+  // Listen on every interface so kubelet httpGet probes can hit the pod IP.
+  // Credential CRUD, metadata, and log export stay loopback-only: assistant
+  // and gateway in this pod call http://localhost:<CES_HEALTH_PORT>.
   const server = Bun.serve({
     port,
-    async fetch(req) {
+    async fetch(req, httpServer) {
       const url = new URL(req.url);
       if (url.pathname === "/healthz") {
         return new Response(JSON.stringify({ status: "ok" }), {
@@ -256,7 +260,7 @@ function startHealthServer(
         });
       }
       if (url.pathname === "/readyz") {
-        // Always return 200 — pod readiness must not depend on whether the
+        // Always return 200: pod readiness must not depend on whether the
         // assistant has connected.  When the CES feature flag is off the
         // assistant never connects, and a 503 here would block pod
         // scheduling during dark-launch.  The sidecar can't do useful work
@@ -275,6 +279,11 @@ function startHealthServer(
         );
       }
 
+      const peer = httpServer.requestIP(req)?.address;
+      if (!peer || !isLoopbackAddress(peer)) {
+        return new Response("Not Found", { status: 404 });
+      }
+
       // Credential CRUD routes (only if service token is configured)
       if (credentialDeps) {
         const metadataResponse = await handleMetadataRoute(req);