@graygate/bot-sdk 0.1.0

package/src/state.ts

@@ -0,0 +1,104 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * The bot runtime's state directory.
+ *
+ * It holds **the private key PEM and the room keys, in the clear**. Neither the server nor the
+ * phone of the person who created the bot has a copy, so this directory is the only one: lose it
+ * and the past messages of those rooms never open again (there is no room-key backup, by design),
+ * and new messages stay closed until the next rotation. **Guarding and backing it up is the
+ * operator's job.**
+ *
+ * The bot token is not written here. It arrives through the environment and stays in memory.
+ */
+
+interface StateShape {
+  /** room id → key version → room key */
+  roomKeys: Record<string, Record<string, string>>;
+  /** Ids already handled. Delivery is at-least-once, so the same item can arrive twice. */
+  seen: string[];
+}
+
+const SEEN_MAX = 5000;
+
+export class BotState {
+  private readonly keyPath: string;
+  private readonly statePath: string;
+  private state: StateShape = { roomKeys: {}, seen: [] };
+  private seenSet = new Set<string>();
+
+  constructor(private readonly dir: string) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    this.keyPath = join(dir, 'private-key.pem');
+    this.statePath = join(dir, 'state.json');
+    try {
+      this.state = JSON.parse(readFileSync(this.statePath, 'utf8')) as StateShape;
+      this.state.roomKeys ??= {};
+      this.state.seen ??= [];
+      this.seenSet = new Set(this.state.seen);
+    } catch {
+      // First run — start empty.
+    }
+  }
+
+  readPrivateKey(): string | null {
+    try {
+      return readFileSync(this.keyPath, 'utf8');
+    } catch {
+      return null;
+    }
+  }
+
+  writePrivateKey(pem: string): void {
+    writeAtomic(this.keyPath, pem);
+  }
+
+  roomKey(roomId: string, keyVersion: number): string | null {
+    return this.state.roomKeys[roomId]?.[String(keyVersion)] ?? null;
+  }
+
+  /** The newest key version and its key — what sending uses. */
+  latestRoomKey(roomId: string): { keyVersion: number; roomKey: string } | null {
+    const versions = this.state.roomKeys[roomId];
+    if (!versions) return null;
+    let best = 0;
+    for (const v of Object.keys(versions)) best = Math.max(best, Number(v));
+    const roomKey = versions[String(best)];
+    return best > 0 && roomKey ? { keyVersion: best, roomKey } : null;
+  }
+
+  putRoomKey(roomId: string, keyVersion: number, roomKey: string): void {
+    (this.state.roomKeys[roomId] ??= {})[String(keyVersion)] = roomKey;
+    this.persist();
+  }
+
+  forgetRoom(roomId: string): void {
+    delete this.state.roomKeys[roomId];
+    this.persist();
+  }
+
+  /** Whether this item was already handled; a first sighting is recorded and returns false. */
+  markSeen(id: string): boolean {
+    if (this.seenSet.has(id)) return true;
+    this.seenSet.add(id);
+    this.state.seen.push(id);
+    if (this.state.seen.length > SEEN_MAX) {
+      const dropped = this.state.seen.splice(0, this.state.seen.length - SEEN_MAX);
+      for (const old of dropped) this.seenSet.delete(old);
+    }
+    this.persist();
+    return false;
+  }
+
+  private persist(): void {
+    writeAtomic(this.statePath, JSON.stringify(this.state));
+  }
+}
+
+/** Write to a temporary file, then rename — dying mid-write cannot leave half a state file. */
+function writeAtomic(path: string, contents: string): void {
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, contents, { mode: 0o600 });
+  renameSync(tmp, path);
+}

package/src/wire/body.ts

