@wakeshift/sdk 0.0.0-stage → 0.2.0

package/dist/harness.js

@@ -0,0 +1,78 @@
+// harnessAgent names the agent a guest's MCP client signs in as: its
+// harness's ID ("copilot-cli" → copilot, "Claude Code" → claude-code), as
+// topics name it, else its name as an ID. A port
+// of the core's harnesses.AgentID: test/agent-ids.json is the Go
+// function's output, and both sides' tests check it.
+// The core's harness table (internal/harnesses): only what naming needs.
+const known = [
+    { id: "codex", clients: ["codex-mcp-client"] },
+    { id: "claude-code", clients: ["claude-code"] },
+    { id: "cursor", clients: ["Cursor", "cursor-vscode"] },
+    { id: "cursor-cloud", clients: [] },
+    { id: "grok-bot", clients: [] },
+    { id: "copilot", clients: ["copilot-cli"] },
+    { id: "opencode", clients: ["opencode"] },
+    { id: "antigravity", clients: ["antigravity-client"] },
+    { id: "openclaw", clients: ["openclaw-bundle-mcp"] },
+    { id: "hermes", clients: ["mcp"], unsure: true },
+    { id: "chatgpt", clients: ["openai-mcp"] },
+    { id: "gemini", clients: ["gemini-cli-mcp-client"] },
+    { id: "goose", clients: ["goose-cli", "goose-desktop"] },
+    { id: "cline", clients: ["Cline"] },
+    { id: "amp", clients: [] },
+    { id: "devin", clients: [] },
+    { id: "vscode", clients: ["Visual Studio Code", "Visual Studio Code - Insiders"] },
+];
+/**
+ * The agent ID an MCP client's name maps to: its harness's ID, else the
+ * name as an ID (2–40 lowercase letters, digits and dashes; "agent" if
+ * nothing's left).
+ */
+export function harnessAgent(client) {
+    const name = client.trim().toLowerCase();
+    if (name) {
+        for (const h of known) {
+            if (h.clients.some((c) => c.toLowerCase() === name)) {
+                if (!h.unsure)
+                    return h.id;
+                break;
+            }
+        }
+    }
+    const id = slug(client);
+    for (const h of known) {
+        if (h.unsure)
+            continue;
+        if (id === h.id || id.startsWith(h.id + "-"))
+            return h.id;
+        if (h.clients.some((c) => id === slug(c)))
+            return h.id;
+    }
+    return id;
+}
+// slug is a name as an agent ID: lowercase letters, digits and dashes, up
+// to 40 characters, without anything in parentheses ("agent" if fewer than
+// 2 are left).
+function slug(name) {
+    let n = name.toLowerCase();
+    const i = n.indexOf("(");
+    if (i > 0)
+        n = n.slice(0, i);
+    let out = "";
+    let dash = false;
+    for (const r of n.trim()) {
+        if ((r >= "a" && r <= "z") || (r >= "0" && r <= "9")) {
+            out += r;
+            dash = false;
+        }
+        else if (!dash && out.length > 0) {
+            out += "-";
+            dash = true;
+        }
+    }
+    let id = out.replace(/^-+|-+$/g, "");
+    if (id.length > 40)
+        id = id.slice(0, 40).replace(/^-+|-+$/g, "");
+    return id.length < 2 ? "agent" : id;
+}
+//# sourceMappingURL=harness.js.map

