@fonoster/common 0.27.0 → 0.30.0

package/dist/webhooks/prisma.d.ts

@@ -0,0 +1,55 @@
+import { Delivery, WebhookEndpoint, WebhookStore } from "./Dispatcher";
+type PrismaLike = any;
+export type PrismaWebhookStoreOptions = {
+    /**
+     * Take over pending deliveries this long overdue (their owner died or stalled). Off by default;
+     * turn it on in processes that run `runDue()` on a timer. Default 60 s when set to true.
+     */
+    adoptOverdue?: boolean | number;
+    now?: () => number;
+};
+export declare class PrismaWebhookStore implements WebhookStore {
+    private readonly prisma;
+    private readonly options;
+    private e;
+    private d;
+    private readonly writes;
+    private constructor();
+    static open(prisma: PrismaLike, options?: PrismaWebhookStoreOptions): Promise<PrismaWebhookStore>;
+    private now;
+    /**
+     * Reloads endpoints, forgets settled deliveries (they stay in the log) and, with
+     * `adoptOverdue`, claims pending deliveries whose owner stopped retrying them.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Reloads one workspace's endpoints now. The fan-out calls it for each event, so an endpoint
+     * created, changed or deleted a moment ago through another replica counts at once instead of
+     * after the next `refresh()` (ST-2).
+     */
+    refreshEndpoints(workspaceRef: string): Promise<void>;
+    endpoints(workspaceRef?: string): WebhookEndpoint[];
+    putEndpoint(x: WebhookEndpoint): void;
+    deleteEndpoint(id: string): void;
+    /** Deliveries this process knows: the ones it created, adopted or loaded. */
+    deliveries(endpointId?: string): Delivery[];
+    /**
+     * Stores new deliveries before returning (the fan-out acknowledges the bus message only then).
+     * Returns the ones it stored; a delivery that already exists (the same event fanned out again)
+     * is left as it is, and whoever owns it keeps it (ST-2).
+     */
+    insertDeliveries(xs: Delivery[]): Promise<Delivery[]>;
+    putDelivery(x: Delivery): void;
+    /**
+     * The delivery log, newest first (W6). Loaded deliveries become known to this store, so
+     * `WebhookDispatcher.resend` can find them.
+     */
+    loadDeliveries(filter?: {
+        endpointId?: string;
+        workspaceRef?: string;
+        id?: string;
+    }, limit?: number): Promise<Delivery[]>;
+    /** Waits for every queued write; throws the first failure. */
+    flush(): Promise<void>;
+}
+export {};

package/dist/webhooks/prisma.js