@@ -0,0 +1,140 @@
+/**
+ * Generated from protocol/src/body.ts in the graygate monorepo — do not edit by hand.
+ * Only the declarations the bot SDK needs are here; the rest of that module stays private.
+ */
+
+import { MEDIA_MAX_BYTES, TEXT_CIPHERTEXT_MAX } from './constants';
+import { z } from 'zod';
+
+/**
+ * Channel post or comment — **no `parentId` means a post, a `parentId` means a first-level comment
+ * on that post.**
+ *
+ * The parent reference sits inside the ciphertext so the server never learns the shape of a
+ * conversation. The price is that the server cannot enforce who may post; that is enforced twice on
+ * the client instead, once by hiding the composer and once by checking on receipt.
+ *
+ * Outside a channel the field is ignored — out of spec, absorbed harmlessly. Replies to replies do
+ * not exist: if the parent is already a comment, the receiving client refuses it.
+ */
+const parentId = z.string().uuid().optional();
+
+/**
+ * The message being replied to — **the id alone, never a copy of what it said.**
+ *
+ * Leaving out the quoted snapshot is the whole design of the feature:
+ *
+ * 1. A device without the original **has no business learning it.** Someone who joined late, whose
+ *    copy expired under auto-delete, or who deleted it locally only needs to know "this is a
+ *    reply". They had no path to the original in the first place.
+ * 2. A snapshot would be **a copy that outlives both auto-delete and local deletion**: a sentence
+ *    that should have expired lives on inside somebody else's reply, out of reach of the deletion
+ *    that was supposed to remove it.
+ *
+ * So the quote card is drawn **only when the receiving device finds the original in its own
+ * storage.** Otherwise the message just shows as a reply. It is a separate field from `parentId`
+ * because it means something else: `parentId` is the post/comment hierarchy of a channel, this is a
+ * reference between messages at the same level.
+ *
+ * A client too old to know this field has it stripped by the schema and renders the text alone.
+ */
+const replyTo = z.string().uuid().optional();
+
+export const messageBodySchema = z.discriminatedUnion('t', [
+  z.object({
+    t: z.literal('text'),
+    text: z.string().min(1).max(8000),
+    parentId,
+    replyTo,
+  }),
+  z.object({
+    t: z.literal('media'),
+    fileName: z.string().min(1).max(255),
+    mime: z.string().min(1).max(100),
+    size: z.number().int().positive().max(MEDIA_MAX_BYTES),
+    /**
+     * Text sent along with the attachment, up to the same 8,000 characters as a text message.
+     *
+     * It rides in the same message rather than a second one because in a channel one message is one
+     * post: split them and a picture and its caption become **two separate posts** (and the caption
+     * cannot be a comment either — the parent id only exists once the first one is stored).
+     *
+     * Nothing changes for the server; this is inside the ciphertext. A client too old to know the
+     * field has it stripped by the schema and renders the attachment alone.
+     */
+    caption: z.string().min(1).max(8000).optional(),
+    /**
+     * Ties together several pictures chosen at once. Messages sharing a `groupId` are drawn as one
+     * bubble, and tapping opens them in a swipeable viewer — but each picture is still **its own
+     * message**, with its own key, upload and acknowledgement. The server sees none of this. A
+     * client too old to know the field has it stripped and draws the pictures one by one, which
+     * loses the grouping and nothing else. `groupCount` is how many the sender sent, so the
+     * receiver can tell that some have not arrived yet.
+     */
+    groupId: z.string().uuid().optional(),
+    groupCount: z.number().int().min(2).max(50).optional(),
+    parentId,
+    replyTo,
+  }),
+  /**
+   * A shared location: **two numbers and nothing else.** No map image, no street address, no place
+   * name — a map tile is an outbound request, and an address or place name means handing the
+   * coordinates to a geocoding service first.
+   *
+   * The receiver draws a card from these numbers and only opens the system map app after the person
+   * confirms, building the URL itself from the validated numbers. A string supplied by the sender
+   * is never opened.
+   *
+   * `accuracy` is the radius in metres, when known. A client too old to know this type fails the
+   * discriminated union and leaves an "integrity check failed" line, which is better than
+   * disguising the message as text — that would put coordinates in a body where they render as a
+   * tappable link.
+   */
+  z.object({
+    t: z.literal('location'),
+    lat: z.number().min(-90).max(90),
+    lng: z.number().min(-180).max(180),
+    accuracy: z.number().nonnegative().max(100_000).optional(),
+    parentId,
+    replyTo,
+  }),
+  // System events sent by clients — this path is for things the server must not learn.
+  z.object({
+    t: z.literal('sys.screenshot'),
+  }),
+  /**
+   * Pins a channel post. With a `messageId` the post is pinned; **without one the pin is cleared.**
+   *
+   * The pin is not server state for the same reason posting rights are not: the server cannot tell
+   * which ciphertext is a post, so it could not act on "pin that one" without being told, in the
+   * clear, which message belongs to which room. So a pin travels exactly like a post — one message
+   * encrypted with the room key — and every device records it locally.
+   *
+   * Authority works the same way. The control is shown only to the admin, and a receiving client
+   * applies the pin only when the sender created the room. Outside a channel it is ignored.
+   *
+   * **A channel has one pin.** Pinning again replaces it, ordered by the message's `createdAt` so
+   * that an old event arriving late cannot overwrite a newer pin.
+   *
+   * A client too old to know this type fails the discriminated union and leaves an "integrity check
+   * failed" line.
+   */
+  z.object({
+    t: z.literal('sys.pin'),
+    messageId: z.string().uuid().optional(),
+  }),
+]);
+
+export type MessageBody = z.infer<typeof messageBodySchema>;
+
+/**
+ * How an encrypted message travels — the same shape the crypto layer produces. The size limits here
+ * are the ones the server enforces.
+ */
+export const encryptedPayloadSchema = z.object({
+  ciphertext: z.string().min(1).max(TEXT_CIPHERTEXT_MAX),
+  iv: z.string().min(1).max(64), // 16-byte AES-CBC IV, base64 = 24 chars
+  mac: z.string().min(1).max(128), // HMAC-SHA256 in hex = 64 chars
+});
+
+export type EncryptedPayload = z.infer<typeof encryptedPayloadSchema>;

