@helyx/bot 1.1.0 → 1.2.0

package/dist/ecko-evidence-receiver.d.ts

@@ -0,0 +1,32 @@
+import { type ViolationEvidenceReference } from "@helyx/sdk";
+import type { TransientViolationEvidenceStore } from "./transient-violation-evidence.js";
+export declare const ECKO_EVIDENCE_METHOD = "POST";
+export declare const ECKO_EVIDENCE_PATH = "/v1/automod/enhanced/evidence";
+export type EckoEvidenceAcceptance = {
+    outcome: "accepted";
+    evidenceReference: ViolationEvidenceReference;
+} | {
+    outcome: "rejected";
+    code: "invalid_envelope" | "unknown_version" | "signature_invalid" | "stale" | "replay" | "capacity_exceeded";
+};
+/**
+ * Bot-private receiver for the Hosted evidence transport. The HTTP adapter must
+ * pass the exact received bytes; authentication is over those bytes, not a
+ * parsed/re-serialized object. This receiver is not registered in ServiceAccess.
+ */
+export declare class EckoEvidenceReceiver {
+    #private;
+    private readonly evidenceStore;
+    private readonly environment;
+    private readonly now;
+    private readonly maximumAuthenticatedEnvelopesPerSecond;
+    constructor(evidenceStore: TransientViolationEvidenceStore, environment: string, hmacKey: Uint8Array, now?: () => number, maximumAuthenticatedEnvelopesPerSecond?: number);
+    accept(input: {
+        rawBody: Uint8Array;
+        signature: string;
+    }): EckoEvidenceAcceptance;
+    /** Used only after the enclosing Ecko transport request is authenticated. */
+    acceptAuthenticated(rawBody: Uint8Array): EckoEvidenceAcceptance;
+}
+export declare function signEckoEvidenceBody(rawBody: Uint8Array, hmacKey: Uint8Array): string;
+//# sourceMappingURL=ecko-evidence-receiver.d.ts.map

package/dist/ecko-evidence-receiver.js

