@ganju/utils 0.0.6 → 0.0.9

package/src/constants.ts

@@ -622,8 +622,8 @@ const LLM_CATALOG: ReadonlyArray<{
 }> = [
   {
     provider: LLM_PROVIDER_GOOGLE,
-    model: 'gemini-3-flash-preview',
-    label: 'Gemini 3 Flash'
+    model: 'gemini-3.8-flash',
+    label: 'Gemini 3.8 Flash'
   },
   {
     provider: LLM_PROVIDER_GOOGLE,
@@ -632,13 +632,13 @@ const LLM_CATALOG: ReadonlyArray<{
   },
   {
     provider: LLM_PROVIDER_OPENAI,
-    model: 'gpt-4o-mini',
-    label: 'GPT-4o mini'
+    model: 'gpt-5.4-mini',
+    label: 'GPT-5.4 mini'
   },
   {
     provider: LLM_PROVIDER_OPENAI,
-    model: 'gpt-4o',
-    label: 'GPT-4o'
+    model: 'gpt-5.5',
+    label: 'GPT-5.5'
   },
   {
     provider: LLM_PROVIDER_ANTHROPIC,
@@ -647,16 +647,35 @@ const LLM_CATALOG: ReadonlyArray<{
   },
   {
     provider: LLM_PROVIDER_ANTHROPIC,
-    model: 'claude-sonnet-4-6',
-    label: 'Claude Sonnet 4.6'
+    model: 'claude-sonnet-5',
+    label: 'Claude Sonnet 5'
   },
   {
     provider: LLM_PROVIDER_ANTHROPIC,
-    model: 'claude-opus-4.7',
-    label: 'Claude Sonnet 4.7'
+    model: 'claude-opus-5',
+    label: 'Claude Opus 5'
   }
 ];
 
+// The picker's escape hatch. Anything that speaks the OpenAI chat-completions
+// protocol — a gateway, an aggregator, a self-hosted server — is reachable
+// without a catalog row: the customer supplies the model id and the base URL,
+// and the request goes out through the OpenAI adapter. Not a provider value, so
+// it can never reach the database; the dashboard translates it into
+// LLM_PROVIDER_OPENAI_COMPATIBLE on submit.
+const LLM_CATALOG_CUSTOM_KEY = 'custom';
+
+// Validation messages for an organization LLM's base URL. Constants rather than
+// inline strings because localizeZodIssue keys its translations on the exact
+// English text, so the two files have to name the same value. Both also carry a
+// word matchStatus recognises ("required", "must be"): the update path re-checks
+// the merged row and throws the message as a plain Error, and anything
+// unrecognised there becomes an opaque 500 instead of a 400.
+const LLM_BASE_URL_REQUIRED_MESSAGE =
+  'A base URL is required for an OpenAI-compatible model';
+const LLM_BASE_URL_INVALID_MESSAGE =
+  'Base URL must be a public https:// address';
+
 const LLM_SYSTEM_DEFAULT = 'SYSTEM_DEFAULT';
 
 const MAX_TOOL_LOOPS = 8;
@@ -1811,7 +1830,8 @@ const PLAN_PRO = 'PRO' as 'PRO';
 const PLAN_ENTERPRISE = 'ENTERPRISE' as 'ENTERPRISE';
 const PLANS = [PLAN_FREE, PLAN_PRO, PLAN_ENTERPRISE];
 
-// Mirror Stripe's subscription statuses so the webhook can store them verbatim.
+// The provider's subscription statuses, mirrored so the webhook can store them
+// verbatim.
 const SUBSCRIPTION_STATUS_ACTIVE = 'active' as 'active';
 const SUBSCRIPTION_STATUS_TRIALING = 'trialing' as 'trialing';
 const SUBSCRIPTION_STATUS_PAST_DUE = 'past_due' as 'past_due';
@@ -1891,6 +1911,30 @@ const PRICING_SHARED_KEY_HARD_CAP = 100_000;
 // so $2 is now roughly break-even. Raising CHUNK_TARGET_CHARS would tip it
 // positive without touching this number.
 const PRICING_EMBEDDED_PER_GB_USD = 2;
+// Custom-tool invocations included per month, and the rate beyond them.
+//
+// "Tool call" here means one dispatch into a user's own script on Workers for
+// Platforms — NOT a call to a shipped integration or a proxied server. Those
+// cost us one screened fetch from a Worker we already pay for, which is why they
+// stay bundled; this one runs the customer's code on our infrastructure, and is
+// the first cost axis a user can turn against us rather than merely consume.
+//
+// Cloudflare bills the whole chain (dispatcher → user script → outbound worker)
+// as ONE request and counts CPU across all three, so a call costs ~$2.30 per
+// million at the per-script CPU ceiling. $5/M is ~2x that, and 1,000,000 is far
+// past any real month: the heaviest worked customer in the cost model makes
+// 800,000, and a single artifact pinned at its rate limit for a full month
+// manages ~2.6 million.
+const PRICING_INCLUDED_TOOL_CALLS = 1_000_000;
+const PRICING_TOOL_CALL_PER_M_USD = 5;
+// Abuse backstop on custom-tool invocations — the compute analogue of
+// PRICING_SHARED_KEY_HARD_CAP, and needed for the same reason: past a point,
+// usage stops looking like a customer and starts looking like a runaway loop or
+// a stolen credential. 20x the included allowance is ~$46 of compute against
+// ~$95 billed, and takes eight artifacts held at their rate limit for a month to
+// reach. Enterprise is null — the cost model's own enterprise example makes 20
+// million calls a month, so a fixed ceiling there would fight a real customer.
+const PRICING_TOOL_CALL_HARD_CAP = 20_000_000;
 const PRICING_CUSTOM_DOMAIN_USD = 15;
 
 interface PlanLimits {
@@ -1934,6 +1978,20 @@ interface PlanLimits {
   // keeps that from becoming an unbounded tool list on the plan that runs on our
   // model key. `null` = no limit.
   maxHttpEndpointsPerArtifact: number | null;
+  // Monthly allowance of CUSTOM-TOOL invocations — dispatches into the org's own
+  // code. A billing threshold like includedSharedMessages, not a block: past it
+  // paid plans keep running and meter at the per-million rate.
+  //
+  // Only custom code counts. A shipped integration or a proxied server costs one
+  // screened fetch, so metering those would bill a customer for something that
+  // rounds to zero and make the tool list a thing to ration.
+  includedToolCalls: number;
+  // Absolute stop on custom-tool invocations, regardless of billing. The
+  // compute-side twin of sharedKeyHardCap, and the only limit on this axis that
+  // an infinite loop inside someone's tool actually meets — the per-script CPU
+  // ceiling bounds one call, the per-artifact rate limiter bounds calls per
+  // minute, and this bounds the month. `null` = no backstop.
+  toolCallHardCap: number | null;
   // Display-only allowances included in the plan (what overage is measured
   // against). Not used for blocking.
   includedMessages: number;
@@ -1967,6 +2025,15 @@ const PLAN_LIMITS: Record<
     canUseCustomLlm: false,
     canUseCustomCode: false,
     maxHttpEndpointsPerArtifact: 3,
+    // Free can't deploy custom code, so the only way to have a running script on
+    // this plan is to have DOWNGRADED with one already published — a paid org
+    // keeps its versions and their bundles. Those tools go on serving, because
+    // killing a customer's live integrations the moment a card fails is a worse
+    // failure than serving a bounded number of calls while they fix it. This is
+    // that bound: real breathing room, ~$0.02 of compute, and no overage path
+    // off Free to turn it into a bill.
+    includedToolCalls: 0,
+    toolCallHardCap: 10_000,
     includedMessages: 100,
     includedEmbeddedBytes: 5 * MB
   },
@@ -1988,6 +2055,8 @@ const PLAN_LIMITS: Record<
     canUseCustomLlm: true,
     canUseCustomCode: true,
     maxHttpEndpointsPerArtifact: null,
+    includedToolCalls: PRICING_INCLUDED_TOOL_CALLS,
+    toolCallHardCap: PRICING_TOOL_CALL_HARD_CAP,
     includedMessages: PRICING_INCLUDED_MESSAGES,
     includedEmbeddedBytes: PRICING_INCLUDED_EMBEDDED_GB * GB
   },
@@ -2005,6 +2074,12 @@ const PLAN_LIMITS: Record<
     canUseCustomLlm: true,
     canUseCustomCode: true,
     maxHttpEndpointsPerArtifact: null,
+    includedToolCalls: PRICING_INCLUDED_TOOL_CALLS,
+    // No backstop: an Enterprise contract is negotiated against real volume, and
+    // the reference deal in the cost model runs 20 million calls a month — the
+    // exact number a Pro-shaped ceiling would refuse. Raise the ceiling by
+    // contract; don't make one plan's abuse limit another plan's product limit.
+    toolCallHardCap: null,
     includedMessages: PRICING_INCLUDED_MESSAGES,
     includedEmbeddedBytes: PRICING_INCLUDED_EMBEDDED_GB * GB
   }
@@ -2024,21 +2099,46 @@ const PLAN_FEATURE_HTTP_ENDPOINT = 'httpEndpoint' as 'httpEndpoint';
 const PLAN_FEATURE_RAW_STORAGE = 'rawStorage' as 'rawStorage';
 const PLAN_FEATURE_EMBEDDED_STORAGE = 'embeddedStorage' as 'embeddedStorage';
 const PLAN_FEATURE_MESSAGE = 'message' as 'message';
+const PLAN_FEATURE_TOOL_CALL = 'toolCall' as 'toolCall';
 
 // Stable code returned on a quota block so clients can branch on it (402).
 const PLAN_LIMIT_ERROR_CODE = 'PLAN_LIMIT_EXCEEDED';
 
-// Stripe Billing Meter event names. The metering cron reports per-period
-// OVERAGE (usage above the plan's included allowance) to these meters; the
-// meters' prices on the subscription turn that into charges. Embedded storage
-// is reported in whole MB, messages as a raw count.
+// Billing meter event names. The metering cron reports per-period OVERAGE
+// (usage above the plan's included allowance) to these meters; the meters'
+// prices on the subscribed product turn that into charges. Embedded storage is
+// reported in whole MB, messages as a raw count.
+//
+// Each name must match the filter on its meter exactly. A mismatch is not an
+// error at either end — the event is accepted, matches no meter, and the usage
+// is silently unbilled.
 //
 // Messages report to two separate meters because the two kinds of turn bill at
 // different rates — a turn on the org's own key is a platform fee, a turn on our
 // model is inference we bought. One meter can't price both.
-const STRIPE_METER_MESSAGES = 'ganju_channel_messages';
-const STRIPE_METER_SHARED_MESSAGES = 'ganju_shared_messages';
-const STRIPE_METER_EMBEDDED = 'ganju_embedded_storage';
+const BILLING_METER_MESSAGES = 'ganju_channel_messages';
+const BILLING_METER_SHARED_MESSAGES = 'ganju_shared_messages';
+const BILLING_METER_EMBEDDED = 'ganju_embedded_storage';
+// Custom-tool invocations, reported as a raw count of the calls above the
+// included allowance and priced per call at $5/1,000,000. Metered prices are
+// per single unit, so a partial block is billed as the fraction it is — a
+// customer 2.5 million past the allowance owes $12.50, which is what every page
+// of ours quotes.
+const BILLING_METER_TOOL_CALLS = 'ganju_custom_tool_calls';
+
+// The metadata property every meter aggregates (`sum` over it). Ingested events
+// carry the increment under this key, so it has to agree with the aggregation
+// configured on all four meters — which is why it lives beside their names
+// rather than at the call site.
+const BILLING_METER_UNITS_KEY = 'units';
+
+// Polar API hosts. Sandbox is a separate host rather than a mode flag, so the
+// account, products, meters and webhook secret there are all distinct from
+// production's — which is what `POLAR_SERVER` selects between.
+const POLAR_API_BASE = 'https://api.polar.sh';
+const POLAR_SANDBOX_API_BASE = 'https://sandbox-api.polar.sh';
+const POLAR_SERVER_SANDBOX = 'sandbox' as 'sandbox';
+const POLAR_SERVER_PRODUCTION = 'production' as 'production';
 
 // Legal documents a user accepts, and the version they're on. Bump the version
 // when the document changes materially — existing users are then re-prompted,
@@ -2047,7 +2147,7 @@ const STRIPE_METER_EMBEDDED = 'ganju_embedded_storage';
 const CONSENT_DOCUMENT_TERMS = 'terms' as 'terms';
 const CONSENT_DOCUMENT_PRIVACY = 'privacy' as 'privacy';
 const CONSENT_DOCUMENTS = [CONSENT_DOCUMENT_TERMS, CONSENT_DOCUMENT_PRIVACY];
-const CONSENT_CURRENT_VERSION = '2026-08-01';
+const CONSENT_CURRENT_VERSION = '2026-09-10';
 
 const CONSENT_SOURCE_SIGNUP = 'signup' as 'signup';
 const CONSENT_SOURCE_REACCEPT = 'reaccept' as 'reaccept';
@@ -2087,6 +2187,40 @@ const CRON_HOURLY = '0 * * * *';
 const CRON_ERROR_ALERTS = '*/15 * * * *';
 
 const ALERT_STATE_KEY_ERROR_LOG = 'error_log';
+// Custom-tool usage alerting, keyed per organization as `tool_calls:<id>`. The
+// monthly hard cap bounds what abuse can spend; these thresholds are what say
+// something is happening NOW, while there is still a month left to spend.
+const ALERT_STATE_KEY_TOOL_CALLS = 'tool_calls';
+// Calls in a single hour. The per-tool rate limit allows 3,600/hour, and a month
+// of the included million sustained is ~1,370/hour — so five figures in one hour
+// is either many artifacts at full tilt or something that should be looked at.
+const ALERT_TOOL_CALL_SURGE = 10_000;
+// The share of the abuse backstop at which the wall is close enough to warn
+// about. Half a month's ceiling reached is worth an email even if the rate is
+// unremarkable, because the alternative is a customer meeting it silently.
+const ALERT_TOOL_CALL_CAP_FRACTION = 0.5;
+// How long to stay quiet about one organization after alerting on it. Without
+// this a busy month is an hourly email, and an hourly email is a muted one.
+const ALERT_TOOL_CALL_COOLDOWN_HOURS = 6;
+// Organizations itemised in one digest.
+const ALERT_TOOL_CALL_MAX_ROWS = 25;
+
+// The "stop these tools" link the usage digest carries.
+//
+// It exists because the alert travels and the response did not: every other
+// containment step needs a shell holding the production database URL, so an
+// abuse notice arriving away from a desk was one nobody could act on for hours.
+//
+// Narrow on purpose. It disables the organization's custom-code installs — the
+// tools stop registering at boot, the code, versions and settings all survive,
+// and any owner can switch them back on. It cannot delete a script, touch a
+// credential, or reach anything else.
+const CONTAINMENT_TOKEN_VERSION = '1';
+const CONTAINMENT_PURPOSE_DISABLE_CUSTOM_CODE = 'disable-custom-code';
+// Long enough to still work when the mail is read a few hours late, short enough
+// that a forwarded thread or an archived inbox is not a way in.
+const CONTAINMENT_TOKEN_TTL_MS = 12 * 60 * 60 * 1000;
+const CONTAINMENT_PATH = '/containment';
 // Only alert on genuine server failures. 4xx rows are expected client errors
 // (validation, not-found, quota) and would drown the signal.
 const ALERT_MIN_STATUS = 500;
@@ -2131,6 +2265,9 @@ export const constants = {
   PRICING_INCLUDED_EMBEDDED_GB,
   PRICING_MESSAGE_PER_1K_USD,
   PRICING_EMBEDDED_PER_GB_USD,
+  PRICING_INCLUDED_TOOL_CALLS,
+  PRICING_TOOL_CALL_PER_M_USD,
+  PRICING_TOOL_CALL_HARD_CAP,
   PRICING_CUSTOM_DOMAIN_USD,
   PLAN_FEATURE_ORGANIZATION,
   PLAN_FEATURE_PROJECT,
@@ -2144,10 +2281,17 @@ export const constants = {
   PLAN_FEATURE_RAW_STORAGE,
   PLAN_FEATURE_EMBEDDED_STORAGE,
   PLAN_FEATURE_MESSAGE,
+  PLAN_FEATURE_TOOL_CALL,
   PLAN_LIMIT_ERROR_CODE,
-  STRIPE_METER_MESSAGES,
-  STRIPE_METER_SHARED_MESSAGES,
-  STRIPE_METER_EMBEDDED,
+  BILLING_METER_MESSAGES,
+  BILLING_METER_SHARED_MESSAGES,
+  BILLING_METER_EMBEDDED,
+  BILLING_METER_TOOL_CALLS,
+  BILLING_METER_UNITS_KEY,
+  POLAR_API_BASE,
+  POLAR_SANDBOX_API_BASE,
+  POLAR_SERVER_SANDBOX,
+  POLAR_SERVER_PRODUCTION,
   CONSENT_DOCUMENT_TERMS,
   CONSENT_DOCUMENT_PRIVACY,
   CONSENT_DOCUMENTS,
@@ -2161,6 +2305,15 @@ export const constants = {
   CRON_HOURLY,
   CRON_ERROR_ALERTS,
   ALERT_STATE_KEY_ERROR_LOG,
+  ALERT_STATE_KEY_TOOL_CALLS,
+  ALERT_TOOL_CALL_SURGE,
+  ALERT_TOOL_CALL_CAP_FRACTION,
+  ALERT_TOOL_CALL_COOLDOWN_HOURS,
+  ALERT_TOOL_CALL_MAX_ROWS,
+  CONTAINMENT_TOKEN_VERSION,
+  CONTAINMENT_PURPOSE_DISABLE_CUSTOM_CODE,
+  CONTAINMENT_TOKEN_TTL_MS,
+  CONTAINMENT_PATH,
   ALERT_MIN_STATUS,
   ALERT_MAX_ROWS,
   ALERT_MAX_GROUPS,
@@ -2372,6 +2525,9 @@ export const constants = {
   DEFAULT_LLM_MODEL,
   DEFAULT_LLM_SYSTEM_PROMPT,
   LLM_CATALOG,
+  LLM_CATALOG_CUSTOM_KEY,
+  LLM_BASE_URL_REQUIRED_MESSAGE,
+  LLM_BASE_URL_INVALID_MESSAGE,
   LLM_SYSTEM_DEFAULT,
   MAX_TOOL_LOOPS,
   CHANNEL_HISTORY_LIMIT,

package/src/containmentToken.ts

@@ -0,0 +1,146 @@
+import {
+  bytesToBase64,
+  toBase64Url,
+  fromBase64Url,
+  base64ToBytes
+} from './base64';
+import { constants } from './constants';
+
+// The capability carried by the "stop these tools" link in a usage alert.
+//
+// The alert reaches whoever is on call wherever they are; until this existed the
+// response did not — every containment step needed a shell holding the
+// production database URL, so an abuse notice arriving away from a desk was an
+// abuse notice nobody could act on for hours.
+//
+// A signed value rather than a row, for the same reason the tool token is one:
+// there is nothing to revoke. The link lives minutes, does one narrow and fully
+// reversible thing, and names in its own payload the only organization it can do
+// it to.
+//
+// Two properties this must have, and both are about it travelling through email:
+//
+// - **Purpose-bound.** The payload carries `p`, checked on verify, so a token
+//   signed with this deployment's secret for one job can never be replayed as
+//   another. Domain separation is what makes sharing one secret safe.
+// - **Not a GET.** Mail clients, link scanners and chat previews fetch URLs
+//   without being asked. The link opens a page; a form POST on that page is what
+//   acts. A capability that fires on preview is a capability someone else holds.
+export interface ContainmentTokenPayload {
+  // Token format version, so a future change to the payload is rejected rather
+  // than misread.
+  v: string;
+  // Purpose. One value today; present so there can be a second.
+  p: string;
+  organizationId: string;
+  iat: number;
+  exp: number;
+}
+
+const encoder = new TextEncoder();
+
+const importKey = (secret: string): Promise<CryptoKey> =>
+  crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign', 'verify']
+  );
+
+/**
+ * Mint a containment link token for one organization.
+ *
+ * The lifetime is deliberately short. This is not a login: it is a thing you act
+ * on while reading the mail that carried it, and an expiry measured in hours
+ * means a forwarded thread or an archived inbox stops being a way in.
+ */
+export const mintContainmentToken = async (
+  organizationId: string,
+  secret: string,
+  issuedAt: number = Date.now(),
+  ttlMs: number = constants.CONTAINMENT_TOKEN_TTL_MS
+): Promise<string> => {
+  const body: ContainmentTokenPayload = {
+    v: constants.CONTAINMENT_TOKEN_VERSION,
+    p: constants.CONTAINMENT_PURPOSE_DISABLE_CUSTOM_CODE,
+    organizationId,
+    iat: Math.floor(issuedAt / 1000),
+    // Rounded up so a stated lifetime is a floor rather than up to a second
+    // short of one.
+    exp: Math.ceil((issuedAt + ttlMs) / 1000)
+  };
+  const encodedPayload = toBase64Url(
+    bytesToBase64(encoder.encode(JSON.stringify(body)))
+  );
+  const key = await importKey(secret);
+  const signature = await crypto.subtle.sign(
+    'HMAC',
+    key,
+    encoder.encode(encodedPayload)
+  );
+  return `${encodedPayload}.${toBase64Url(bytesToBase64(new Uint8Array(signature)))}`;
+};
+
+/**
+ * Verify a containment token and return its payload, or null when it is
+ * malformed, expired, of an unknown format version, minted for another purpose,
+ * or not signed by this deployment's secret.
+ *
+ * Null rather than a reason, so the page can answer every rejection identically:
+ * a link that says *why* it failed tells whoever found it what to change.
+ */
+export const verifyContainmentToken = async (
+  token: string,
+  secret: string,
+  now: number = Date.now()
+): Promise<ContainmentTokenPayload | null> => {
+  const separator = token.lastIndexOf('.');
+  if (separator <= 0) return null;
+
+  const encodedPayload = token.slice(0, separator);
+  const signature = token.slice(separator + 1);
+
+  const key = await importKey(secret);
+  let valid: boolean;
+  try {
+    const signatureBytes = new Uint8Array(
+      base64ToBytes(fromBase64Url(signature))
+    );
+    valid = await crypto.subtle.verify(
+      'HMAC',
+      key,
+      signatureBytes,
+      encoder.encode(encodedPayload)
+    );
+  } catch {
+    return null;
+  }
+  if (!valid) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(
+      new TextDecoder().decode(base64ToBytes(fromBase64Url(encodedPayload)))
+    );
+  } catch {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== 'object') return null;
+  const candidate = parsed as Partial<ContainmentTokenPayload>;
+  if (candidate.v !== constants.CONTAINMENT_TOKEN_VERSION) return null;
+  if (candidate.p !== constants.CONTAINMENT_PURPOSE_DISABLE_CUSTOM_CODE) {
+    return null;
+  }
+  if (
+    typeof candidate.organizationId !== 'string' ||
+    !candidate.organizationId
+  ) {
+    return null;
+  }
+  if (typeof candidate.exp !== 'number') return null;
+  if (candidate.exp * 1000 <= now) return null;
+
+  return candidate as ContainmentTokenPayload;
+};

package/src/crypto.ts

@@ -73,8 +73,12 @@ export const sha256Base64Url = async (input: string) => {
   );
   const bytes = new Uint8Array(digest);
   let binary = '';
-  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
-  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+  for (let i = 0; i < bytes.length; i++)
+    binary += String.fromCharCode(bytes[i]);
+  return btoa(binary)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
 };
 
 export const hmacSha256Hex = async (key: string, message: string) => {

package/src/getEnv.ts

@@ -2,10 +2,7 @@ export interface EnvSource {
   env?: Record<string, unknown> | unknown;
 }
 
-export const getEnv = (
-  source: EnvSource,
-  key: string
-): string | undefined => {
+export const getEnv = (source: EnvSource, key: string): string | undefined => {
   const env = (source.env as Record<string, unknown> | undefined) || undefined;
   const value = env?.[key];
   if (typeof value === 'string') return value;

package/src/index.ts

@@ -107,6 +107,11 @@ import {
   customCodePreviewUploadName
 } from './customCodeToken';
 import type { CustomCodeTokenPayload } from './customCodeToken';
+import {
+  mintContainmentToken,
+  verifyContainmentToken
+} from './containmentToken';
+import type { ContainmentTokenPayload } from './containmentToken';
 import { oauthProviders } from './oauthProviders';
 import type { OAuthProviderConfig } from './oauthProviders';
 import { resolveAttachment } from './attachment';
@@ -129,6 +134,11 @@ import type {
   ResolveAttachmentResult
 } from './attachment';
 import { ipv4InPrivateRange, isBlockedHost } from './ssrf';
+import {
+  requiresLlmBaseUrl,
+  isAllowedLlmBaseUrl,
+  llmBaseUrlIssue
+} from './llmBaseUrl';
 import { formatRelative } from './formatRelative';
 import { formatRelativeTime } from './formatRelativeTime';
 import { languageCookieDomain } from './languageCookieDomain';
@@ -276,6 +286,8 @@ export const utils = {
   customCodePreviewScriptName,
   customCodeUploadName,
   customCodePreviewUploadName,
+  mintContainmentToken,
+  verifyContainmentToken,
   oauthProviders,
   resolveAttachment,
   isExposedResource,
@@ -290,6 +302,9 @@ export const utils = {
   projectPathIssue,
   ipv4InPrivateRange,
   isBlockedHost,
+  requiresLlmBaseUrl,
+  isAllowedLlmBaseUrl,
+  llmBaseUrlIssue,
   validateMessageVariables,
   formatRelative,
   formatRelativeTime,
@@ -417,6 +432,7 @@ export type {
   CustomCodeSendFile,
   CustomCodeCreateResource,
   CustomCodeTokenPayload,
+  ContainmentTokenPayload,
   OAuthProviderConfig,
   AttachmentResource,
   ResolvedAttachment,

package/src/llmBaseUrl.ts

@@ -0,0 +1,65 @@
+import { constants } from './constants';
+import { isBlockedHost } from './ssrf';
+
+/**
+ * The rules an `organization_llm.base_url` has to satisfy, in one place.
+ *
+ * Two write paths need them and neither can see the whole picture alone: the
+ * create schema validates a complete payload, while an update is a partial, so
+ * the provider may arrive in the request and the base URL may only exist on the
+ * stored row. Keeping the rules here means the two can't drift into disagreeing
+ * about what a valid row is — the same reason every other write in this package
+ * goes through a shared validator rather than an inline check.
+ */
+
+/**
+ * Which providers need a base URL of their own.
+ *
+ * Every other provider has an endpoint baked into its SDK. `openai-compatible`
+ * has none: it is the escape hatch for services that merely speak the OpenAI
+ * protocol, so without a base URL the adapter would send the customer's key to
+ * `api.openai.com` and fail somewhere far from the form they typed it into.
+ */
+export const requiresLlmBaseUrl = (provider?: string | null): boolean =>
+  provider === constants.LLM_PROVIDER_OPENAI_COMPATIBLE;
+
+/**
+ * Whether a base URL is safe to send a request to.
+ *
+ * This is an outbound fetch target chosen by a customer, on a worker holding
+ * their decrypted API key, so it gets the same screening as every other
+ * caller-supplied URL: `https` only, because the key travels in a header, and
+ * no loopback, private or link-local host. The Workers runtime can't resolve
+ * DNS, so — as everywhere else `isBlockedHost` is used — this screens literal
+ * hosts and IPs and is not a defense against DNS rebinding.
+ */
+export const isAllowedLlmBaseUrl = (value: string): boolean => {
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== 'https:') return false;
+  return !isBlockedHost(parsed.hostname);
+};
+
+/**
+ * Both rules against one provider/base-URL pair: the message to reject with, or
+ * `null` when the pair is acceptable. The messages are constants so
+ * `localizeZodIssue` can translate them, and both carry a word `matchStatus`
+ * recognises — the update path throws this as a plain Error rather than a
+ * ZodError, and an unrecognised message there answers 500 where it means 400.
+ */
+export const llmBaseUrlIssue = (
+  provider?: string | null,
+  baseUrl?: string | null
+): string | null => {
+  if (requiresLlmBaseUrl(provider) && !baseUrl) {
+    return constants.LLM_BASE_URL_REQUIRED_MESSAGE;
+  }
+  if (baseUrl && !isAllowedLlmBaseUrl(baseUrl)) {
+    return constants.LLM_BASE_URL_INVALID_MESSAGE;
+  }
+  return null;
+};

package/src/localizeZodIssue.ts

@@ -74,6 +74,12 @@ const CUSTOM_MESSAGES: Record<string, Record<string, string>> = {
   },
   [constants.CUSTOM_CODE_RESOURCE_FILE_TOO_LARGE_MESSAGE]: {
     es: `Los bytes del archivo superan el límite de ${constants.CUSTOM_CODE_MAX_RESOURCE_FILE_BYTES / (1024 * 1024)}MB`
+  },
+  [constants.LLM_BASE_URL_REQUIRED_MESSAGE]: {
+    es: 'Se requiere una URL base para un modelo compatible con OpenAI'
+  },
+  [constants.LLM_BASE_URL_INVALID_MESSAGE]: {
+    es: 'La URL base debe ser una dirección https:// pública'
   }
 };
 

package/src/oauth.ts

@@ -95,9 +95,7 @@ export const clearReauthMetadata = (
   return Object.keys(next).length > 0 ? next : null;
 };
 
-export const isCredentialNeedingReauth = (
-  metadata: unknown
-): boolean => {
+export const isCredentialNeedingReauth = (metadata: unknown): boolean => {
   if (!metadata || typeof metadata !== 'object') return false;
   return (metadata as Record<string, unknown>).needsReauth === true;
 };

package/src/parseHttpError.ts

@@ -1,4 +1,6 @@
-export const parseHttpErrorMessage = async (response: Response): Promise<string> => {
+export const parseHttpErrorMessage = async (
+  response: Response
+): Promise<string> => {
   const raw = await response.text();
   if (!raw) return `${response.status} ${response.statusText}`;