package/dist/harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.js","sourceRoot":"","sources":["../src/harness.ts"],"names":[],"mappings":"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","sourcesContent":["// harnessAgent names the agent a guest's MCP client signs in as: its\n// harness's ID (\"copilot-cli\" → copilot, \"Claude Code\" → claude-code), as\n// topics name it, else its name as an ID. A port\n// of the core's harnesses.AgentID: test/agent-ids.json is the Go\n// function's output, and both sides' tests check it.\n\ninterface Known {\n  id: string;\n  clients: string[];\n  /** Its client name is one others send too (Hermes Agent's \"mcp\"): it keeps its own ID. */\n  unsure?: boolean;\n}\n\n// The core's harness table (internal/harnesses): only what naming needs.\nconst known: Known[] = [\n  { id: \"codex\", clients: [\"codex-mcp-client\"] },\n  { id: \"claude-code\", clients: [\"claude-code\"] },\n  { id: \"cursor\", clients: [\"Cursor\", \"cursor-vscode\"] },\n  { id: \"cursor-cloud\", clients: [] },\n  { id: \"grok-bot\", clients: [] },\n  { id: \"copilot\", clients: [\"copilot-cli\"] },\n  { id: \"opencode\", clients: [\"opencode\"] },\n  { id: \"antigravity\", clients: [\"antigravity-client\"] },\n  { id: \"openclaw\", clients: [\"openclaw-bundle-mcp\"] },\n  { id: \"hermes\", clients: [\"mcp\"], unsure: true },\n  { id: \"chatgpt\", clients: [\"openai-mcp\"] },\n  { id: \"gemini\", clients: [\"gemini-cli-mcp-client\"] },\n  { id: \"goose\", clients: [\"goose-cli\", \"goose-desktop\"] },\n  { id: \"cline\", clients: [\"Cline\"] },\n  { id: \"amp\", clients: [] },\n  { id: \"devin\", clients: [] },\n  { id: \"vscode\", clients: [\"Visual Studio Code\", \"Visual Studio Code - Insiders\"] },\n];\n\n/**\n * The agent ID an MCP client's name maps to: its harness's ID, else the\n * name as an ID (2–40 lowercase letters, digits and dashes; \"agent\" if\n * nothing's left).\n */\nexport function harnessAgent(client: string): string {\n  const name = client.trim().toLowerCase();\n  if (name) {\n    for (const h of known) {\n      if (h.clients.some((c) => c.toLowerCase() === name)) {\n        if (!h.unsure) return h.id;\n        break;\n      }\n    }\n  }\n  const id = slug(client);\n  for (const h of known) {\n    if (h.unsure) continue;\n    if (id === h.id || id.startsWith(h.id + \"-\")) return h.id;\n    if (h.clients.some((c) => id === slug(c))) return h.id;\n  }\n  return id;\n}\n\n// slug is a name as an agent ID: lowercase letters, digits and dashes, up\n// to 40 characters, without anything in parentheses (\"agent\" if fewer than\n// 2 are left).\nfunction slug(name: string): string {\n  let n = name.toLowerCase();\n  const i = n.indexOf(\"(\");\n  if (i > 0) n = n.slice(0, i);\n  let out = \"\";\n  let dash = false;\n  for (const r of n.trim()) {\n    if ((r >= \"a\" && r <= \"z\") || (r >= \"0\" && r <= \"9\")) {\n      out += r;\n      dash = false;\n    } else if (!dash && out.length > 0) {\n      out += \"-\";\n      dash = true;\n    }\n  }\n  let id = out.replace(/^-+|-+$/g, \"\");\n  if (id.length > 40) id = id.slice(0, 40).replace(/^-+|-+$/g, \"\");\n  return id.length < 2 ? \"agent\" : id;\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { Wakeshift, DEFAULT_CORE, SESSION_ARG, HARNESS_ARG, CONVERSATION_ARG, UNKNOWN_CLIENT_WARNING, type WakeshiftOptions, type AppInfo, type Call, type CallOptions, type ClientInfoSource, type Duration, type SubscribeOptions, type Subscription, type Addition, type Recognised, type TopicEvent, type Published, type SendStatus, type Via, type TopicStatus, type SubscriptionStatus, type PublishUrl, type ToolExtra, type Manifest, type AgentScope, type ScopeEvent, } from "./wakeshift.js";
+export { GuestAuth, guestOf, type Guest, type GuestAuthOptions, type GuestAuthInfo } from "./guest.js";
+export { harnessAgent } from "./harness.js";
+export { WakeshiftError, isCode } from "./errors.js";
+export { parseKey, signAssertion, type AppKey } from "./key.js";
+export { WakeEvent, ArgsError, speaksEvents, EVENT_TOOL_TEXT, SUBSCRIBE_TOOL_DESCRIPTION, UNSUBSCRIBE_TOOL_DESCRIPTION, LIST_TOOL_DESCRIPTION, type EventOptions, type EmitOptions, type CallerSubscription, type EventTypeManifest, type AttachOptions, type Identity, type Subscriber, } from "./events.js";
+export { EXTENSION_KEY, LEGACY_KEY, TEXT_META, REVISION as EVENTS_REVISION } from "./spec.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { Wakeshift, DEFAULT_CORE, SESSION_ARG, HARNESS_ARG, CONVERSATION_ARG, UNKNOWN_CLIENT_WARNING, } from "./wakeshift.js";
+export { GuestAuth, guestOf } from "./guest.js";
+export { harnessAgent } from "./harness.js";
+export { WakeshiftError, isCode } from "./errors.js";
+export { parseKey, signAssertion } from "./key.js";
+export { WakeEvent, ArgsError, speaksEvents, EVENT_TOOL_TEXT, SUBSCRIBE_TOOL_DESCRIPTION, UNSUBSCRIBE_TOOL_DESCRIPTION, LIST_TOOL_DESCRIPTION, } from "./events.js";
+export { EXTENSION_KEY, LEGACY_KEY, TEXT_META, REVISION as EVENTS_REVISION } from "./spec.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,YAAY,EACZ,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,sBAAsB,GAsBvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,OAAO,EAAyD,MAAM,YAAY,CAAC;AACvG,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAe,MAAM,UAAU,CAAC;AAChE,OAAO,EACL,SAAS,EACT,SAAS,EACT,YAAY,EACZ,eAAe,EACf,0BAA0B,EAC1B,4BAA4B,EAC5B,qBAAqB,GAQtB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,IAAI,eAAe,EAAE,MAAM,WAAW,CAAC","sourcesContent":["export {\n  Wakeshift,\n  DEFAULT_CORE,\n  SESSION_ARG,\n  HARNESS_ARG,\n  CONVERSATION_ARG,\n  UNKNOWN_CLIENT_WARNING,\n  type WakeshiftOptions,\n  type AppInfo,\n  type Call,\n  type CallOptions,\n  type ClientInfoSource,\n  type Duration,\n  type SubscribeOptions,\n  type Subscription,\n  type Addition,\n  type Recognised,\n  type TopicEvent,\n  type Published,\n  type SendStatus,\n  type Via,\n  type TopicStatus,\n  type SubscriptionStatus,\n  type PublishUrl,\n  type ToolExtra,\n  type Manifest,\n  type AgentScope,\n  type ScopeEvent,\n} from \"./wakeshift.js\";\nexport { GuestAuth, guestOf, type Guest, type GuestAuthOptions, type GuestAuthInfo } from \"./guest.js\";\nexport { harnessAgent } from \"./harness.js\";\nexport { WakeshiftError, isCode } from \"./errors.js\";\nexport { parseKey, signAssertion, type AppKey } from \"./key.js\";\nexport {\n  WakeEvent,\n  ArgsError,\n  speaksEvents,\n  EVENT_TOOL_TEXT,\n  SUBSCRIBE_TOOL_DESCRIPTION,\n  UNSUBSCRIBE_TOOL_DESCRIPTION,\n  LIST_TOOL_DESCRIPTION,\n  type EventOptions,\n  type EmitOptions,\n  type CallerSubscription,\n  type EventTypeManifest,\n  type AttachOptions,\n  type Identity,\n  type Subscriber,\n} from \"./events.js\";\nexport { EXTENSION_KEY, LEGACY_KEY, TEXT_META, REVISION as EVENTS_REVISION } from \"./spec.js\";\n"]}

package/dist/key.d.ts