@@ -0,0 +1,242 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrismaWebhookStore = void 0;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const WriteBehind_1 = require("../utils/WriteBehind");
+const ms = (d) => (d ? d.getTime() : undefined);
+const date = (n) => (n === undefined ? null : new Date(n));
+function toEndpoint(r) {
+    const e = {
+        id: r.ref,
+        workspaceRef: r.accessKeyId,
+        url: r.url,
+        events: r.events,
+        secret: r.secret
+    };
+    if (r.previousSecret) {
+        e.previousSecret = r.previousSecret;
+        e.previousUntil = ms(r.previousUntil);
+    }
+    return e;
+}
+function toDelivery(r) {
+    const d = {
+        id: r.ref,
+        endpointId: r.endpointRef,
+        event: r.event,
+        status: r.status,
+        attempts: r.attempts,
+        nextAttemptAt: ms(r.nextAttemptAt)
+    };
+    if (r.firstAttemptAt)
+        d.firstAttemptAt = ms(r.firstAttemptAt);
+    if (r.lastAttemptAt)
+        d.lastAttemptAt = ms(r.lastAttemptAt);
+    if (r.lastStatus !== null && r.lastStatus !== undefined)
+        d.lastStatus = r.lastStatus;
+    return d;
+}
+/** A delivery's columns (without its ref). */
+function deliveryData(x) {
+    var _a;
+    return {
+        endpointRef: x.endpointId,
+        accessKeyId: x.event.workspaceRef,
+        eventId: x.event.id,
+        eventType: x.event.type,
+        event: x.event,
+        status: x.status,
+        attempts: x.attempts,
+        firstAttemptAt: date(x.firstAttemptAt),
+        lastAttemptAt: date(x.lastAttemptAt),
+        lastStatus: (_a = x.lastStatus) !== null && _a !== void 0 ? _a : null,
+        nextAttemptAt: new Date(x.nextAttemptAt)
+    };
+}
+class PrismaWebhookStore {
+    constructor(prisma, options) {
+        this.prisma = prisma;
+        this.options = options;
+        this.e = new Map();
+        this.d = new Map();
+        this.writes = new WriteBehind_1.WriteBehind();
+    }
+    static open(prisma_1) {
+        return __awaiter(this, arguments, void 0, function* (prisma, options = {}) {
+            const store = new PrismaWebhookStore(prisma, options);
+            yield store.refresh();
+            return store;
+        });
+    }
+    now() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.options).now) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : Date.now();
+    }
+    /**
+     * Reloads endpoints, forgets settled deliveries (they stay in the log) and, with
+     * `adoptOverdue`, claims pending deliveries whose owner stopped retrying them.
+     */
+    refresh() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.writes.flush();
+            const rows = yield this.prisma.webhookEndpoint.findMany();
+            this.e = new Map(rows.map((r) => [r.ref, toEndpoint(r)]));
+            for (const [id, d] of this.d)
+                if (d.status !== "pending")
+                    this.d.delete(id);
+            const adopt = this.options.adoptOverdue;
+            if (!adopt)
+                return;
+            const after = adopt === true ? 60000 : adopt;
+            const overdue = yield this.prisma.webhookDelivery.findMany({
+                where: {
+                    status: "pending",
+                    nextAttemptAt: { lt: new Date(this.now() - after) }
+                },
+                take: 500
+            });
+            for (const r of overdue) {
+                if (this.d.has(r.ref))
+                    continue;
+                // Claim it: only one process moves nextAttemptAt from the value it read.
+                const { count } = yield this.prisma.webhookDelivery.updateMany({
+                    where: { ref: r.ref, nextAttemptAt: r.nextAttemptAt },
+                    data: { nextAttemptAt: new Date(this.now()) }
+                });
+                if (count === 1)
+                    this.d.set(r.ref, Object.assign(Object.assign({}, toDelivery(r)), { nextAttemptAt: this.now() }));
+            }
+        });
+    }
+    /**
+     * Reloads one workspace's endpoints now. The fan-out calls it for each event, so an endpoint
+     * created, changed or deleted a moment ago through another replica counts at once instead of
+     * after the next `refresh()` (ST-2).
+     */
+    refreshEndpoints(workspaceRef) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.writes.flush();
+            const rows = yield this.prisma.webhookEndpoint.findMany({
+                where: { accessKeyId: workspaceRef }
+            });
+            for (const [id, e] of this.e)
+                if (e.workspaceRef === workspaceRef)
+                    this.e.delete(id);
+            for (const r of rows)
+                this.e.set(r.ref, toEndpoint(r));
+        });
+    }
+    endpoints(workspaceRef) {
+        return [...this.e.values()].filter((x) => !workspaceRef || x.workspaceRef === workspaceRef);
+    }
+    putEndpoint(x) {
+        var _a;
+        this.e.set(x.id, x);
+        const data = {
+            accessKeyId: x.workspaceRef,
+            url: x.url,
+            events: x.events,
+            secret: x.secret,
+            previousSecret: (_a = x.previousSecret) !== null && _a !== void 0 ? _a : null,
+            previousUntil: date(x.previousUntil)
+        };
+        this.writes.push(() => this.prisma.webhookEndpoint.upsert({
+            where: { ref: x.id },
+            create: Object.assign({ ref: x.id }, data),
+            update: data
+        }));
+    }
+    deleteEndpoint(id) {
+        this.e.delete(id);
+        this.writes.push(() => this.prisma.webhookEndpoint.deleteMany({ where: { ref: id } }));
+    }
+    /** Deliveries this process knows: the ones it created, adopted or loaded. */
+    deliveries(endpointId) {
+        return [...this.d.values()].filter((x) => !endpointId || x.endpointId === endpointId);
+    }
+    /**
+     * Stores new deliveries before returning (the fan-out acknowledges the bus message only then).
+     * Returns the ones it stored; a delivery that already exists (the same event fanned out again)
+     * is left as it is, and whoever owns it keeps it (ST-2).
+     */
+    insertDeliveries(xs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.writes.flush();
+            const created = [];
+            for (const x of xs) {
+                try {
+                    yield this.prisma.webhookDelivery.create({
+                        data: Object.assign({ ref: x.id }, deliveryData(x))
+                    });
+                }
+                catch (e) {
+                    if (e.code === "P2002")
+                        continue;
+                    throw e;
+                }
+                this.d.set(x.id, x);
+                created.push(x);
+            }
+            return created;
+        });
+    }
+    putDelivery(x) {
+        this.d.set(x.id, x);
+        const data = deliveryData(x);
+        this.writes.push(() => this.prisma.webhookDelivery.upsert({
+            where: { ref: x.id },
+            create: Object.assign({ ref: x.id }, data),
+            update: data
+        }));
+    }
+    /**
+     * The delivery log, newest first (W6). Loaded deliveries become known to this store, so
+     * `WebhookDispatcher.resend` can find them.
+     */
+    loadDeliveries() {
+        return __awaiter(this, arguments, void 0, function* (filter = {}, limit = 100) {
+            yield this.writes.flush();
+            const rows = yield this.prisma.webhookDelivery.findMany({
+                where: Object.assign(Object.assign(Object.assign({}, (filter.id ? { ref: filter.id } : {})), (filter.endpointId ? { endpointRef: filter.endpointId } : {})), (filter.workspaceRef ? { accessKeyId: filter.workspaceRef } : {})),
+                orderBy: { createdAt: "desc" },
+                take: limit
+            });
+            const out = rows.map(toDelivery);
+            for (const d of out)
+                if (!this.d.has(d.id))
+                    this.d.set(d.id, d);
+            return out;
+        });
+    }
+    /** Waits for every queued write; throws the first failure. */
+    flush() {
+        return this.writes.flush();
+    }
+}
+exports.PrismaWebhookStore = PrismaWebhookStore;