package/src/wire/constants.ts

@@ -0,0 +1,35 @@
+/**
+ * Generated from protocol/src/constants.ts in the graygate monorepo — do not edit by hand.
+ * Only the declarations the bot SDK needs are here; the rest of that module stays private.
+ */
+
+/** Largest ciphertext a text message may carry (bytes, after base64 encoding). */
+export const TEXT_CIPHERTEXT_MAX = 64 * 1024;
+
+/** Largest media file (bytes). Uploaded straight to object storage, never through the server. */
+export const MEDIA_MAX_BYTES = 50 * 1024 * 1024;
+
+/**
+ * Longest comment on a channel post (a post itself may run to 8,000 characters — see body.ts).
+ * **Only the sending client enforces this**: the limit lives inside the ciphertext, where the
+ * server cannot see it.
+ */
+export const COMMENT_TEXT_MAX = 2000;
+
+/**
+ * The client header (`x-graygate-client`) a bot runtime sends — **not a secret.**
+ *
+ * The edge in front of the server keeps out traffic that never came from a graygate client at all;
+ * it is not a security boundary, so bots get their own value alongside the app's and both are
+ * accepted. The edge worker and the server hold copies of both.
+ */
+export const BOT_CLIENT_TOKEN = 'Qb7dK2mXhs1TfLpA9wEzR4vNc0uGyJ6i';
+
+/** Bot access-token lifetime (minutes), same as a person's. No refresh token: the bot token is the long-lived credential. */
+export const BOT_ACCESS_TOKEN_TTL_MIN = 15;
+
+/** Most items one webhook request may carry. */
+export const BOT_WEBHOOK_BATCH_MAX = 100;
+
+/** How far a signature timestamp may be from now (seconds). Anything further is treated as a replay and dropped. */
+export const BOT_WEBHOOK_SIGNATURE_TOLERANCE_S = 300;

package/src/wire/crypto.ts