@@ -0,0 +1,29 @@
+import { type KeyObject } from "node:crypto";
+export interface AppKey {
+    /**
+     * An older key's mode; null for a current key.
+     * @deprecated Modes mean nothing now, and current keys have none.
+     */
+    mode: "test" | "live" | null;
+    /** The app's ID, for an older key that names it; null for a current key (ask Wakeshift: `wake.app()`). */
+    appId: string | null;
+    privateKey: KeyObject;
+    /** The 32-byte seed: what the SDK's own signed values (guest sign-in) are keyed from. */
+    seed: Buffer;
+    /** The key's ID in assertions' headers: base64url of the first 16 bytes of the public key's SHA-256. */
+    kid: string;
+}
+/** Reads an app key from the console, either format. Throws on anything else. */
+export declare function parseKey(key: string): AppKey;
+/** A raw 32-byte Ed25519 public key's kid: base64url of the first 16 bytes of its SHA-256. */
+export declare function keyIdOf(publicKey: Uint8Array): string;
+/** The app's public key, base64url (what the console stores). */
+export declare function publicKeyOf(k: AppKey): string;
+/**
+ * Signs a fresh assertion of the app's identity for core (its base URL,
+ * without a trailing slash): a compact JWS, alg EdDSA, typ app+jwt, with
+ * the key's kid, living two minutes. iss and sub are the app's ID when
+ * it's known (an older key names it; pass appId once Wakeshift has said
+ * it), else the kid.
+ */
+export declare function signAssertion(k: AppKey, core: string, now?: number, appId?: string | null): string;

package/dist/key.js

