@nehorai/credits 2.0.0 → 2.2.0

package/dist/auth/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/auth/api-key.ts"],"sourcesContent":["import type { ICreditsAuthProvider, CreditsUser } from \"./types.js\";\n\n/**\n * Timing-safe string comparison to prevent timing attacks\n */\nfunction timingSafeEqual(a: string, b: string): boolean {\n  if (!a || !b) {\n    return false;\n  }\n\n  // Pad strings to same length to prevent length-based timing attacks\n  const maxLength = Math.max(a.length, b.length);\n  const paddedA = a.padEnd(maxLength);\n  const paddedB = b.padEnd(maxLength);\n\n  let result = 0;\n  for (let i = 0; i < maxLength; i++) {\n    result |= paddedA.charCodeAt(i) ^ paddedB.charCodeAt(i);\n  }\n\n  // Also check that lengths were originally equal\n  return result === 0 && a.length === b.length;\n}\n\n/**\n * Verify a Bearer token from an Authorization header\n *\n * @param header - The Authorization header value (e.g., \"Bearer secret123\")\n * @param secret - The expected secret value\n * @returns True if token is valid\n */\nexport function verifyBearerToken(header: string | null, secret: string): boolean {\n  if (!header || !secret) {\n    return false;\n  }\n\n  // Extract token from \"Bearer {token}\" format\n  const token = header.replace(/^Bearer\\s+/i, \"\");\n\n  // Use timing-safe comparison\n  return timingSafeEqual(token, secret);\n}\n\n/**\n * API Key auth provider for admin routes\n *\n * Uses Bearer token authentication for external API access\n * The API key is stored in CREDITS_ADMIN_API_KEY environment variable\n */\nexport class ApiKeyCreditsProvider implements ICreditsAuthProvider {\n  private readonly apiKey: string | undefined;\n  private isValidated = false;\n\n  constructor(authHeader?: string | null, apiKey?: string) {\n    this.apiKey = apiKey ?? process.env.CREDITS_ADMIN_API_KEY;\n\n    // Validate the provided auth header using timing-safe comparison\n    if (authHeader && this.apiKey) {\n      this.isValidated = verifyBearerToken(authHeader, this.apiKey);\n    }\n  }\n\n  async getCurrentUser(): Promise<CreditsUser | null> {\n    if (!this.isValidated) {\n      return null;\n    }\n\n    // API key auth returns a special \"admin\" user\n    return {\n      id: \"api-admin\",\n      email: \"api@admin.internal\",\n      name: \"API Admin\",\n    };\n  }\n\n  async verifyAdminAccess(): Promise<boolean> {\n    return this.isValidated;\n  }\n}\n\n/**\n * Verify an API key from a request header\n * @param authHeader - Authorization header value\n * @param apiKey - Optional API key to use (defaults to CREDITS_ADMIN_API_KEY env var)\n * @returns True if API key is valid\n */\nexport function verifyAdminApiKey(authHeader: string | null, apiKey?: string): boolean {\n  if (!authHeader) {\n    return false;\n  }\n\n  const expectedKey = apiKey ?? process.env.CREDITS_ADMIN_API_KEY;\n  if (!expectedKey) {\n    console.warn(\"CREDITS_ADMIN_API_KEY not configured\");\n    return false;\n  }\n\n  // Use timing-safe comparison to prevent timing attacks\n  return verifyBearerToken(authHeader, expectedKey);\n}\n\n/**\n * Create an API key auth provider from a request\n * @param request - Request object with headers\n * @param apiKey - Optional API key to use\n * @returns API key auth provider\n */\nexport function createApiKeyProvider(request: Request, apiKey?: string): ApiKeyCreditsProvider {\n  const authHeader = request.headers.get(\"Authorization\");\n  return new ApiKeyCreditsProvider(authHeader, apiKey);\n}\n"],"mappings":";AAKA,SAAS,gBAAgB,GAAW,GAAoB;AACtD,MAAI,CAAC,KAAK,CAAC,GAAG;AACZ,WAAO;AAAA,EACT;AAGA,QAAM,YAAY,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM;AAC7C,QAAM,UAAU,EAAE,OAAO,SAAS;AAClC,QAAM,UAAU,EAAE,OAAO,SAAS;AAElC,MAAI,SAAS;AACb,WAAS,IAAI,GAAG,IAAI,WAAW,KAAK;AAClC,cAAU,QAAQ,WAAW,CAAC,IAAI,QAAQ,WAAW,CAAC;AAAA,EACxD;AAGA,SAAO,WAAW,KAAK,EAAE,WAAW,EAAE;AACxC;AASO,SAAS,kBAAkB,QAAuB,QAAyB;AAChF,MAAI,CAAC,UAAU,CAAC,QAAQ;AACtB,WAAO;AAAA,EACT;AAGA,QAAM,QAAQ,OAAO,QAAQ,eAAe,EAAE;AAG9C,SAAO,gBAAgB,OAAO,MAAM;AACtC;AAQO,IAAM,wBAAN,MAA4D;AAAA,EAChD;AAAA,EACT,cAAc;AAAA,EAEtB,YAAY,YAA4B,QAAiB;AACvD,SAAK,SAAS,UAAU,QAAQ,IAAI;AAGpC,QAAI,cAAc,KAAK,QAAQ;AAC7B,WAAK,cAAc,kBAAkB,YAAY,KAAK,MAAM;AAAA,IAC9D;AAAA,EACF;AAAA,EAEA,MAAM,iBAA8C;AAClD,QAAI,CAAC,KAAK,aAAa;AACrB,aAAO;AAAA,IACT;AAGA,WAAO;AAAA,MACL,IAAI;AAAA,MACJ,OAAO;AAAA,MACP,MAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEA,MAAM,oBAAsC;AAC1C,WAAO,KAAK;AAAA,EACd;AACF;AAQO,SAAS,kBAAkB,YAA2B,QAA0B;AACrF,MAAI,CAAC,YAAY;AACf,WAAO;AAAA,EACT;AAEA,QAAM,cAAc,UAAU,QAAQ,IAAI;AAC1C,MAAI,CAAC,aAAa;AAChB,YAAQ,KAAK,sCAAsC;AACnD,WAAO;AAAA,EACT;AAGA,SAAO,kBAAkB,YAAY,WAAW;AAClD;AAQO,SAAS,qBAAqB,SAAkB,QAAwC;AAC7F,QAAM,aAAa,QAAQ,QAAQ,IAAI,eAAe;AACtD,SAAO,IAAI,sBAAsB,YAAY,MAAM;AACrD;","names":[]}
+{"version":3,"sources":["../../src/auth/api-key.ts"],"sourcesContent":["import type { ICreditsAuthProvider, CreditsUser } from \"./types.js\";\r\n\r\n/**\r\n * Timing-safe string comparison to prevent timing attacks\r\n */\r\nfunction timingSafeEqual(a: string, b: string): boolean {\r\n  if (!a || !b) {\r\n    return false;\r\n  }\r\n\r\n  // Pad strings to same length to prevent length-based timing attacks\r\n  const maxLength = Math.max(a.length, b.length);\r\n  const paddedA = a.padEnd(maxLength);\r\n  const paddedB = b.padEnd(maxLength);\r\n\r\n  let result = 0;\r\n  for (let i = 0; i < maxLength; i++) {\r\n    result |= paddedA.charCodeAt(i) ^ paddedB.charCodeAt(i);\r\n  }\r\n\r\n  // Also check that lengths were originally equal\r\n  return result === 0 && a.length === b.length;\r\n}\r\n\r\n/**\r\n * Verify a Bearer token from an Authorization header\r\n *\r\n * @param header - The Authorization header value (e.g., \"Bearer secret123\")\r\n * @param secret - The expected secret value\r\n * @returns True if token is valid\r\n */\r\nexport function verifyBearerToken(header: string | null, secret: string): boolean {\r\n  if (!header || !secret) {\r\n    return false;\r\n  }\r\n\r\n  // Extract token from \"Bearer {token}\" format\r\n  const token = header.replace(/^Bearer\\s+/i, \"\");\r\n\r\n  // Use timing-safe comparison\r\n  return timingSafeEqual(token, secret);\r\n}\r\n\r\n/**\r\n * API Key auth provider for admin routes\r\n *\r\n * Uses Bearer token authentication for external API access\r\n * The API key is stored in CREDITS_ADMIN_API_KEY environment variable\r\n */\r\nexport class ApiKeyCreditsProvider implements ICreditsAuthProvider {\r\n  private readonly apiKey: string | undefined;\r\n  private isValidated = false;\r\n\r\n  constructor(authHeader?: string | null, apiKey?: string) {\r\n    this.apiKey = apiKey ?? process.env.CREDITS_ADMIN_API_KEY;\r\n\r\n    // Validate the provided auth header using timing-safe comparison\r\n    if (authHeader && this.apiKey) {\r\n      this.isValidated = verifyBearerToken(authHeader, this.apiKey);\r\n    }\r\n  }\r\n\r\n  async getCurrentUser(): Promise<CreditsUser | null> {\r\n    if (!this.isValidated) {\r\n      return null;\r\n    }\r\n\r\n    // API key auth returns a special \"admin\" user\r\n    return {\r\n      id: \"api-admin\",\r\n      email: \"api@admin.internal\",\r\n      name: \"API Admin\",\r\n    };\r\n  }\r\n\r\n  async verifyAdminAccess(): Promise<boolean> {\r\n    return this.isValidated;\r\n  }\r\n}\r\n\r\n/**\r\n * Verify an API key from a request header\r\n * @param authHeader - Authorization header value\r\n * @param apiKey - Optional API key to use (defaults to CREDITS_ADMIN_API_KEY env var)\r\n * @returns True if API key is valid\r\n */\r\nexport function verifyAdminApiKey(authHeader: string | null, apiKey?: string): boolean {\r\n  if (!authHeader) {\r\n    return false;\r\n  }\r\n\r\n  const expectedKey = apiKey ?? process.env.CREDITS_ADMIN_API_KEY;\r\n  if (!expectedKey) {\r\n    console.warn(\"CREDITS_ADMIN_API_KEY not configured\");\r\n    return false;\r\n  }\r\n\r\n  // Use timing-safe comparison to prevent timing attacks\r\n  return verifyBearerToken(authHeader, expectedKey);\r\n}\r\n\r\n/**\r\n * Create an API key auth provider from a request\r\n * @param request - Request object with headers\r\n * @param apiKey - Optional API key to use\r\n * @returns API key auth provider\r\n */\r\nexport function createApiKeyProvider(request: Request, apiKey?: string): ApiKeyCreditsProvider {\r\n  const authHeader = request.headers.get(\"Authorization\");\r\n  return new ApiKeyCreditsProvider(authHeader, apiKey);\r\n}\r\n"],"mappings":";AAKA,SAAS,gBAAgB,GAAW,GAAoB;AACtD,MAAI,CAAC,KAAK,CAAC,GAAG;AACZ,WAAO;AAAA,EACT;AAGA,QAAM,YAAY,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM;AAC7C,QAAM,UAAU,EAAE,OAAO,SAAS;AAClC,QAAM,UAAU,EAAE,OAAO,SAAS;AAElC,MAAI,SAAS;AACb,WAAS,IAAI,GAAG,IAAI,WAAW,KAAK;AAClC,cAAU,QAAQ,WAAW,CAAC,IAAI,QAAQ,WAAW,CAAC;AAAA,EACxD;AAGA,SAAO,WAAW,KAAK,EAAE,WAAW,EAAE;AACxC;AASO,SAAS,kBAAkB,QAAuB,QAAyB;AAChF,MAAI,CAAC,UAAU,CAAC,QAAQ;AACtB,WAAO;AAAA,EACT;AAGA,QAAM,QAAQ,OAAO,QAAQ,eAAe,EAAE;AAG9C,SAAO,gBAAgB,OAAO,MAAM;AACtC;AAQO,IAAM,wBAAN,MAA4D;AAAA,EAChD;AAAA,EACT,cAAc;AAAA,EAEtB,YAAY,YAA4B,QAAiB;AACvD,SAAK,SAAS,UAAU,QAAQ,IAAI;AAGpC,QAAI,cAAc,KAAK,QAAQ;AAC7B,WAAK,cAAc,kBAAkB,YAAY,KAAK,MAAM;AAAA,IAC9D;AAAA,EACF;AAAA,EAEA,MAAM,iBAA8C;AAClD,QAAI,CAAC,KAAK,aAAa;AACrB,aAAO;AAAA,IACT;AAGA,WAAO;AAAA,MACL,IAAI;AAAA,MACJ,OAAO;AAAA,MACP,MAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEA,MAAM,oBAAsC;AAC1C,WAAO,KAAK;AAAA,EACd;AACF;AAQO,SAAS,kBAAkB,YAA2B,QAA0B;AACrF,MAAI,CAAC,YAAY;AACf,WAAO;AAAA,EACT;AAEA,QAAM,cAAc,UAAU,QAAQ,IAAI;AAC1C,MAAI,CAAC,aAAa;AAChB,YAAQ,KAAK,sCAAsC;AACnD,WAAO;AAAA,EACT;AAGA,SAAO,kBAAkB,YAAY,WAAW;AAClD;AAQO,SAAS,qBAAqB,SAAkB,QAAwC;AAC7F,QAAM,aAAa,QAAQ,QAAQ,IAAI,eAAe;AACtD,SAAO,IAAI,sBAAsB,YAAY,MAAM;AACrD;","names":[]}