@@ -0,0 +1,132 @@
+/**
+ * Generated from crypto/src/index.ts in the graygate monorepo — do not edit by hand.
+ * Only the declarations the bot SDK needs are here; the rest of that module stays private.
+ */
+
+import CryptoJS from 'crypto-js';
+import forge from 'node-forge';
+import { CryptoUtils } from 'graygate-cypher/dist/crypto';
+
+export class IntegrityError extends Error {
+  constructor() {
+    super('message integrity check failed (HMAC mismatch)');
+    this.name = 'IntegrityError';
+  }
+}
+
+export class DecryptionError extends Error {
+  constructor() {
+    super('decryption failed');
+    this.name = 'DecryptionError';
+  }
+}
+
+/** Domain separation — one password derives keys that are independent of each other. */
+const CTX = {
+  roomKey: 'graygate:v1:roomkey',
+  verifier: 'graygate:v1:verifier',
+  hmac: 'graygate:v1:hmac',
+  devicePin: 'graygate:v1:devicepin',
+  /** Recovery phrase to the verifier sent to the server. */
+  recovery: 'graygate:v1:recovery',
+  /** Recovery phrase to the verifier kept on this device. **Must differ** from the server's. */
+  recoveryLocal: 'graygate:v1:recoverylocal',
+} as const;
+
+export interface EncryptedMessage {
+  ciphertext: string;
+  iv: string;
+  mac: string;
+}
+
+export interface RsaKeyPair {
+  publicKeyPem: string;
+  privateKeyPem: string;
+}
+
+/**
+ * Generates a user's RSA key pair — at signup, and again when someone moves to a new device. It is
+ * pure JavaScript, so on a phone it can take tens of seconds.
+ *
+ * **Why the stepwise generator:** the callback form of `generateKeyPair` holds the JavaScript thread
+ * for the whole computation when there is no worker to run it on. The progress line set just before
+ * it ("generating keys") never reaches the screen, and the person watches the *previous* step's text
+ * sit there for half a minute. Stepping the generator in slices and yielding to the event loop in
+ * between keeps the progress honest — a slow security step should be **shown**, not hidden.
+ */
+export function generateRsaKeyPair(bits = 2048): Promise<RsaKeyPair> {
+  // The stepwise API exists at runtime but is missing from the type definitions, hence the cast.
+  const rsa = forge.pki.rsa as unknown as {
+    createKeyPairGenerationState(bits: number, e: number): { keys: forge.pki.KeyPair | null };
+    stepKeyPairGenerationState(state: unknown, ms: number): boolean;
+  };
+
+  return new Promise((resolve, reject) => {
+    const state = rsa.createKeyPairGenerationState(bits, 0x10001);
+    const run = (): void => {
+      try {
+        // 100ms of work at a time, then yield — enough that frames still get drawn.
+        if (!rsa.stepKeyPairGenerationState(state, 100)) {
+          setTimeout(run, 0);
+          return;
+        }
+        const keys = state.keys!;
+        resolve({
+          publicKeyPem: forge.pki.publicKeyToPem(keys.publicKey),
+          privateKeyPem: forge.pki.privateKeyToPem(keys.privateKey),
+        });
+      } catch (err) {
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    };
+    run();
+  });
+}
+
+async function deriveMacKey(roomKey: string): Promise<string> {
+  return CryptoUtils.deriveFileKey(roomKey, CTX.hmac);
+}
+
+/** Encrypts a message body (any JSON-serialisable value) with the room key and signs it. */
+export async function encryptMessage(roomKey: string, body: unknown): Promise<EncryptedMessage> {
+  const { encryptedData, iv } = await CryptoUtils.encrypt(JSON.stringify(body), roomKey);
+  const macKey = await deriveMacKey(roomKey);
+  const mac = CryptoJS.HmacSHA256(`${encryptedData}.${iv}`, macKey).toString(CryptoJS.enc.Hex);
+  return { ciphertext: encryptedData, iv, mac };
+}
+
+/**
+ * Verifies the HMAC, then decrypts. A mismatch throws `IntegrityError` and decryption is never
+ * attempted — this is the first stage of the content-validation pipeline, and it runs before any
+ * received bytes reach a parser.
+ */
+export async function decryptMessage(roomKey: string, msg: EncryptedMessage): Promise<unknown> {
+  const macKey = await deriveMacKey(roomKey);
+  const expected = CryptoJS.HmacSHA256(`${msg.ciphertext}.${msg.iv}`, macKey).toString(CryptoJS.enc.Hex);
+  if (!constantTimeEqual(expected, msg.mac)) throw new IntegrityError();
+
+  let plain: string;
+  try {
+    plain = await CryptoUtils.decrypt(msg.ciphertext, roomKey, msg.iv);
+  } catch {
+    throw new DecryptionError();
+  }
+  if (!plain) throw new DecryptionError();
+  try {
+    return JSON.parse(plain);
+  } catch {
+    throw new DecryptionError();
+  }
+}
+
+/** Opens an envelope with this device's private key (PEM) and returns the room key. */
+export function unwrapRoomKey(wrapped: string, privateKeyPem: string): Promise<string> {
+  return CryptoUtils.decryptFileKey(wrapped, new TextEncoder().encode(privateKeyPem));
+}
+
+function constantTimeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}