@@ -0,0 +1,107 @@
+import { createHash, createPrivateKey, createPublicKey, randomBytes, sign } from "node:crypto";
+const appIdRE = /^[a-z][a-z0-9-]{1,39}$/;
+const seedRE = /^[A-Za-z0-9_-]{43}$/;
+const alphabet = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+const LEN = 50;
+const LIMIT = 1n << 288n;
+// PKCS #8 for an Ed25519 key, before its 32-byte seed (RFC 8410).
+const pkcs8Prefix = Buffer.from("302e020100300506032b657004220420", "hex");
+// Errors never include the key.
+const errFormat = "wakeshift: an app key is wst_ followed by 50 letters and digits (or an older wst_test_… or wst_live_… key)";
+const errMistyped = "wakeshift: the app key is cut short or mistyped";
+// CRC32 (IEEE). zlib.crc32 needs Node 22.2; the package supports 22.0.
+const crcTable = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(b) {
+    let c = 0xffffffff;
+    for (const x of b)
+        c = crcTable[(c ^ x) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** Reads an app key from the console, either format. Throws on anything else. */
+export function parseKey(key) {
+    const s = String(key ?? "").trim();
+    if (!s.startsWith("wst_"))
+        throw new Error("wakeshift: an app key starts with wst_");
+    const rest = s.slice(4);
+    const i = rest.indexOf("_");
+    if (i >= 0)
+        return parseOld(rest.slice(0, i), rest.slice(i + 1));
+    if (rest.length !== LEN)
+        throw new Error(errMistyped);
+    let n = 0n;
+    for (const ch of rest) {
+        const d = alphabet.indexOf(ch);
+        if (d < 0)
+            throw new Error(errMistyped);
+        n = n * 58n + BigInt(d);
+    }
+    if (n >= LIMIT)
+        throw new Error(errMistyped);
+    const b = Buffer.from(n.toString(16).padStart(72, "0"), "hex");
+    const seed = Buffer.from(b.subarray(0, 32));
+    if (crc32(seed) !== b.readUInt32BE(32))
+        throw new Error(errMistyped);
+    return fromSeed(null, null, seed);
+}
+// An older key: wst_<mode>_<app id>_<seed>. App IDs have no "_"; the seed
+// (base64url) may.
+function parseOld(mode, after) {
+    if (mode !== "test" && mode !== "live")
+        throw new Error(errFormat);
+    const j = after.indexOf("_");
+    const appId = j < 0 ? "" : after.slice(0, j);
+    if (!appIdRE.test(appId))
+        throw new Error("wakeshift: the app key has no app ID");
+    const seed = after.slice(j + 1);
+    const raw = seedRE.test(seed) ? Buffer.from(seed, "base64url") : Buffer.alloc(0);
+    if (raw.length !== 32)
+        throw new Error(errMistyped);
+    return fromSeed(mode, appId, raw);
+}
+function fromSeed(mode, appId, seed) {
+    const privateKey = createPrivateKey({ key: Buffer.concat([pkcs8Prefix, seed]), format: "der", type: "pkcs8" });
+    return { mode, appId, privateKey, seed, kid: keyIdOf(rawPublicKey(privateKey)) };
+}
+function rawPublicKey(k) {
+    return Buffer.from(createPublicKey(k).export({ format: "jwk" }).x, "base64url");
+}
+/** A raw 32-byte Ed25519 public key's kid: base64url of the first 16 bytes of its SHA-256. */
+export function keyIdOf(publicKey) {
+    return createHash("sha256").update(publicKey).digest().subarray(0, 16).toString("base64url");
+}
+/** The app's public key, base64url (what the console stores). */
+export function publicKeyOf(k) {
+    return rawPublicKey(k.privateKey).toString("base64url");
+}
+const b64 = (v) => Buffer.from(typeof v === "string" ? v : JSON.stringify(v)).toString("base64url");
+/**
+ * Signs a fresh assertion of the app's identity for core (its base URL,
+ * without a trailing slash): a compact JWS, alg EdDSA, typ app+jwt, with
+ * the key's kid, living two minutes. iss and sub are the app's ID when
+ * it's known (an older key names it; pass appId once Wakeshift has said
+ * it), else the kid.
+ */
+export function signAssertion(k, core, now = Date.now(), appId) {
+    const iat = Math.floor(now / 1000);
+    const who = appId || k.appId || k.kid;
+    const claims = {
+        iss: who,
+        sub: who,
+        aud: core + "/api/apps",
+        iat,
+        exp: iat + 120,
+        jti: randomBytes(16).toString("base64url"),
+    };
+    const input = b64({ alg: "EdDSA", typ: "app+jwt", kid: k.kid }) + "." + b64(claims);
+    return input + "." + sign(null, Buffer.from(input), k.privateKey).toString("base64url");
+}
+//# sourceMappingURL=key.js.map

package/dist/key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, createPrivateKey, createPublicKey, randomBytes, sign, type KeyObject } from \"node:crypto\";\n\n// An app key from the Wakeshift console is the app's Ed25519 private key.\n// Current keys are\n//\n//   wst_<50 base58 characters>\n//\n// 36 bytes, the 32-byte seed then the CRC32 (IEEE, big-endian) of the\n// seed, read as one big-endian integer and written in base58 (Bitcoin's\n// alphabet), left-padded with \"1\". They name no app: Wakeshift finds the\n// app by the key's kid, which every assertion's header carries, and says\n// which it is (GET /api/apps/v1/app). Older keys, which keep working, are\n//\n//   wst_<test|live>_<app id>_<seed, base64url>\n//\n// The two can't be confused: base58 has no \"_\". The key never goes over\n// the wire: it signs short-lived assertions, and Wakeshift keeps only the\n// public half.\n\nexport interface AppKey {\n  /**\n   * An older key's mode; null for a current key.\n   * @deprecated Modes mean nothing now, and current keys have none.\n   */\n  mode: \"test\" | \"live\" | null;\n  /** The app's ID, for an older key that names it; null for a current key (ask Wakeshift: `wake.app()`). */\n  appId: string | null;\n  privateKey: KeyObject;\n  /** The 32-byte seed: what the SDK's own signed values (guest sign-in) are keyed from. */\n  seed: Buffer;\n  /** The key's ID in assertions' headers: base64url of the first 16 bytes of the public key's SHA-256. */\n  kid: string;\n}\n\nconst appIdRE = /^[a-z][a-z0-9-]{1,39}$/;\nconst seedRE = /^[A-Za-z0-9_-]{43}$/;\nconst alphabet = \"123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz\";\nconst LEN = 50;\nconst LIMIT = 1n << 288n;\n// PKCS #8 for an Ed25519 key, before its 32-byte seed (RFC 8410).\nconst pkcs8Prefix = Buffer.from(\"302e020100300506032b657004220420\", \"hex\");\n\n// Errors never include the key.\nconst errFormat = \"wakeshift: an app key is wst_ followed by 50 letters and digits (or an older wst_test_… or wst_live_… key)\";\nconst errMistyped = \"wakeshift: the app key is cut short or mistyped\";\n\n// CRC32 (IEEE). zlib.crc32 needs Node 22.2; the package supports 22.0.\nconst crcTable = (() => {\n  const t = new Uint32Array(256);\n  for (let n = 0; n < 256; n++) {\n    let c = n;\n    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;\n    t[n] = c >>> 0;\n  }\n  return t;\n})();\n\nfunction crc32(b: Uint8Array): number {\n  let c = 0xffffffff;\n  for (const x of b) c = crcTable[(c ^ x) & 0xff] ^ (c >>> 8);\n  return (c ^ 0xffffffff) >>> 0;\n}\n\n/** Reads an app key from the console, either format. Throws on anything else. */\nexport function parseKey(key: string): AppKey {\n  const s = String(key ?? \"\").trim();\n  if (!s.startsWith(\"wst_\")) throw new Error(\"wakeshift: an app key starts with wst_\");\n  const rest = s.slice(4);\n  const i = rest.indexOf(\"_\");\n  if (i >= 0) return parseOld(rest.slice(0, i), rest.slice(i + 1));\n  if (rest.length !== LEN) throw new Error(errMistyped);\n  let n = 0n;\n  for (const ch of rest) {\n    const d = alphabet.indexOf(ch);\n    if (d < 0) throw new Error(errMistyped);\n    n = n * 58n + BigInt(d);\n  }\n  if (n >= LIMIT) throw new Error(errMistyped);\n  const b = Buffer.from(n.toString(16).padStart(72, \"0\"), \"hex\");\n  const seed = Buffer.from(b.subarray(0, 32));\n  if (crc32(seed) !== b.readUInt32BE(32)) throw new Error(errMistyped);\n  return fromSeed(null, null, seed);\n}\n\n// An older key: wst_<mode>_<app id>_<seed>. App IDs have no \"_\"; the seed\n// (base64url) may.\nfunction parseOld(mode: string, after: string): AppKey {\n  if (mode !== \"test\" && mode !== \"live\") throw new Error(errFormat);\n  const j = after.indexOf(\"_\");\n  const appId = j < 0 ? \"\" : after.slice(0, j);\n  if (!appIdRE.test(appId)) throw new Error(\"wakeshift: the app key has no app ID\");\n  const seed = after.slice(j + 1);\n  const raw = seedRE.test(seed) ? Buffer.from(seed, \"base64url\") : Buffer.alloc(0);\n  if (raw.length !== 32) throw new Error(errMistyped);\n  return fromSeed(mode, appId, raw);\n}\n\nfunction fromSeed(mode: AppKey[\"mode\"], appId: string | null, seed: Buffer): AppKey {\n  const privateKey = createPrivateKey({ key: Buffer.concat([pkcs8Prefix, seed]), format: \"der\", type: \"pkcs8\" });\n  return { mode, appId, privateKey, seed, kid: keyIdOf(rawPublicKey(privateKey)) };\n}\n\nfunction rawPublicKey(k: KeyObject): Buffer {\n  return Buffer.from(createPublicKey(k).export({ format: \"jwk\" }).x as string, \"base64url\");\n}\n\n/** A raw 32-byte Ed25519 public key's kid: base64url of the first 16 bytes of its SHA-256. */\nexport function keyIdOf(publicKey: Uint8Array): string {\n  return createHash(\"sha256\").update(publicKey).digest().subarray(0, 16).toString(\"base64url\");\n}\n\n/** The app's public key, base64url (what the console stores). */\nexport function publicKeyOf(k: AppKey): string {\n  return rawPublicKey(k.privateKey).toString(\"base64url\");\n}\n\nconst b64 = (v: unknown) => Buffer.from(typeof v === \"string\" ? v : JSON.stringify(v)).toString(\"base64url\");\n\n/**\n * Signs a fresh assertion of the app's identity for core (its base URL,\n * without a trailing slash): a compact JWS, alg EdDSA, typ app+jwt, with\n * the key's kid, living two minutes. iss and sub are the app's ID when\n * it's known (an older key names it; pass appId once Wakeshift has said\n * it), else the kid.\n */\nexport function signAssertion(k: AppKey, core: string, now = Date.now(), appId?: string | null): string {\n  const iat = Math.floor(now / 1000);\n  const who = appId || k.appId || k.kid;\n  const claims = {\n    iss: who,\n    sub: who,\n    aud: core + \"/api/apps\",\n    iat,\n    exp: iat + 120,\n    jti: randomBytes(16).toString(\"base64url\"),\n  };\n  const input = b64({ alg: \"EdDSA\", typ: \"app+jwt\", kid: k.kid }) + \".\" + b64(claims);\n  return input + \".\" + sign(null, Buffer.from(input), k.privateKey).toString(\"base64url\");\n}\n"]}

