@ganju/utils 0.0.6 → 0.0.8

package/dist/sources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,MAAM;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAAC;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAAI,YAAY,MAAM,CAAC,YAAY,CAAC,KAAG,OAEb,CAAC;AAE5D,eAAO,MAAM,uBAAuB,GAClC,UAAU;IAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,KAC1D,OAEwB,CAAC;AAE5B,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAGnD,CAAC;AAEF,eAAO,MAAM,wBAAwB,GACnC,KAAK,kBAAkB,EACvB,YAAY,MAAM,EAClB,aAAa,MAAM,KAClB,MAGF,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAKD,eAAO,MAAM,sBAAsB,GACjC,SAAS,MAAM,EAAE,EACjB,KAAK,kBAAkB,EACvB,UAAU;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,KACpC,YAAY,EAwBd,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,EAAE,EACjB,KAAK,kBAAkB,KACtB,MAmBF,CAAC"}
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,MAAM;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAAC;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAC/B,YAAY,MAAM,CAAC,YAAY,CAAC,KAC/B,OAEwD,CAAC;AAE5D,eAAO,MAAM,uBAAuB,GAClC,UAAU;IAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,KAC1D,OAEwB,CAAC;AAE5B,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAGnD,CAAC;AAEF,eAAO,MAAM,wBAAwB,GACnC,KAAK,kBAAkB,EACvB,YAAY,MAAM,EAClB,aAAa,MAAM,KAClB,MAGF,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAKD,eAAO,MAAM,sBAAsB,GACjC,SAAS,MAAM,EAAE,EACjB,KAAK,kBAAkB,EACvB,UAAU;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,KACpC,YAAY,EA2Bd,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,EAAE,EACjB,KAAK,kBAAkB,KACtB,MAmBF,CAAC"}