package/src/wire/events.ts

@@ -0,0 +1,29 @@
+/**
+ * Generated from protocol/src/ws.ts in the graygate monorepo — do not edit by hand.
+ * Only the declarations the bot SDK needs are here; the rest of that module stays private.
+ */
+
+import { encryptedPayloadSchema } from './body';
+import { z } from 'zod';
+
+const uuid = z.string().uuid();
+
+export const msgNewPayload = z.object({
+  id: uuid,
+  roomId: uuid,
+  senderId: uuid,
+  keyVersion: z.number().int().positive(),
+  kind: z.enum(['text', 'media']),
+  ciphertext: encryptedPayloadSchema,
+  mediaId: uuid.optional(),
+  createdAt: z.string().datetime(),
+});
+
+export const envelopeNewPayload = z.object({
+  id: uuid,
+  roomId: uuid,
+  keyVersion: z.number().int().positive(),
+  purpose: z.enum(['invite', 'rotation']),
+  ciphertext: z.string().min(1), // RSA-OAEP base64
+  createdBy: uuid,
+});

package/src/wire/index.ts

@@ -0,0 +1,9 @@
+/**
+ * The wire format the bot speaks — message bodies, webhook items, and the crypto around them.
+ * Generated from the graygate monorepo (see scripts/export-public.mjs there); do not edit.
+ */
+export * from './constants';
+export * from './body';
+export * from './events';
+export * from './webhook';
+export * from './crypto';

package/src/wire/webhook.ts

@@ -0,0 +1,38 @@
+/**
+ * Generated from protocol/src/rest.ts in the graygate monorepo — do not edit by hand.
+ * Only the declarations the bot SDK needs are here; the rest of that module stays private.
+ */
+
+import { BOT_WEBHOOK_BATCH_MAX } from './constants';
+import { envelopeNewPayload, msgNewPayload } from './events';
+import { z } from 'zod';
+
+const uuid = z.string().uuid();
+
+/**
+ * The webhook body a bot receives. Each item has **the same shape** as the payload the WebSocket
+ * pushes to a phone.
+ *
+ * What leaves is ciphertext, so a webhook delivered to the wrong address leaks the metadata around
+ * a message — room id, sender id, timestamp — and not what was said.
+ */
+export const botWebhookItem = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('msg.new'), payload: msgNewPayload }),
+  z.object({ type: z.literal('envelope.new'), payload: envelopeNewPayload }),
+  z.object({ type: z.literal('member.joined'), payload: z.object({ roomId: uuid, userId: uuid }) }),
+  z.object({ type: z.literal('member.left'), payload: z.object({ roomId: uuid, userId: uuid }) }),
+  z.object({
+    type: z.literal('member.key_changed'),
+    payload: z.object({ roomId: uuid, userId: uuid, keyUpdatedAt: z.string().datetime() }),
+  }),
+  z.object({ type: z.literal('room.deleted'), payload: z.object({ roomId: uuid }) }),
+]);
+
+export type BotWebhookItem = z.infer<typeof botWebhookItem>;
+
+export const botWebhookBody = z.object({
+  botId: uuid,
+  items: z.array(botWebhookItem).max(BOT_WEBHOOK_BATCH_MAX),
+});
+
+export type BotWebhookBody = z.infer<typeof botWebhookBody>;