package/dist/limits.d.ts

@@ -0,0 +1,19 @@
+import type { IncomingMessage } from "node:http";
+/** A rate limiter: at most max events per window (ms) for each key, in memory, pruning idle keys as it goes. A negative max turns it off. */
+export declare class RateLimiter {
+    readonly max: number;
+    readonly window: number;
+    readonly keys: number;
+    private readonly seen;
+    private pruned;
+    constructor(max: number, window: number, keys?: number);
+    allow(key: string, now: number): boolean;
+}
+/** What an address counts as for the limits: an IPv6 address's /64 (one host usually has a whole /64), anything else as it is. */
+export declare function limitKey(addr: string): string;
+/**
+ * The request's client address: with hops trusted proxies in front (each
+ * appending to X-Forwarded-For), the entry the outermost one added; entries
+ * before it are the client's own claims.
+ */
+export declare function clientAddr(req: IncomingMessage, hops: number): string;

package/dist/limits.js

@@ -0,0 +1,105 @@
+// Per-address limits for unauthenticated endpoints (GuestAuth's register
+// and token): who a request is from, behind trusted proxies, and how many
+// requests each address may make. In memory, per process.
+import { isIP } from "node:net";
+// LIMITER_KEYS bounds a limiter's memory: past it, a new address is refused
+// until old ones expire (the endpoints are unauthenticated, and IPv6 makes
+// addresses cheap).
+const LIMITER_KEYS = 100_000;
+/** A rate limiter: at most max events per window (ms) for each key, in memory, pruning idle keys as it goes. A negative max turns it off. */
+export class RateLimiter {
+    max;
+    window;
+    keys;
+    seen = new Map();
+    pruned = 0;
+    constructor(max, window, keys = LIMITER_KEYS) {
+        this.max = max;
+        this.window = window;
+        this.keys = keys;
+    }
+    allow(key, now) {
+        if (this.max < 0)
+            return true;
+        key = limitKey(key);
+        const cut = now - this.window;
+        const prune = () => {
+            for (const [k, ts] of this.seen)
+                if (ts.length === 0 || ts[ts.length - 1] <= cut)
+                    this.seen.delete(k);
+            this.pruned = now;
+        };
+        if (now - this.pruned > this.window)
+            prune();
+        if (!this.seen.has(key) && this.seen.size >= this.keys) {
+            prune();
+            if (this.seen.size >= this.keys)
+                return false;
+        }
+        const ts = (this.seen.get(key) ?? []).filter((t) => t > cut);
+        if (ts.length >= this.max) {
+            this.seen.set(key, ts);
+            return false;
+        }
+        ts.push(now);
+        this.seen.set(key, ts);
+        return true;
+    }
+}
+/** What an address counts as for the limits: an IPv6 address's /64 (one host usually has a whole /64), anything else as it is. */
+export function limitKey(addr) {
+    const a = addr.replace(/%.*$/, "");
+    if (isIP(a) !== 6 || /^::ffff:\d+\.\d+\.\d+\.\d+$/i.test(a))
+        return addr;
+    const groups = expandIPv6(a);
+    return groups ? groups.slice(0, 4).join(":") + "::/64" : addr;
+}
+// expandIPv6 is an IPv6 address's eight groups (a dotted IPv4 tail as two).
+function expandIPv6(a) {
+    let s = a.toLowerCase();
+    const v4 = /(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(s);
+    if (v4) {
+        const b = v4.slice(1).map(Number);
+        s = s.slice(0, v4.index) + ((b[0] << 8) | b[1]).toString(16) + ":" + ((b[2] << 8) | b[3]).toString(16);
+    }
+    const halves = s.split("::");
+    if (halves.length > 2)
+        return null;
+    const head = halves[0] ? halves[0].split(":") : [];
+    const tail = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+    const fill = halves.length === 2 ? 8 - head.length - tail.length : 0;
+    const all = [...head, ...Array(Math.max(fill, 0)).fill("0"), ...tail];
+    if (all.length !== 8)
+        return null;
+    return all.map((g) => parseInt(g, 16).toString(16));
+}
+/**
+ * The request's client address: with hops trusted proxies in front (each
+ * appending to X-Forwarded-For), the entry the outermost one added; entries
+ * before it are the client's own claims.
+ */
+export function clientAddr(req, hops) {
+    // The first X-Forwarded-For header only, as Go's Header.Get reads it.
+    const distinct = req.headersDistinct?.["x-forwarded-for"];
+    const raw = req.headers["x-forwarded-for"];
+    const f = distinct?.[0] ?? (Array.isArray(raw) ? raw[0] : raw);
+    if (f && hops > 0) {
+        // Only an entry the proxies added: with fewer entries than hops, or one
+        // that isn't an address, the header isn't the proxies' (a request that
+        // reached the app some other way), so it's ignored.
+        const parts = f.split(",");
+        if (parts.length >= hops) {
+            const ip = parts[parts.length - hops].trim();
+            if (isIP(ip))
+                return normalizeAddr(ip);
+        }
+    }
+    return normalizeAddr(req.socket?.remoteAddress ?? "");
+}
+// normalizeAddr writes an IPv4 address a dual-stack socket reports as
+// ::ffff:a.b.c.d as a.b.c.d, as Go does.
+function normalizeAddr(a) {
+    const m = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(a);
+    return m ? m[1] : a;
+}
+//# sourceMappingURL=limits.js.map

package/dist/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"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","sourcesContent":["// Per-address limits for unauthenticated endpoints (GuestAuth's register\n// and token): who a request is from, behind trusted proxies, and how many\n// requests each address may make. In memory, per process.\n\nimport type { IncomingMessage } from \"node:http\";\nimport { isIP } from \"node:net\";\n\n// LIMITER_KEYS bounds a limiter's memory: past it, a new address is refused\n// until old ones expire (the endpoints are unauthenticated, and IPv6 makes\n// addresses cheap).\nconst LIMITER_KEYS = 100_000;\n\n/** A rate limiter: at most max events per window (ms) for each key, in memory, pruning idle keys as it goes. A negative max turns it off. */\nexport class RateLimiter {\n  private readonly seen = new Map<string, number[]>();\n  private pruned = 0;\n\n  constructor(\n    readonly max: number,\n    readonly window: number,\n    readonly keys = LIMITER_KEYS,\n  ) {}\n\n  allow(key: string, now: number): boolean {\n    if (this.max < 0) return true;\n    key = limitKey(key);\n    const cut = now - this.window;\n    const prune = () => {\n      for (const [k, ts] of this.seen) if (ts.length === 0 || ts[ts.length - 1] <= cut) this.seen.delete(k);\n      this.pruned = now;\n    };\n    if (now - this.pruned > this.window) prune();\n    if (!this.seen.has(key) && this.seen.size >= this.keys) {\n      prune();\n      if (this.seen.size >= this.keys) return false;\n    }\n    const ts = (this.seen.get(key) ?? []).filter((t) => t > cut);\n    if (ts.length >= this.max) {\n      this.seen.set(key, ts);\n      return false;\n    }\n    ts.push(now);\n    this.seen.set(key, ts);\n    return true;\n  }\n}\n\n/** What an address counts as for the limits: an IPv6 address's /64 (one host usually has a whole /64), anything else as it is. */\nexport function limitKey(addr: string): string {\n  const a = addr.replace(/%.*$/, \"\");\n  if (isIP(a) !== 6 || /^::ffff:\\d+\\.\\d+\\.\\d+\\.\\d+$/i.test(a)) return addr;\n  const groups = expandIPv6(a);\n  return groups ? groups.slice(0, 4).join(\":\") + \"::/64\" : addr;\n}\n\n// expandIPv6 is an IPv6 address's eight groups (a dotted IPv4 tail as two).\nfunction expandIPv6(a: string): string[] | null {\n  let s = a.toLowerCase();\n  const v4 = /(\\d+)\\.(\\d+)\\.(\\d+)\\.(\\d+)$/.exec(s);\n  if (v4) {\n    const b = v4.slice(1).map(Number);\n    s = s.slice(0, v4.index) + ((b[0] << 8) | b[1]).toString(16) + \":\" + ((b[2] << 8) | b[3]).toString(16);\n  }\n  const halves = s.split(\"::\");\n  if (halves.length > 2) return null;\n  const head = halves[0] ? halves[0].split(\":\") : [];\n  const tail = halves.length === 2 && halves[1] ? halves[1].split(\":\") : [];\n  const fill = halves.length === 2 ? 8 - head.length - tail.length : 0;\n  const all = [...head, ...Array(Math.max(fill, 0)).fill(\"0\"), ...tail];\n  if (all.length !== 8) return null;\n  return all.map((g) => parseInt(g, 16).toString(16));\n}\n\n/**\n * The request's client address: with hops trusted proxies in front (each\n * appending to X-Forwarded-For), the entry the outermost one added; entries\n * before it are the client's own claims.\n */\nexport function clientAddr(req: IncomingMessage, hops: number): string {\n  // The first X-Forwarded-For header only, as Go's Header.Get reads it.\n  const distinct = (req as IncomingMessage & { headersDistinct?: Record<string, string[] | undefined> }).headersDistinct?.[\"x-forwarded-for\"];\n  const raw = req.headers[\"x-forwarded-for\"];\n  const f = distinct?.[0] ?? (Array.isArray(raw) ? raw[0] : raw);\n  if (f && hops > 0) {\n    // Only an entry the proxies added: with fewer entries than hops, or one\n    // that isn't an address, the header isn't the proxies' (a request that\n    // reached the app some other way), so it's ignored.\n    const parts = f.split(\",\");\n    if (parts.length >= hops) {\n      const ip = parts[parts.length - hops].trim();\n      if (isIP(ip)) return normalizeAddr(ip);\n    }\n  }\n  return normalizeAddr(req.socket?.remoteAddress ?? \"\");\n}\n\n// normalizeAddr writes an IPv4 address a dual-stack socket reports as\n// ::ffff:a.b.c.d as a.b.c.d, as Go does.\nfunction normalizeAddr(a: string): string {\n  const m = /^::ffff:(\\d+\\.\\d+\\.\\d+\\.\\d+)$/i.exec(a);\n  return m ? m[1] : a;\n}\n"]}