package/dist/core/index.cjs

@@ -36,12 +36,16 @@ __export(core_exports, {
   assertRepresentableTierAmount: () => assertRepresentableTierAmount,
   assertUnkeyedDirectReservation: () => assertUnkeyedDirectReservation,
   assertUnreferencedDirectTransaction: () => assertUnreferencedDirectTransaction,
+  assertValidBalanceTarget: () => assertValidBalanceTarget,
   assertValidCreditAmount: () => assertValidCreditAmount,
   assertValidIdempotencyKey: () => assertValidIdempotencyKey,
   assertValidStoredAmount: () => assertValidStoredAmount,
   assertValidStoredAmountRaw: () => assertValidStoredAmountRaw,
+  assertValidTierBalanceInput: () => assertValidTierBalanceInput,
+  attributeExpiredBacking: () => attributeExpiredBacking,
   backedBalanceFloor: () => backedBalanceFloor,
   calculateAvailableCredits: () => calculateAvailableCredits,
+  cappedBalance: () => cappedBalance,
   classifyDatabaseError: () => classifyDatabaseError,
   commitReservationWithJournal: () => commitReservationWithJournal,
   createDeferredExecutor: () => createDeferredExecutor,
@@ -57,6 +61,7 @@ __export(core_exports, {
   createUnsupportedOperationError: () => createUnsupportedOperationError,
   createUserNotFoundError: () => createUserNotFoundError,
   describePaymentMismatch: () => describePaymentMismatch,
+  expiredHoldBackingPatch: () => expiredHoldBackingPatch,
   genericDeferred: () => genericDeferred,
   getSqlState: () => getSqlState,
   hasPlacedHold: () => hasPlacedHold,
@@ -78,9 +83,14 @@ __export(core_exports, {
   noopDeferred: () => noopDeferred,
   normalizePaymentRef: () => normalizePaymentRef,
   numericToCents: () => numericToCents,
+  planBalanceCap: () => planBalanceCap,
+  planBalanceTarget: () => planBalanceTarget,
+  planHoldCommit: () => planHoldCommit,
   releaseReservationWithJournal: () => releaseReservationWithJournal,
   reserveCreditsForOperation: () => reserveCreditsForOperation,
   sameAmount: () => sameAmount,
+  settleExpiredHoldBacking: () => settleExpiredHoldBacking,
+  spendableBalance: () => spendableBalance,
   storedMonthlyLimit: () => storedMonthlyLimit,
   sumAmounts: () => sumAmounts,
   synchronousDeferred: () => synchronousDeferred,
@@ -312,6 +322,86 @@ function backedBalanceFloor(reserved, bonusCredits) {
   assertRepresentableAmount(floor, "backedBalanceFloor", { reserved, bonusCredits });
   return floor;
 }
+function cappedBalance(balance, cap, reserved, bonusCredits) {
+  return Math.min(balance, Math.max(cap, backedBalanceFloor(reserved, bonusCredits)));
+}
+function spendableBalance(balance, expiredHoldBacking = 0) {
+  return sumAmounts(balance, -Math.min(expiredHoldBacking, balance));
+}
+function planBalanceTarget(target, reserved, bonusCredits) {
+  const balance = Math.max(target, backedBalanceFloor(reserved, bonusCredits));
+  return { balance, expiredHoldBacking: sumAmounts(balance, -target) };
+}
+function planBalanceCap(balance, cap, reserved, bonusCredits, expiredHoldBacking = 0) {
+  const spendable = spendableBalance(balance, expiredHoldBacking);
+  const target = Math.min(spendable, cap);
+  const kept = Math.max(
+    sumAmounts(balance, -spendable),
+    sumAmounts(backedBalanceFloor(reserved, bonusCredits), -target)
+  );
+  const next = Math.min(balance, sumAmounts(target, kept));
+  return { balance: next, expiredHoldBacking: Math.max(0, sumAmounts(next, -target)) };
+}
+function settleExpiredHoldBacking(balance, expiredHoldBacking, holdBacking) {
+  const held = Math.min(expiredHoldBacking, balance);
+  const used = Math.min(held, holdBacking);
+  return { used, remaining: sumAmounts(held, -used) };
+}
+function planHoldCommit(balance, bonusCredits, expiredHoldBacking, holdBacking, amount) {
+  const backing = settleExpiredHoldBacking(balance, expiredHoldBacking, holdBacking);
+  const rest = sumAmounts(amount, -backing.used);
+  const fromSpendable = Math.min(spendableBalance(balance, expiredHoldBacking), rest);
+  const fromBonus = sumAmounts(rest, -fromSpendable);
+  return {
+    covered: fromBonus <= bonusCredits,
+    balance: sumAmounts(balance, -backing.used, -fromSpendable),
+    bonusCredits: sumAmounts(bonusCredits, -fromBonus),
+    expiredHoldBacking: backing.remaining
+  };
+}
+function attributeExpiredBacking(holds, total) {
+  const placed = holds.filter((hold) => hold.holdPlacedAt).sort(
+    (a, b) => a.holdPlacedAt === b.holdPlacedAt ? a.id < b.id ? -1 : 1 : a.holdPlacedAt < b.holdPlacedAt ? -1 : 1
+  );
+  const shares = /* @__PURE__ */ new Map();
+  let left = total;
+  for (const hold of placed) {
+    const kept = Math.min(hold.expiredBacking ?? 0, hold.amount, left);
+    shares.set(hold.id, kept);
+    left = sumAmounts(left, -kept);
+  }
+  for (const hold of placed) {
+    const share = shares.get(hold.id);
+    const added = Math.min(sumAmounts(hold.amount, -share), left);
+    shares.set(hold.id, sumAmounts(share, added));
+    left = sumAmounts(left, -added);
+  }
+  return shares;
+}
+function expiredHoldBackingPatch(next, stored = 0) {
+  return next > 0 || stored > 0 ? { expiredHoldBacking: next } : {};
+}
+function assertValidBalanceTarget(value, field, context) {
+  assertRepresentableAmount(value, field, context);
+  if (value < 0) {
+    throw new CreditError(
+      `${field} cannot be negative (got ${value})`,
+      CreditErrorCode.INVALID_AMOUNT,
+      { field, value, ...context }
+    );
+  }
+}
+function assertValidTierBalanceInput(input, context) {
+  if (input.balanceCap === void 0) return;
+  if (input.balance !== void 0) {
+    throw new CreditError(
+      "A tier update cannot set both balance and balanceCap",
+      CreditErrorCode.INVALID_AMOUNT,
+      { balance: input.balance, balanceCap: input.balanceCap, ...context }
+    );
+  }
+  assertValidBalanceTarget(input.balanceCap, "balanceCap", context);
+}
 function assertRepresentableTierAmount(value, field, context) {
   if (value === Number.POSITIVE_INFINITY) return;
   assertRepresentableAmount(value, field, context);
@@ -686,11 +776,13 @@ var creditSystemConfigSchema = import_zod.z.object({
   /**
    * Operation costs in credits
    * Keys are operation type names (any non-empty string)
-   * Values are positive numbers representing credit cost
+   * Values are non-negative numbers representing credit cost. 0 marks a free
+   * operation: `withCredits` runs it without touching the ledger. Amounts that
+   * move credits stay strictly positive, so `reserveCredits` refuses a 0.
    */
   operationCosts: import_zod.z.record(
     import_zod.z.string().min(1),
-    import_zod.z.number().positive()
+    import_zod.z.number().nonnegative()
   ),
   /**
    * Display labels for operation types (English canonical labels).
@@ -712,9 +804,9 @@ var creditSystemConfigSchema = import_zod.z.object({
    */
   reservationExpiryMs: import_zod.z.number().positive().default(5 * 60 * 1e3),
   /**
-   * Default credits for new users (free tier)
+   * Default credits for new users (free tier). 0 means no signup grant.
    */
-  defaultFreeCredits: import_zod.z.number().positive().default(25),
+  defaultFreeCredits: import_zod.z.number().min(0).default(25),
   /**
    * Grace period in days after subscription expires before downgrade
    */
@@ -1098,12 +1190,16 @@ async function reserveCreditsForOperation(repository, userId, amount, operationT
   assertRepresentableTierAmount,
   assertUnkeyedDirectReservation,
   assertUnreferencedDirectTransaction,
+  assertValidBalanceTarget,
   assertValidCreditAmount,
   assertValidIdempotencyKey,
   assertValidStoredAmount,
   assertValidStoredAmountRaw,
+  assertValidTierBalanceInput,
+  attributeExpiredBacking,
   backedBalanceFloor,
   calculateAvailableCredits,
+  cappedBalance,
   classifyDatabaseError,
   commitReservationWithJournal,
   createDeferredExecutor,
@@ -1119,6 +1215,7 @@ async function reserveCreditsForOperation(repository, userId, amount, operationT
   createUnsupportedOperationError,
   createUserNotFoundError,
   describePaymentMismatch,
+  expiredHoldBackingPatch,
   genericDeferred,
   getSqlState,
   hasPlacedHold,
@@ -1140,9 +1237,14 @@ async function reserveCreditsForOperation(repository, userId, amount, operationT
   noopDeferred,
   normalizePaymentRef,
   numericToCents,
+  planBalanceCap,
+  planBalanceTarget,
+  planHoldCommit,
   releaseReservationWithJournal,
   reserveCreditsForOperation,
   sameAmount,
+  settleExpiredHoldBacking,
+  spendableBalance,
   storedMonthlyLimit,
   sumAmounts,
   synchronousDeferred,