package/dist/webhooks/signing.d.ts

@@ -0,0 +1,8 @@
+export declare const WEBHOOK_SIGNATURE_HEADER = "X-Fonoster-Signature";
+export declare const WEBHOOK_TIMESTAMP_HEADER = "X-Fonoster-Timestamp";
+export declare function webhookHeaders(body: string, secrets: string[], nowSeconds?: number): {
+    "X-Fonoster-Timestamp": string;
+    "X-Fonoster-Signature": string;
+};
+/** For receivers: true when one of the signatures matches and the timestamp is fresh (±300 s). */
+export declare function verifyWebhook(body: string, headers: Record<string, string | string[] | undefined>, secret: string, nowSeconds?: number): boolean;

package/dist/webhooks/signing.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOK_TIMESTAMP_HEADER = exports.WEBHOOK_SIGNATURE_HEADER = void 0;
+exports.webhookHeaders = webhookHeaders;
+exports.verifyWebhook = verifyWebhook;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const crypto_1 = require("crypto");
+// add-workspace-webhooks, "Deliveries are signed": X-Fonoster-Timestamp (Unix seconds) and
+// X-Fonoster-Signature = hex HMAC-SHA256 of "<timestamp>.<raw body>", one per valid secret,
+// comma-separated during a rotation window.
+exports.WEBHOOK_SIGNATURE_HEADER = "X-Fonoster-Signature";
+exports.WEBHOOK_TIMESTAMP_HEADER = "X-Fonoster-Timestamp";
+const hmac = (secret, timestamp, body) => (0, crypto_1.createHmac)("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
+function webhookHeaders(body, secrets, nowSeconds = Math.floor(Date.now() / 1000)) {
+    return {
+        [exports.WEBHOOK_TIMESTAMP_HEADER]: String(nowSeconds),
+        [exports.WEBHOOK_SIGNATURE_HEADER]: secrets
+            .map((s) => hmac(s, nowSeconds, body))
+            .join(",")
+    };
+}
+/** For receivers: true when one of the signatures matches and the timestamp is fresh (±300 s). */
+function verifyWebhook(body, headers, secret, nowSeconds = Math.floor(Date.now() / 1000)) {
+    const lower = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]));
+    const timestamp = Number(lower[exports.WEBHOOK_TIMESTAMP_HEADER.toLowerCase()]);
+    const header = lower[exports.WEBHOOK_SIGNATURE_HEADER.toLowerCase()];
+    if (!Number.isFinite(timestamp) || typeof header !== "string")
+        return false;
+    if (Math.abs(nowSeconds - timestamp) > 300)
+        return false;
+    const expected = Buffer.from(hmac(secret, timestamp, body), "hex");
+    return header.split(",").some((sig) => {
+        const given = Buffer.from(sig.trim(), "hex");
+        return given.length === expected.length && (0, crypto_1.timingSafeEqual)(given, expected);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fonoster/common",
-  "version": "0.27.0",
+  "version": "0.30.0",
   "description": "Common library for Fonoster projects",
   "author": "Pedro Sanders <psanders@fonoster.com>",
   "homepage": "https://github.com/fonoster/fonoster#readme",
@@ -15,27 +15,38 @@
     "prebuild": "rimraf ./dist tsconfig.tsbuildinfo",
     "build": "tsc -b tsconfig.json",
     "postbuild": "cp -a src/protos dist",
-    "clean": "rimraf ./dist node_modules tsconfig.tsbuildinfo"
+    "clean": "rimraf ./dist node_modules tsconfig.tsbuildinfo",
+    "generate:session-schema": "tsx scripts/export-session-schema.ts"
   },
   "dependencies": {
-    "@fonoster/logger": "^0.27.0",
-    "@fonoster/types": "^0.27.0",
-    "@grpc/grpc-js": "~1.10.11",
+    "@fonoster/logger": "^0.30.0",
+    "@fonoster/types": "^0.30.0",
+    "@grpc/grpc-js": "~1.14.6",
     "@grpc/proto-loader": "^0.7.15",
     "@influxdata/influxdb-client": "^1.35.0",
-    "dotenv": "^16.6.1",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/resources": "^2.12.0",
+    "@opentelemetry/sdk-trace-base": "^2.12.0",
+    "@opentelemetry/sdk-trace-node": "^2.12.0",
+    "ajv": "^8.17.1",
     "grpc-health-check": "^2.0.2",
     "handlebars": "^4.7.8",
+    "json-schema-to-ts": "^3.1.1",
+    "jsonc-parser": "^3.2.0",
     "jsonwebtoken": "^9.0.2",
     "jwt-decode": "^4.0.0",
-    "nodemailer": "^6.10.1",
+    "nkeys.js": "^1.1.0",
+    "nodemailer": "^10.1.2",
     "pb-util": "^1.0.3",
     "twilio": "^5.11.1",
     "validator": "^13.12.0",
+    "yaml": "^2.9.0",
+    "zod": "^3.25.76",
     "zod-validation-error": "^3.5.4"
   },
   "files": [
-    "dist"
+    "dist",
+    "schema"
   ],
   "publishConfig": {
     "access": "public"
@@ -47,8 +58,10 @@
   "bugs": {
     "url": "https://github.com/fonoster/fonoster/issues"
   },
-  "devDependencies": {
-    "@types/nodemailer": "^6.4.21"
-  },
-  "gitHead": "1191b34677b51a36000177887ff82303ef2693e1"
+  "devDependencies": {},
+  "gitHead": "08c9cfd7932675b6b16111daa4d03f14b4e287d1",
+  "bin": {
+    "fonoster-registry": "dist/registry/cli.js",
+    "fonoster-config": "dist/config/cli/index.js"
+  }
 }