package/dist/retry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/retry.js

@@ -0,0 +1,58 @@
+// Wakeshift runs behind Google's load balancer on Cloud Run. For some
+// minutes after a rollout, the load balancer sends a small share of requests
+// to a retired revision, which answers at once with Google's own HTML "500
+// Server Error" page: the request never reached a Wakeshift instance. It
+// happens to every client alike (new connections included), so retrying is
+// what gets the request through.
+/** @internal Pauses before each retry of a refused request (so at most length + 1 attempts). */
+export const RETRY_PAUSES_MS = [250, 1000];
+/**
+ * @internal fetchFn, retrying a request the load balancer refused before it
+ * reached Wakeshift: Google's HTML 500 page, for any request (it never ran),
+ * and a 502, 503 or 504 not from Wakeshift for a GET or HEAD. Wakeshift's own
+ * errors (JSON) are never retried, nor is a request whose body can't be sent
+ * again (a stream).
+ */
+export function retryRefused(fetchFn, pauses = RETRY_PAUSES_MS) {
+    return (async (input, init) => {
+        const method = (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+        const resendable = !(input instanceof Request) && (init?.body == null || typeof init.body === "string" || init.body instanceof URLSearchParams);
+        for (let attempt = 0;; attempt++) {
+            const resp = await fetchFn(input, init);
+            if (!resendable || attempt >= pauses.length || !(await refused(method, resp)))
+                return resp;
+            await resp.body?.cancel().catch(() => { });
+            await pause(pauses[attempt], init?.signal ?? undefined);
+        }
+    });
+}
+/** @internal Whether resp is the load balancer's refusal, not the service's answer. */
+export async function refused(method, resp) {
+    const type = (resp.headers.get("Content-Type") ?? "").split(";")[0].trim().toLowerCase();
+    if (resp.status === 500) {
+        if (type !== "text/html")
+            return false;
+        const text = await resp.clone().text().catch(() => "");
+        return text.includes("Server Error");
+    }
+    if (resp.status === 502 || resp.status === 503 || resp.status === 504) {
+        return (method === "GET" || method === "HEAD") && type !== "application/json";
+    }
+    return false;
+}
+function pause(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const t = setTimeout(() => {
+            signal?.removeEventListener("abort", stop);
+            resolve();
+        }, ms);
+        const stop = () => {
+            clearTimeout(t);
+            reject(signal.reason);
+        };
+        signal?.addEventListener("abort", stop, { once: true });
+    });
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"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","sourcesContent":["// Wakeshift runs behind Google's load balancer on Cloud Run. For some\n// minutes after a rollout, the load balancer sends a small share of requests\n// to a retired revision, which answers at once with Google's own HTML \"500\n// Server Error\" page: the request never reached a Wakeshift instance. It\n// happens to every client alike (new connections included), so retrying is\n// what gets the request through.\n\n/** @internal Pauses before each retry of a refused request (so at most length + 1 attempts). */\nexport const RETRY_PAUSES_MS = [250, 1000];\n\n/**\n * @internal fetchFn, retrying a request the load balancer refused before it\n * reached Wakeshift: Google's HTML 500 page, for any request (it never ran),\n * and a 502, 503 or 504 not from Wakeshift for a GET or HEAD. Wakeshift's own\n * errors (JSON) are never retried, nor is a request whose body can't be sent\n * again (a stream).\n */\nexport function retryRefused(fetchFn: typeof fetch, pauses: number[] = RETRY_PAUSES_MS): typeof fetch {\n  return (async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {\n    const method = (init?.method ?? (input instanceof Request ? input.method : \"GET\")).toUpperCase();\n    const resendable = !(input instanceof Request) && (init?.body == null || typeof init.body === \"string\" || init.body instanceof URLSearchParams);\n    for (let attempt = 0; ; attempt++) {\n      const resp = await fetchFn(input, init);\n      if (!resendable || attempt >= pauses.length || !(await refused(method, resp))) return resp;\n      await resp.body?.cancel().catch(() => {});\n      await pause(pauses[attempt]!, init?.signal ?? undefined);\n    }\n  }) as typeof fetch;\n}\n\n/** @internal Whether resp is the load balancer's refusal, not the service's answer. */\nexport async function refused(method: string, resp: Response): Promise<boolean> {\n  const type = (resp.headers.get(\"Content-Type\") ?? \"\").split(\";\")[0]!.trim().toLowerCase();\n  if (resp.status === 500) {\n    if (type !== \"text/html\") return false;\n    const text = await resp.clone().text().catch(() => \"\");\n    return text.includes(\"Server Error\");\n  }\n  if (resp.status === 502 || resp.status === 503 || resp.status === 504) {\n    return (method === \"GET\" || method === \"HEAD\") && type !== \"application/json\";\n  }\n  return false;\n}\n\nfunction pause(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise((resolve, reject) => {\n    if (signal?.aborted) return reject(signal.reason);\n    const t = setTimeout(() => {\n      signal?.removeEventListener(\"abort\", stop);\n      resolve();\n    }, ms);\n    const stop = () => {\n      clearTimeout(t);\n      reject(signal!.reason);\n    };\n    signal?.addEventListener(\"abort\", stop, { once: true });\n  });\n}\n"]}

