@ganju/utils 0.0.5 → 0.0.8

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';
@@ -218,6 +223,14 @@ import {
   isCredentialNeedingReauth
 } from './oauth';
 import type { RefreshOAuthTokenInput, RefreshedOAuthToken } from './oauth';
+import {
+  isValidTimeZone,
+  readCredentialTimeZone,
+  credentialTimeZoneIsStale,
+  writeCredentialTimeZone,
+  fetchGoogleCalendarTimeZone,
+  fetchCalcomTimeZone
+} from './vendorTimeZone';
 import { PlanLimitError, isPlanLimitError } from './planLimitError';
 import type { PlanLimitDetails } from './planLimitError';
 import type { PlanLimits } from './constants';
@@ -268,6 +281,8 @@ export const utils = {
   customCodePreviewScriptName,
   customCodeUploadName,
   customCodePreviewUploadName,
+  mintContainmentToken,
+  verifyContainmentToken,
   oauthProviders,
   resolveAttachment,
   isExposedResource,
@@ -333,6 +348,12 @@ export const utils = {
   buildReauthMetadata,
   clearReauthMetadata,
   isCredentialNeedingReauth,
+  isValidTimeZone,
+  readCredentialTimeZone,
+  credentialTimeZoneIsStale,
+  writeCredentialTimeZone,
+  fetchGoogleCalendarTimeZone,
+  fetchCalcomTimeZone,
   PlanLimitError,
   isPlanLimitError
 };
@@ -403,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') {

package/src/vendorTimeZone.ts

@@ -0,0 +1,171 @@
+// The time zone the user configured with the vendor, and where we keep it.
+//
+// Every scheduling question the model answers is a time-zone question first:
+// "tomorrow at 9" is not an instant until you know whose 9 it is. We had two
+// sources for that and neither worked. `artifact_tool.config.defaultTimeZone`
+// is only written when the owner opens a dropdown and changes it, so in
+// practice it is empty. The fallbacks underneath it were `undefined` (Google
+// then uses the calendar's own zone, which only helps when the timestamp has no
+// offset) and the string 'UTC' (Cal.com, which books the attendee in UTC and
+// tells nobody).
+//
+// But the user already answered this question — in Google Calendar's settings,
+// and in their Cal.com profile. So we ask the vendor instead of asking the
+// owner again, and the answer becomes the default under any explicit choice.
+//
+// It is cached on `artifact_credential.metadata` because that is what it is a
+// property of: the connected account, not the tool row. One artifact can have
+// six calendar tools installed and they all share one connection, so the
+// connection is the only place the answer belongs exactly once.
+
+import { constants } from './constants';
+
+// Metadata keys on artifact_credential. Namespaced with a prefix that will not
+// collide with the reauth markers written by the OAuth refresh path.
+const TIME_ZONE_KEY = 'timeZone';
+const TIME_ZONE_CHECKED_AT_KEY = 'timeZoneCheckedAt';
+
+// How long a cached zone is trusted. A day, because this changes when somebody
+// moves or travels — rarely, and never urgently. The cost of being briefly
+// stale is one meeting in the old zone; the cost of a shorter TTL is a vendor
+// round trip on the path of a tool call.
+const TIME_ZONE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Is this a time zone the runtime actually knows?
+ *
+ * Everything downstream — `Intl.DateTimeFormat`, Google's `start.timeZone`,
+ * Cal.com's `attendee.timeZone` — throws or 400s on a name it cannot resolve.
+ * A vendor returning something unexpected must degrade to "we don't know"
+ * rather than poison every later call with a value that cannot be used.
+ */
+export const isValidTimeZone = (value: unknown): value is string => {
+  if (typeof value !== 'string' || !value.trim()) return false;
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: value.trim() });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** The cached zone on a credential's metadata, or null. */
+export const readCredentialTimeZone = (metadata: unknown): string | null => {
+  if (!metadata || typeof metadata !== 'object') return null;
+  const value = (metadata as Record<string, unknown>)[TIME_ZONE_KEY];
+  return isValidTimeZone(value) ? value.trim() : null;
+};
+
+/**
+ * Should we ask the vendor again?
+ *
+ * True when there is nothing cached, when the stamp is missing or unreadable,
+ * or when the TTL has passed. A cache with no stamp is treated as stale rather
+ * than as fresh-forever — the conservative direction, since the only cost is
+ * one request.
+ */
+export const credentialTimeZoneIsStale = (
+  metadata: unknown,
+  now: number = Date.now()
+): boolean => {
+  if (!readCredentialTimeZone(metadata)) return true;
+  const raw = (metadata as Record<string, unknown>)[TIME_ZONE_CHECKED_AT_KEY];
+  if (typeof raw !== 'string') return true;
+  const checkedAt = Date.parse(raw);
+  if (!Number.isFinite(checkedAt)) return true;
+  return now - checkedAt >= TIME_ZONE_TTL_MS;
+};
+
+/**
+ * Merge a freshly read zone into a credential's metadata.
+ *
+ * Merges rather than replaces, because this column also carries the reauth
+ * markers — writing a bare `{ timeZone }` here would clear `needsReauth` and
+ * silently re-enable a connection the refresh path had flagged as broken.
+ *
+ * A null zone (the vendor could not tell us) still stamps the check, so a
+ * provider that never reports one is asked once a day rather than on every
+ * single call.
+ */
+export const writeCredentialTimeZone = (
+  previous: unknown,
+  timeZone: string | null,
+  now: Date = new Date()
+): Record<string, unknown> => {
+  const base =
+    previous && typeof previous === 'object'
+      ? { ...(previous as Record<string, unknown>) }
+      : {};
+  if (isValidTimeZone(timeZone)) {
+    base[TIME_ZONE_KEY] = timeZone.trim();
+  } else {
+    delete base[TIME_ZONE_KEY];
+  }
+  base[TIME_ZONE_CHECKED_AT_KEY] = now.toISOString();
+  return base;
+};
+
+/**
+ * The zone Google Calendar is configured in, from the primary calendar.
+ *
+ * Deliberately NOT `GET /users/me/settings/timezone`, which is the more
+ * direct answer to "what did the user configure" and needs
+ * `calendar.settings.readonly` — a scope we do not request and could not add
+ * without sending every already-connected user back through consent. The
+ * primary calendar's zone is the same value in every case that matters, and
+ * `calendar.readonly` already covers it.
+ *
+ * Returns null on any failure. Not knowing the zone is a state the callers
+ * handle; a throw here would take a tool call or a chat turn with it.
+ */
+export const fetchGoogleCalendarTimeZone = async (
+  accessToken: string
+): Promise<string | null> => {
+  try {
+    const response = await fetch(
+      `${constants.GOOGLE_CALENDAR_API_BASE}/calendars/primary`,
+      {
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          Accept: 'application/json'
+        }
+      }
+    );
+    if (!response.ok) return null;
+    const payload = (await response.json()) as { timeZone?: unknown };
+    return isValidTimeZone(payload?.timeZone) ? payload.timeZone.trim() : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The zone on the connected Cal.com profile.
+ *
+ * This is the host's zone — the one their availability is written in — which
+ * is what "9am" means when the artifact owner or their bot says it. It is not
+ * the attendee's zone; see the booking handler for why we use it there anyway.
+ *
+ * Same null-on-failure contract as the Google reader above.
+ */
+export const fetchCalcomTimeZone = async (
+  apiKey: string
+): Promise<string | null> => {
+  try {
+    const response = await fetch(`${constants.CALCOM_API_BASE}/me`, {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'cal-api-version': constants.CALCOM_API_VERSION_ME,
+        Accept: 'application/json'
+      }
+    });
+    if (!response.ok) return null;
+    const payload = (await response.json()) as {
+      data?: { timeZone?: unknown };
+    };
+    const value = payload?.data?.timeZone;
+    return isValidTimeZone(value) ? value.trim() : null;
+  } catch {
+    return null;
+  }
+};