@@ -0,0 +1,173 @@
+import { AUTOMOD_ENHANCED_CONTRACT_VERSION, AUTOMOD_ENHANCED_EVIDENCE_PROTOCOL, AUTOMOD_ENHANCED_PROVIDER_ID, AUTOMOD_SCANNER_LIMITS, } from "@helyx/sdk";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { z } from "zod";
+const SNOWFLAKE = z.string().regex(/^\d{17,20}$/u);
+const evidenceEnvelopeSchema = z
+    .object({
+    protocol: z.literal(AUTOMOD_ENHANCED_EVIDENCE_PROTOCOL),
+    providerId: z.literal(AUTOMOD_ENHANCED_PROVIDER_ID),
+    contractVersion: z.literal(AUTOMOD_ENHANCED_CONTRACT_VERSION),
+    operationId: z.string().regex(/^[a-f0-9]{64}$/u),
+    nonce: z.string().regex(/^[A-Za-z0-9_-]{32,128}$/u),
+    issuedAt: z.iso.datetime({ offset: true }),
+    deadlineAt: z.iso.datetime({ offset: true }),
+    environment: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/u),
+    guildId: SNOWFLAKE,
+    channelId: SNOWFLAKE,
+    messageId: SNOWFLAKE,
+    authorUserId: SNOWFLAKE,
+    configurationRevision: z
+        .string()
+        .min(1)
+        .max(160)
+        .refine((value) => !/[\r\n]/u.test(value)),
+    content: z.string().min(1).max(AUTOMOD_SCANNER_LIMITS.messageCharacters),
+})
+    .strict();
+const MAX_REPLAY_ENTRIES = 20_000;
+const MAX_AUTHENTICATED_ENVELOPES_PER_SECOND = 500;
+export const ECKO_EVIDENCE_METHOD = "POST";
+export const ECKO_EVIDENCE_PATH = "/v1/automod/enhanced/evidence";
+/**
+ * Bot-private receiver for the Hosted evidence transport. The HTTP adapter must
+ * pass the exact received bytes; authentication is over those bytes, not a
+ * parsed/re-serialized object. This receiver is not registered in ServiceAccess.
+ */
+export class EckoEvidenceReceiver {
+    evidenceStore;
+    environment;
+    now;
+    maximumAuthenticatedEnvelopesPerSecond;
+    #replayEntries = new Map();
+    #key;
+    #rateWindowStartedAt = Number.NEGATIVE_INFINITY;
+    #rateWindowCount = 0;
+    constructor(evidenceStore, environment, hmacKey, now = Date.now, maximumAuthenticatedEnvelopesPerSecond = MAX_AUTHENTICATED_ENVELOPES_PER_SECOND) {
+        this.evidenceStore = evidenceStore;
+        this.environment = environment;
+        this.now = now;
+        this.maximumAuthenticatedEnvelopesPerSecond = maximumAuthenticatedEnvelopesPerSecond;
+        this.#key = Buffer.from(hmacKey);
+        if (this.#key.byteLength < 32)
+            throw new RangeError("Ecko evidence HMAC key must contain 32 bytes");
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/u.test(environment))
+            throw new Error("Ecko evidence environment is invalid");
+        if (!Number.isSafeInteger(maximumAuthenticatedEnvelopesPerSecond) ||
+            maximumAuthenticatedEnvelopesPerSecond < 1 ||
+            maximumAuthenticatedEnvelopesPerSecond >
+                MAX_AUTHENTICATED_ENVELOPES_PER_SECOND)
+            throw new RangeError("Ecko evidence ingress limit is invalid");
+    }
+    accept(input) {
+        const body = Buffer.from(input.rawBody);
+        if (body.byteLength < 1 ||
+            body.byteLength > AUTOMOD_SCANNER_LIMITS.evidenceBytes)
+            return rejected("invalid_envelope");
+        if (!verifySignature(body, input.signature, this.#key))
+            return rejected("signature_invalid");
+        return this.#acceptAuthenticatedBody(body);
+    }
+    /** Used only after the enclosing Ecko transport request is authenticated. */
+    acceptAuthenticated(rawBody) {
+        const body = Buffer.from(rawBody);
+        if (body.byteLength < 1 ||
+            body.byteLength > AUTOMOD_SCANNER_LIMITS.evidenceBytes)
+            return rejected("invalid_envelope");
+        return this.#acceptAuthenticatedBody(body);
+    }
+    #acceptAuthenticatedBody(body) {
+        let decoded;
+        try {
+            decoded = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(body));
+        }
+        catch {
+            return rejected("invalid_envelope");
+        }
+        const parsed = evidenceEnvelopeSchema.safeParse(decoded);
+        if (!parsed.success)
+            return rejected(hasUnknownProtocolIdentity(decoded)
+                ? "unknown_version"
+                : "invalid_envelope");
+        const envelope = parsed.data;
+        if (envelope.environment !== this.environment)
+            return rejected("invalid_envelope");
+        if (Buffer.byteLength(envelope.content, "utf8") >
+            AUTOMOD_SCANNER_LIMITS.messageUtf8Bytes)
+            return rejected("invalid_envelope");
+        const issuedAt = Date.parse(envelope.issuedAt);
+        const deadlineAt = Date.parse(envelope.deadlineAt);
+        const now = this.now();
+        if (deadlineAt <= issuedAt ||
+            deadlineAt - issuedAt >
+                AUTOMOD_SCANNER_LIMITS.evidenceDeadlineSeconds * 1_000 ||
+            issuedAt > now + AUTOMOD_SCANNER_LIMITS.clockSkewSeconds * 1_000 ||
+            deadlineAt < now)
+            return rejected("stale");
+        if (!this.#acceptWithinRateLimit(now))
+            return rejected("capacity_exceeded");
+        this.#prune(now);
+        const nonceKey = `nonce:${envelope.nonce}`;
+        const operationKey = `operation:${envelope.operationId}`;
+        if (this.#replayEntries.has(nonceKey) ||
+            this.#replayEntries.has(operationKey))
+            return rejected("replay");
+        if (this.#replayEntries.size + 2 > MAX_REPLAY_ENTRIES)
+            return rejected("capacity_exceeded");
+        const evidenceReference = this.evidenceStore.capture({
+            source: "enhanced_scanner",
+            sourceEventId: envelope.operationId,
+            configurationRevision: envelope.configurationRevision,
+            guildId: envelope.guildId,
+            channelId: envelope.channelId,
+            messageId: envelope.messageId,
+            authorUserId: envelope.authorUserId,
+            content: envelope.content,
+        });
+        if (!evidenceReference)
+            return rejected("capacity_exceeded");
+        this.#replayEntries.set(nonceKey, deadlineAt);
+        this.#replayEntries.set(operationKey, deadlineAt);
+        return { outcome: "accepted", evidenceReference };
+    }
+    #prune(now) {
+        for (const [key, expiresAt] of this.#replayEntries)
+            if (expiresAt < now)
+                this.#replayEntries.delete(key);
+    }
+    #acceptWithinRateLimit(now) {
+        if (now - this.#rateWindowStartedAt >= 1_000) {
+            this.#rateWindowStartedAt = now;
+            this.#rateWindowCount = 0;
+        }
+        if (this.#rateWindowCount >= this.maximumAuthenticatedEnvelopesPerSecond)
+            return false;
+        this.#rateWindowCount += 1;
+        return true;
+    }
+}
+function hasUnknownProtocolIdentity(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return (record.protocol !== AUTOMOD_ENHANCED_EVIDENCE_PROTOCOL ||
+        record.providerId !== AUTOMOD_ENHANCED_PROVIDER_ID ||
+        record.contractVersion !== AUTOMOD_ENHANCED_CONTRACT_VERSION);
+}
+export function signEckoEvidenceBody(rawBody, hmacKey) {
+    return createHmac("sha256", hmacKey)
+        .update(`${ECKO_EVIDENCE_METHOD}\n${ECKO_EVIDENCE_PATH}\n`, "utf8")
+        .update(rawBody)
+        .digest("hex");
+}
+function verifySignature(body, signature, key) {
+    if (!/^[a-f0-9]{64}$/u.test(signature))
+        return false;
+    const expected = Buffer.from(signEckoEvidenceBody(body, key), "hex");
+    const actual = Buffer.from(signature, "hex");
+    return (actual.byteLength === expected.byteLength &&
+        timingSafeEqual(actual, expected));
+}
+function rejected(code) {
+    return { outcome: "rejected", code };
+}
+//# sourceMappingURL=ecko-evidence-receiver.js.map

package/dist/ecko-transport-auth.d.ts

@@ -0,0 +1,19 @@
+export type EckoTransportAuthentication = {
+    authenticated: true;
+} | {
+    authenticated: false;
+    code: "invalid" | "stale" | "replay" | "capacity";
+};
+export declare class EckoTransportAuthenticator {
+    #private;
+    private readonly environment;
+    private readonly now;
+    constructor(environment: string, secrets: readonly string[], now?: () => number);
+    authenticate(input: {
+        method: string;
+        path: string;
+        body: Uint8Array;
+        headers: Readonly<Record<string, string | string[] | undefined>>;
+    }): EckoTransportAuthentication;
+}
+//# sourceMappingURL=ecko-transport-auth.d.ts.map

package/dist/ecko-transport-auth.js

@@ -0,0 +1,80 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+const MAX_REPLAY_ENTRIES = 250_000;
+const REPLAY_WINDOW_MS = 2 * 60 * 1_000;
+export class EckoTransportAuthenticator {
+    environment;
+    now;
+    #keys;
+    #replay = new Map();
+    constructor(environment, secrets, now = Date.now) {
+        this.environment = environment;
+        this.now = now;
+        this.#keys = secrets.map((secret) => Buffer.from(secret, "base64"));
+        if (this.#keys.length < 1 ||
+            this.#keys.length > 2 ||
+            this.#keys.some((key) => key.byteLength !== 32))
+            throw new Error("Ecko transport requires one or two 32-byte keys");
+    }
+    authenticate(input) {
+        const version = one(input.headers["x-helyx-ecko-version"]);
+        const environment = one(input.headers["x-helyx-ecko-environment"]);
+        const timestamp = one(input.headers["x-helyx-ecko-timestamp"]);
+        const deadline = one(input.headers["x-helyx-ecko-deadline"]);
+        const nonce = one(input.headers["x-helyx-ecko-nonce"]);
+        const signature = one(input.headers["x-helyx-ecko-signature"]);
+        if (version !== "1" ||
+            environment !== this.environment ||
+            !timestamp ||
+            !/^\d{10}$/u.test(timestamp) ||
+            !deadline ||
+            !/^\d{10}$/u.test(deadline) ||
+            !nonce ||
+            !/^[A-Za-z0-9_-]{32,128}$/u.test(nonce) ||
+            !signature ||
+            !/^[a-f0-9]{64}$/u.test(signature))
+            return { authenticated: false, code: "invalid" };
+        const now = this.now();
+        const issuedAt = Number(timestamp) * 1_000;
+        const deadlineAt = Number(deadline) * 1_000;
+        if (issuedAt > now + 30_000 ||
+            deadlineAt < now ||
+            deadlineAt <= issuedAt ||
+            deadlineAt - issuedAt > 30_000)
+            return { authenticated: false, code: "stale" };
+        const digest = createHash("sha256").update(input.body).digest("hex");
+        const canonical = [
+            version,
+            input.method.toUpperCase(),
+            input.path,
+            environment,
+            timestamp,
+            deadline,
+            nonce,
+            digest,
+        ].join("\n");
+        const supplied = Buffer.from(signature, "hex");
+        const valid = this.#keys.some((key) => {
+            const expected = createHmac("sha256", key).update(canonical).digest();
+            return (supplied.byteLength === expected.byteLength &&
+                timingSafeEqual(supplied, expected));
+        });
+        if (!valid)
+            return { authenticated: false, code: "invalid" };
+        this.#prune(now);
+        if (this.#replay.has(nonce))
+            return { authenticated: false, code: "replay" };
+        if (this.#replay.size >= MAX_REPLAY_ENTRIES)
+            return { authenticated: false, code: "capacity" };
+        this.#replay.set(nonce, Math.min(deadlineAt + REPLAY_WINDOW_MS, now + REPLAY_WINDOW_MS));
+        return { authenticated: true };
+    }
+    #prune(now) {
+        for (const [nonce, expiresAt] of this.#replay)
+            if (expiresAt < now)
+                this.#replay.delete(nonce);
+    }
+}
+function one(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+//# sourceMappingURL=ecko-transport-auth.js.map

package/dist/ecko-transport-routes.d.ts

@@ -0,0 +1,19 @@
+import { type AutoModerationScannerProviderRegistryService } from "@helyx/sdk";
+import type { FastifyInstance } from "fastify";
+import type { EckoEvidenceReceiver } from "./ecko-evidence-receiver.js";
+import type { EckoTransportAuthenticator } from "./ecko-transport-auth.js";
+export interface EckoTelemetrySink {
+    accept(input: unknown): Promise<boolean>;
+}
+export declare function registerEckoTransportRoutes(server: FastifyInstance, input: {
+    authenticator: EckoTransportAuthenticator;
+    registry: AutoModerationScannerProviderRegistryService;
+    evidence: EckoEvidenceReceiver;
+    gateState(): Promise<{
+        state: "enabled" | "draining" | "disabled";
+        updatedAt: Date;
+    }>;
+    telemetry?: EckoTelemetrySink;
+    now?: () => number;
+}): void;
+//# sourceMappingURL=ecko-transport-routes.d.ts.map

package/dist/ecko-transport-routes.js

@@ -0,0 +1,130 @@
+import { AUTOMOD_ENHANCED_CONTRACT_VERSION, AUTOMOD_ENHANCED_PROVIDER_ID, AUTOMOD_SCANNER_LIMITS, } from "@helyx/sdk";
+import { z } from "zod";
+export function registerEckoTransportRoutes(server, input) {
+    const pending = new Map();
+    const now = input.now ?? Date.now;
+    server.get("/v1/ecko/configurations", async (request, reply) => {
+        if (!authenticate(request, reply, input.authenticator, new Uint8Array()))
+            return;
+        if ((await input.gateState()).state !== "enabled")
+            return reply.code(503).send({ code: "gate_disabled" });
+        const query = z
+            .object({
+            cursor: z.string().min(1).max(2_048).optional(),
+            limit: z.coerce
+                .number()
+                .int()
+                .min(1)
+                .max(AUTOMOD_SCANNER_LIMITS.configurationPageServers),
+            knownFingerprint: z.string().min(1).max(128).optional(),
+        })
+            .strict()
+            .parse(request.query);
+        return input.registry.getConfigurationPage({
+            adapter: "hosted_ecko",
+            providerId: AUTOMOD_ENHANCED_PROVIDER_ID,
+            contractVersion: AUTOMOD_ENHANCED_CONTRACT_VERSION,
+            limit: query.limit,
+            ...(query.cursor ? { cursor: query.cursor } : {}),
+            ...(query.knownFingerprint
+                ? { knownFingerprint: query.knownFingerprint }
+                : {}),
+        });
+    });
+    server.post("/v1/ecko/evidence", { config: { rawBody: true } }, async (request, reply) => {
+        const body = rawBody(request.body);
+        if (!authenticate(request, reply, input.authenticator, body))
+            return;
+        prunePending(pending, now());
+        const accepted = input.evidence.acceptAuthenticated(body);
+        if (accepted.outcome !== "accepted")
+            return reply.code(422).send(accepted);
+        pending.set(accepted.evidenceReference.sourceEventId, {
+            reference: accepted.evidenceReference,
+            expiresAt: now() + AUTOMOD_SCANNER_LIMITS.evidenceDeadlineSeconds * 1_000,
+        });
+        return reply.code(202).send({ outcome: "accepted" });
+    });
+    server.post("/v1/ecko/results", { config: { rawBody: true } }, async (request, reply) => {
+        const body = rawBody(request.body);
+        if (!authenticate(request, reply, input.authenticator, body))
+            return;
+        if (body.byteLength > AUTOMOD_SCANNER_LIMITS.resultBytes)
+            return reply
+                .code(413)
+                .send({ outcome: "rejected", code: "invalid_envelope" });
+        const decoded = parseJson(body);
+        const gate = await input.gateState();
+        if (!gateAllowsResult(gate, decoded))
+            return reply
+                .code(503)
+                .send({ outcome: "rejected", code: "module_unavailable" });
+        const operationId = operationIdFrom(decoded);
+        prunePending(pending, now());
+        const evidence = operationId ? pending.get(operationId) : undefined;
+        if (operationId)
+            pending.delete(operationId);
+        return input.registry.acceptResult({
+            adapter: "hosted_ecko",
+            providerId: AUTOMOD_ENHANCED_PROVIDER_ID,
+            contractVersion: AUTOMOD_ENHANCED_CONTRACT_VERSION,
+            result: decoded,
+            ...(evidence ? { evidenceReference: evidence.reference } : {}),
+        });
+    });
+    server.post("/v1/ecko/telemetry", { config: { rawBody: true } }, async (request, reply) => {
+        const body = rawBody(request.body);
+        if (!authenticate(request, reply, input.authenticator, body))
+            return;
+        if (!input.telemetry)
+            return reply.code(503).send({ accepted: false });
+        const accepted = await input.telemetry.accept(parseJson(body));
+        return reply.code(accepted ? 202 : 409).send({ accepted });
+    });
+}
+function gateAllowsResult(gate, result) {
+    if (gate.state === "enabled")
+        return true;
+    if (gate.state === "disabled" || !result || typeof result !== "object")
+        return false;
+    const issuedAt = result["issuedAt"];
+    return (typeof issuedAt === "string" &&
+        Number.isFinite(Date.parse(issuedAt)) &&
+        Date.parse(issuedAt) <= gate.updatedAt.getTime());
+}
+function authenticate(request, reply, authenticator, body) {
+    const result = authenticator.authenticate({
+        method: request.method,
+        path: request.url,
+        headers: request.headers,
+        body,
+    });
+    if (result.authenticated)
+        return true;
+    reply
+        .code(result.code === "capacity" ? 429 : 401)
+        .send({ message: "Ecko transport authentication failed" });
+    return false;
+}
+function rawBody(value) {
+    if (value instanceof Uint8Array)
+        return value;
+    return Buffer.from(JSON.stringify(value ?? null));
+}
+function parseJson(body) {
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(body));
+}
+function operationIdFrom(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const operationId = value["operationId"];
+    return typeof operationId === "string" && /^[a-f0-9]{64}$/u.test(operationId)
+        ? operationId
+        : undefined;
+}
+function prunePending(pending, now) {
+    for (const [operationId, evidence] of pending)
+        if (evidence.expiresAt <= now)
+            pending.delete(operationId);
+}
+//# sourceMappingURL=ecko-transport-routes.js.map

package/dist/embedded-auto-moderation-pool.d.ts

@@ -0,0 +1,46 @@
+import type { CompiledEnhancedConfiguration, EnhancedScanResult } from "@helyx/module-automod/engine";
+import type { EmbeddedWorkerObservation, EmbeddedWorkerRequest } from "./embedded-auto-moderation-worker-runtime.js";
+interface WorkerLike {
+    postMessage(value: EmbeddedWorkerRequest): void;
+    terminate(): Promise<number>;
+    on(event: "message", listener: (value: unknown) => void): this;
+    on(event: "error", listener: (error: Error) => void): this;
+    on(event: "exit", listener: (code: number) => void): this;
+}
+export interface EmbeddedScannerPoolLimits {
+    workers: number;
+    maximumItems: number;
+    maximumBytes: number;
+    maximumItemsPerGuild: number;
+}
+export interface EmbeddedScannerPoolSnapshot {
+    status: "idle" | "ready" | "degraded" | "circuit_open" | "stopped";
+    workers: number;
+    configuredGuilds: number;
+    queuedItems: number;
+    queuedBytes: number;
+    activeItems: number;
+    overflow: number;
+    expired: number;
+    workerFailures: number;
+}
+export declare class EmbeddedAutoModerationPool {
+    #private;
+    private readonly limits;
+    constructor(limits: EmbeddedScannerPoolLimits, options?: {
+        workerFactory?: () => WorkerLike;
+        workerUrl?: URL;
+        now?: () => number;
+    });
+    private readonly now;
+    replaceConfigurations(configurations: readonly CompiledEnhancedConfiguration[]): void;
+    submit(input: {
+        observation: EmbeddedWorkerObservation;
+        deadlineAt: number;
+        complete: (result: EnhancedScanResult | null) => Promise<void>;
+    }): boolean;
+    snapshot(): EmbeddedScannerPoolSnapshot;
+    stop(timeoutMs?: number): Promise<boolean>;
+}
+export {};
+//# sourceMappingURL=embedded-auto-moderation-pool.d.ts.map