package/dist/sealed.d.ts

@@ -0,0 +1,4 @@
+/** The signed form of v. */
+export declare function seal(key: Buffer, v: unknown): string;
+/** The JSON object s carries, if key signed it; null for anything else. */
+export declare function unseal<T>(key: Buffer, s: unknown): T | null;

package/dist/sealed.js

@@ -0,0 +1,38 @@
+// Signed values: base64url JSON, a ".", and its HMAC-SHA256 under key, so
+// only the app can make one and nobody can change one. Signed, not
+// encrypted: whoever holds one can read it. GuestAuth's clients, codes and
+// tokens use these, each with its own key.
+import { createHmac, timingSafeEqual } from "node:crypto";
+const B64URL_RE = /^[A-Za-z0-9_-]*$/;
+/** The signed form of v. */
+export function seal(key, v) {
+    const p = Buffer.from(JSON.stringify(v)).toString("base64url");
+    return p + "." + createHmac("sha256", key).update(p).digest("base64url");
+}
+/** The JSON object s carries, if key signed it; null for anything else. */
+export function unseal(key, s) {
+    if (typeof s !== "string")
+        return null;
+    const i = s.indexOf(".");
+    if (i < 0)
+        return null;
+    const p = s.slice(0, i);
+    const sig = s.slice(i + 1);
+    if (!B64URL_RE.test(p) || !B64URL_RE.test(sig))
+        return null;
+    const got = Buffer.from(sig, "base64url");
+    // Only the canonical encoding: no second spelling of the same signature.
+    if (got.toString("base64url") !== sig)
+        return null;
+    const want = createHmac("sha256", key).update(p).digest();
+    if (got.length !== want.length || !timingSafeEqual(got, want))
+        return null;
+    try {
+        const v = JSON.parse(Buffer.from(p, "base64url").toString("utf8"));
+        return v !== null && typeof v === "object" && !Array.isArray(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=sealed.js.map

package/dist/sealed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed.js","sourceRoot":"","sources":["../src/sealed.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,mEAAmE;AACnE,2EAA2E;AAC3E,2CAA2C;AAE3C,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,SAAS,GAAG,kBAAkB,CAAC;AAErC,4BAA4B;AAC5B,MAAM,UAAU,IAAI,CAAC,GAAW,EAAE,CAAU;IAC1C,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC/D,OAAO,CAAC,GAAG,GAAG,GAAG,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AAC3E,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,MAAM,CAAI,GAAW,EAAE,CAAU;IAC/C,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACzB,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACxB,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5D,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IAC1C,yEAAyE;IACzE,IAAI,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IACnD,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC1D,IAAI,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3E,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACnE,OAAO,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IACpF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["// Signed values: base64url JSON, a \".\", and its HMAC-SHA256 under key, so\n// only the app can make one and nobody can change one. Signed, not\n// encrypted: whoever holds one can read it. GuestAuth's clients, codes and\n// tokens use these, each with its own key.\n\nimport { createHmac, timingSafeEqual } from \"node:crypto\";\n\nconst B64URL_RE = /^[A-Za-z0-9_-]*$/;\n\n/** The signed form of v. */\nexport function seal(key: Buffer, v: unknown): string {\n  const p = Buffer.from(JSON.stringify(v)).toString(\"base64url\");\n  return p + \".\" + createHmac(\"sha256\", key).update(p).digest(\"base64url\");\n}\n\n/** The JSON object s carries, if key signed it; null for anything else. */\nexport function unseal<T>(key: Buffer, s: unknown): T | null {\n  if (typeof s !== \"string\") return null;\n  const i = s.indexOf(\".\");\n  if (i < 0) return null;\n  const p = s.slice(0, i);\n  const sig = s.slice(i + 1);\n  if (!B64URL_RE.test(p) || !B64URL_RE.test(sig)) return null;\n  const got = Buffer.from(sig, \"base64url\");\n  // Only the canonical encoding: no second spelling of the same signature.\n  if (got.toString(\"base64url\") !== sig) return null;\n  const want = createHmac(\"sha256\", key).update(p).digest();\n  if (got.length !== want.length || !timingSafeEqual(got, want)) return null;\n  try {\n    const v = JSON.parse(Buffer.from(p, \"base64url\").toString(\"utf8\"));\n    return v !== null && typeof v === \"object\" && !Array.isArray(v) ? (v as T) : null;\n  } catch {\n    return null;\n  }\n}\n"]}

package/dist/spec.d.ts

@@ -0,0 +1,28 @@
+/** The draft these follow. */
+export declare const REVISION = "SEP-3415 (2026-10-16)";
+/** Capability keys: the draft's extension, and the top-level key ChatGPT reads. A server advertises both. */
+export declare const EXTENSION_KEY = "io.modelcontextprotocol/events";
+export declare const LEGACY_KEY = "events";
+/** On every events/* result. */
+export declare const RESULT_TYPE = "complete";
+/** The _meta key of an occurrence's rendered line (Wakeshift adds it on delivery). */
+export declare const TEXT_META = "ai.wakeshift/text";
+/** The Streamable HTTP header events/subscribe and events/unsubscribe carry: params.name. */
+export declare const NAME_HEADER = "mcp-name";
+export type Dialect = "draft" | "chatgpt";
+export interface Codes {
+    notFound: number;
+    forbidden: number;
+    resourceExhausted: number;
+    unsupported: number;
+    callbackEndpoint: number;
+}
+export declare const INVALID_PARAMS = -32602;
+export declare const HEADER_MISMATCH = -32020;
+export declare const INTERNAL_ERROR = -32603;
+/** A dialect's error codes: the draft's (provisional) or ChatGPT's. */
+export declare function codesFor(dialect: Dialect): Codes;
+/** A client's dialect, by its clientInfo name or User-Agent: ChatGPT's MCP client is openai-mcp. */
+export declare function dialectOf(clientName: string, userAgent: string): Dialect;
+/** Decodes an Mcp-Name header: plain ASCII, or SEP-2243's base64 sentinel (=?base64?…?=). null: a sentinel that doesn't decode. */
+export declare function headerValue(h: string): string | null;

package/dist/spec.js

@@ -0,0 +1,43 @@
+// The SEP-3415 (MCP Events) constants the SDK uses, in one place, matching
+// Wakeshift's own (internal/mcpevents/event/spec.go, which a test checks
+// these against): the draft is still moving.
+/** The draft these follow. */
+export const REVISION = "SEP-3415 (2026-10-16)";
+/** Capability keys: the draft's extension, and the top-level key ChatGPT reads. A server advertises both. */
+export const EXTENSION_KEY = "io.modelcontextprotocol/events";
+export const LEGACY_KEY = "events";
+/** On every events/* result. */
+export const RESULT_TYPE = "complete";
+/** The _meta key of an occurrence's rendered line (Wakeshift adds it on delivery). */
+export const TEXT_META = "ai.wakeshift/text";
+/** The Streamable HTTP header events/subscribe and events/unsubscribe carry: params.name. */
+export const NAME_HEADER = "mcp-name";
+export const INVALID_PARAMS = -32602;
+export const HEADER_MISMATCH = -32020;
+export const INTERNAL_ERROR = -32603;
+/** A dialect's error codes: the draft's (provisional) or ChatGPT's. */
+export function codesFor(dialect) {
+    if (dialect === "chatgpt") {
+        return { notFound: -32011, forbidden: -32012, resourceExhausted: INVALID_PARAMS, unsupported: INVALID_PARAMS, callbackEndpoint: -32015 };
+    }
+    return { notFound: -32023, forbidden: -32024, resourceExhausted: -32025, unsupported: -32026, callbackEndpoint: -32027 };
+}
+/** A client's dialect, by its clientInfo name or User-Agent: ChatGPT's MCP client is openai-mcp. */
+export function dialectOf(clientName, userAgent) {
+    return clientName.toLowerCase() === "openai-mcp" || userAgent.toLowerCase().startsWith("openai-mcp") ? "chatgpt" : "draft";
+}
+/** Decodes an Mcp-Name header: plain ASCII, or SEP-2243's base64 sentinel (=?base64?…?=). null: a sentinel that doesn't decode. */
+export function headerValue(h) {
+    if (!h.startsWith("=?base64?") || !h.endsWith("?="))
+        return h;
+    try {
+        const b = Buffer.from(h.slice("=?base64?".length, -2), "base64");
+        if (b.toString("base64").replace(/=+$/, "") !== h.slice("=?base64?".length, -2).replace(/=+$/, ""))
+            return null;
+        return b.toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=spec.js.map