package/dist/vendorError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vendorError.d.ts","sourceRoot":"","sources":["../src/vendorError.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,mBAAmB,GAAI,MAAM,OAAO,EAAE,UAAU,MAAM,KAAG,MASrE,CAAC"}
+{"version":3,"file":"vendorError.d.ts","sourceRoot":"","sources":["../src/vendorError.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,mBAAmB,GAC9B,MAAM,OAAO,EACb,UAAU,MAAM,KACf,MASF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganju/utils",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Shared constants, schemas and helpers for Ganju",
   "license": "Apache-2.0",
   "author": "MontoyaAndres <andresmontoyafcb@gmail.com>",

package/src/attachment.ts

@@ -28,7 +28,8 @@ export interface ResolvedAttachment {
 }
 
 export type ResolveAttachmentResult =
-  { ok: true; attachment: ResolvedAttachment } | { ok: false; error: string };
+  | { ok: true; attachment: ResolvedAttachment }
+  | { ok: false; error: string };
 
 /**
  * Resolve one resource's attachment bytes.

package/src/chunking.ts

@@ -37,7 +37,9 @@ export const splitRecursive = (
     }
     if (current) chunks.push(current);
     return chunks.flatMap(chunk =>
-      chunk.length > target ? splitRecursive(chunk, target, separators) : [chunk]
+      chunk.length > target
+        ? splitRecursive(chunk, target, separators)
+        : [chunk]
     );
   }
 
@@ -104,7 +106,9 @@ export const prepareChunks = (
   if (documents && documents.length > 0) {
     const out: PreparedChunk[] = [];
     documents.forEach((doc, docIndex) => {
-      const body = (doc.pageContent || '').replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '').trim();
+      const body = (doc.pageContent || '')
+        .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '')
+        .trim();
       if (!body) return;
       const text = docIndex === 0 && header ? `${header}\n\n${body}` : body;
       const pieces = chunkText(text, options);
@@ -122,7 +126,9 @@ export const prepareChunks = (
     return out;
   }
 
-  const body = (fallbackContent || '').replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '').trim();
+  const body = (fallbackContent || '')
+    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '')
+    .trim();
   const fullText = [header, body].filter(Boolean).join('\n\n');
   return chunkText(fullText, options).map(content => ({
     content,

package/src/coerce.ts

@@ -3,7 +3,10 @@ export const toStringArray = (input: unknown): string[] => {
     return input.map(s => String(s).trim()).filter(Boolean);
   }
   if (typeof input === 'string' && input.trim()) {
-    return input.split(',').map(s => s.trim()).filter(Boolean);
+    return input
+      .split(',')
+      .map(s => s.trim())
+      .filter(Boolean);
   }
   return [];
 };

package/src/constants.ts

@@ -1811,7 +1811,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 +1892,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 +1959,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 +2006,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 +2036,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 +2055,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 +2080,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 +2128,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-08-31';
 
 const CONSENT_SOURCE_SIGNUP = 'signup' as 'signup';
 const CONSENT_SOURCE_REACCEPT = 'reaccept' as 'reaccept';
@@ -2087,6 +2168,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 +2246,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 +2262,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 +2286,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,

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';
@@ -276,6 +281,8 @@ export const utils = {
   customCodePreviewScriptName,
   customCodeUploadName,
   customCodePreviewUploadName,
+  mintContainmentToken,
+  verifyContainmentToken,
   oauthProviders,
   resolveAttachment,
   isExposedResource,
@@ -417,6 +424,7 @@ export type {
   CustomCodeSendFile,
   CustomCodeCreateResource,
   CustomCodeTokenPayload,
+  ContainmentTokenPayload,
   OAuthProviderConfig,
   AttachmentResource,
   ResolvedAttachment,

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}`;
 

package/src/slackSend.ts

@@ -18,17 +18,17 @@ export interface SlackSendRequest {
   operation: SlackOperation;
 
   // chat.postMessage / files.completeUploadExternal share these
-  channel: string;            // channel ID (C…/G…/D…) or name (#general)
-  threadTs?: string;          // reply in-thread when set
+  channel: string; // channel ID (C…/G…/D…) or name (#general)
+  threadTs?: string; // reply in-thread when set
 
   // post-message
-  text?: string;              // required for post-message
-  mrkdwn?: boolean;           // defaults to true on Slack's side
-  blocks?: unknown[];         // optional Block Kit payload
+  text?: string; // required for post-message
+  mrkdwn?: boolean; // defaults to true on Slack's side
+  blocks?: unknown[]; // optional Block Kit payload
 
   // upload-file
-  title?: string;             // shown in the Slack file viewer
-  initialComment?: string;    // message body posted alongside the file
+  title?: string; // shown in the Slack file viewer
+  initialComment?: string; // message body posted alongside the file
 }
 
 // Wire protocol for sending a PROXIED (remote MCP) resource as a Slack file.
@@ -59,7 +59,7 @@ export interface SlackSendResponse {
   // file id. Empty string when Slack returns ok:true with no id (shouldn't
   // happen, but defensively typed).
   id: string;
-  channel?: string;           // resolved channel id
-  ts?: string;                // message timestamp (post-message only)
-  permalink?: string;         // file permalink (upload-file only)
+  channel?: string; // resolved channel id
+  ts?: string; // message timestamp (post-message only)
+  permalink?: string; // file permalink (upload-file only)
 }

package/src/sources.ts

@@ -30,7 +30,9 @@ export interface ResourceUrlContext {
  * nothing to a browser. Formatting it as a web link produced a dead button in
  * whichever channel the answer went to.
  */
-export const isDownloadableSource = (sourceType: Source['sourceType']): boolean =>
+export const isDownloadableSource = (
+  sourceType: Source['sourceType']
+): boolean =>
   sourceType === constants.RESOURCE_SOURCE_TYPE_FILE ||
   sourceType === constants.RESOURCE_SOURCE_TYPE_CUSTOM_CODE;
 
@@ -79,7 +81,10 @@ export const formatSourcesAsButtons = (
         source.pageNumber
       );
       return {
-        text: truncateLabel(`${position} ${label}${pageSuffix}`, maxLabelLength),
+        text: truncateLabel(
+          `${position} ${label}${pageSuffix}`,
+          maxLabelLength
+        ),
         url
       };
     }

package/src/vendorError.ts

@@ -7,7 +7,10 @@
 // Error message turns a perfectly diagnosable failure into "[object Object]",
 // which is what every one of these call sites did until a real Gmail rejection
 // was put through them.
-export const describeVendorError = (body: unknown, fallback: string): string => {
+export const describeVendorError = (
+  body: unknown,
+  fallback: string
+): string => {
   const error = (body as { error?: unknown } | null | undefined)?.error;
   if (typeof error === 'string' && error) return error;
   if (error && typeof error === 'object') {