@vex-chat/spire 2.5.0 → 2.6.0

package/src/db/schema.ts

@@ -8,6 +8,63 @@ import type { Insertable, Selectable, Updateable } from "kysely";
 
 // ── Table interfaces ────────────────────────────────────────────────────
 
+export type AccountEntitlementRow = Selectable<AccountEntitlementsTable>;
+
+export interface AccountEntitlementsTable {
+    expiresAt: null | string;
+    source: string;
+    tier: string;
+    updatedAt: string;
+    userID: string;
+}
+
+export type AccountEntitlementUpdate = Updateable<AccountEntitlementsTable>;
+
+export type BillingStoreSubscriptionRow =
+    Selectable<BillingStoreSubscriptionsTable>;
+
+export interface BillingStoreSubscriptionsTable {
+    createdAt: string;
+    environment: string;
+    expiresAt: null | string;
+    externalOriginalID: null | string;
+    externalTransactionID: null | string;
+    platform: string;
+    productID: string;
+    purchaseToken: null | string;
+    purchaseTokenHash: null | string;
+    rawPayload: string;
+    status: string;
+    storeProductID: string;
+    subscriptionID: string;
+    tier: string;
+    updatedAt: string;
+    userID: string;
+}
+
+export type BillingStoreSubscriptionUpdate =
+    Updateable<BillingStoreSubscriptionsTable>;
+
+export type BillingStoreTransactionRow =
+    Selectable<BillingStoreTransactionsTable>;
+
+export interface BillingStoreTransactionsTable {
+    environment: string;
+    eventType: string;
+    externalTransactionID: null | string;
+    platform: string;
+    processedAt: string;
+    purchaseTokenHash: null | string;
+    rawPayload: string;
+    storeProductID: string;
+    subscriptionID: string;
+    transactionID: string;
+    userID: string;
+}
+
+export type BillingStoreTransactionUpdate =
+    Updateable<BillingStoreTransactionsTable>;
+
 export type ChannelRow = Selectable<ChannelsTable>;
 
 export interface ChannelsTable {
@@ -92,8 +149,13 @@ export interface MailTable {
     time: string;
 }
 export type MailUpdate = Updateable<MailTable>;
-export type NewChannel = Insertable<ChannelsTable>;
+export type NewAccountEntitlement = Insertable<AccountEntitlementsTable>;
+export type NewBillingStoreSubscription =
+    Insertable<BillingStoreSubscriptionsTable>;
+export type NewBillingStoreTransaction =
+    Insertable<BillingStoreTransactionsTable>;
 
+export type NewChannel = Insertable<ChannelsTable>;
 export type NewDevice = Insertable<DevicesTable>;
 export type NewDevicePasskeyApproval = Insertable<DevicePasskeyApprovalsTable>;
 export type NewEmoji = Insertable<EmojisTable>;
@@ -177,6 +239,9 @@ export interface PreKeysTable {
 }
 export type PreKeyUpdate = Updateable<PreKeysTable>;
 export interface ServerDatabase {
+    account_entitlements: AccountEntitlementsTable;
+    billing_store_subscriptions: BillingStoreSubscriptionsTable;
+    billing_store_transactions: BillingStoreTransactionsTable;
     channels: ChannelsTable;
     device_passkey_approvals: DevicePasskeyApprovalsTable;
     devices: DevicesTable;

package/src/migrations/2026-06-24_account-entitlements.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import type { Kysely } from "kysely";
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+    await db.schema.dropTable("account_entitlements").ifExists().execute();
+}
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+    await db.schema
+        .createTable("account_entitlements")
+        .ifNotExists()
+        .addColumn("userID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("tier", "varchar(32)", (cb) => cb.notNull())
+        .addColumn("source", "varchar(32)", (cb) => cb.notNull())
+        .addColumn("expiresAt", "text")
+        .addColumn("updatedAt", "text", (cb) => cb.notNull())
+        .execute();
+}

package/src/migrations/2026-07-02_store-subscriptions.ts

@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import type { Kysely } from "kysely";
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+    await db.schema
+        .dropTable("billing_store_transactions")
+        .ifExists()
+        .execute();
+    await db.schema
+        .dropTable("billing_store_subscriptions")
+        .ifExists()
+        .execute();
+}
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+    await db.schema
+        .createTable("billing_store_subscriptions")
+        .ifNotExists()
+        .addColumn("subscriptionID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("userID", "varchar(255)", (cb) => cb.notNull())
+        .addColumn("platform", "varchar(32)", (cb) => cb.notNull())
+        .addColumn("environment", "varchar(32)", (cb) => cb.notNull())
+        .addColumn("productID", "varchar(255)", (cb) => cb.notNull())
+        .addColumn("storeProductID", "varchar(255)", (cb) => cb.notNull())
+        .addColumn("tier", "varchar(32)", (cb) => cb.notNull())
+        .addColumn("status", "varchar(32)", (cb) => cb.notNull())
+        .addColumn("expiresAt", "text")
+        .addColumn("externalOriginalID", "varchar(255)")
+        .addColumn("externalTransactionID", "varchar(255)")
+        .addColumn("purchaseToken", "text")
+        .addColumn("purchaseTokenHash", "varchar(128)")
+        .addColumn("rawPayload", "text", (cb) => cb.notNull())
+        .addColumn("createdAt", "text", (cb) => cb.notNull())
+        .addColumn("updatedAt", "text", (cb) => cb.notNull())
+        .execute();
+
+    await db.schema
+        .createIndex("billing_store_subscriptions_user_idx")
+        .ifNotExists()
+        .on("billing_store_subscriptions")
+        .column("userID")
+        .execute();
+
+    await db.schema
+        .createIndex("billing_store_subscriptions_original_idx")
+        .ifNotExists()
+        .on("billing_store_subscriptions")
+        .columns(["platform", "environment", "externalOriginalID"])
+        .execute();
+
+    await db.schema
+        .createIndex("billing_store_subscriptions_token_hash_idx")
+        .ifNotExists()
+        .on("billing_store_subscriptions")
+        .columns(["platform", "environment", "purchaseTokenHash"])
+        .execute();
+
+    await db.schema
+        .createTable("billing_store_transactions")
+        .ifNotExists()
+        .addColumn("transactionID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("subscriptionID", "varchar(255)", (cb) => cb.notNull())
+        .addColumn("userID", "varchar(255)", (cb) => cb.notNull())
+        .addColumn("platform", "varchar(32)", (cb) => cb.notNull())
+        .addColumn("environment", "varchar(32)", (cb) => cb.notNull())
+        .addColumn("storeProductID", "varchar(255)", (cb) => cb.notNull())
+        .addColumn("eventType", "varchar(64)", (cb) => cb.notNull())
+        .addColumn("externalTransactionID", "varchar(255)")
+        .addColumn("purchaseTokenHash", "varchar(128)")
+        .addColumn("rawPayload", "text", (cb) => cb.notNull())
+        .addColumn("processedAt", "text", (cb) => cb.notNull())
+        .execute();
+
+    await db.schema
+        .createIndex("billing_store_transactions_subscription_idx")
+        .ifNotExists()
+        .on("billing_store_transactions")
+        .column("subscriptionID")
+        .execute();
+
+    await db.schema
+        .createIndex("billing_store_transactions_user_idx")
+        .ifNotExists()
+        .on("billing_store_transactions")
+        .column("userID")
+        .execute();
+}

package/src/server/billing.ts

@@ -0,0 +1,361 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import type { Database, StoreSubscriptionUpsertInput } from "../Database.ts";
+import type {
+    BillingAccountState,
+    BillingProduct,
+    BillingSubscription,
+} from "@vex-chat/types";
+
+import express from "express";
+
+import {
+    AccountTierSchema,
+    AppleServerNotificationRequestSchema,
+    AppleTransactionVerificationRequestSchema,
+    datetime,
+    GooglePlayDeveloperNotificationRequestSchema,
+    GooglePurchaseVerificationRequestSchema,
+} from "@vex-chat/types";
+
+import { z } from "zod/v4";
+
+import {
+    BillingVerificationError,
+    decodeAppleServerNotificationPayload,
+    decodeGooglePlayPubSubNotificationPayload,
+    getBillingProductCatalog,
+    resolveBillingProduct,
+    type VerifiedStorePurchase,
+    verifyAppleTransaction,
+    verifyGooglePurchase,
+} from "../BillingVerification.ts";
+
+import { devApiKeyMatches } from "./rateLimit.ts";
+import { getUser } from "./utils.ts";
+import { sendWireResponse } from "./wireResponse.ts";
+
+import { protect } from "./index.ts";
+
+const devGrantPayload = z.object({
+    expiresAt: datetime.nullable().optional(),
+    tier: AccountTierSchema,
+    userID: z.string().min(1),
+});
+
+export function devBillingGrantRoutesEnabled(
+    env: NodeJS.ProcessEnv = process.env,
+): boolean {
+    return (
+        env["NODE_ENV"] !== "production" &&
+        env["VEX_ENABLE_DEV_BILLING_GRANTS"] === "1" &&
+        (env["DEV_API_KEY"]?.trim().length ?? 0) > 0
+    );
+}
+
+export const getBillingRouter = (
+    db: Database,
+    notify: (
+        userID: string,
+        event: string,
+        transmissionID: string,
+        data?: unknown,
+        deviceID?: string,
+    ) => void,
+) => {
+    const router = express.Router();
+
+    router.get("/billing/products", protect, (_req, res) => {
+        sendWireResponse(_req, res, getBillingProductCatalog());
+    });
+
+    router.get("/billing/account", protect, async (req, res) => {
+        const userID = getUser(req).userID;
+        const state = await db.retrieveBillingAccountState(userID);
+        sendWireResponse(req, res, state);
+    });
+
+    router.post("/billing/apple/transactions", protect, async (req, res) => {
+        const parsed = AppleTransactionVerificationRequestSchema.safeParse(
+            req.body,
+        );
+        if (!parsed.success) {
+            res.status(400).json({
+                error: "Invalid Apple transaction payload",
+                issues: parsed.error.issues,
+            });
+            return;
+        }
+
+        await handleVerifiedPurchase(req, res, {
+            db,
+            eventType: "apple_transaction_verified",
+            notify,
+            purchase: await verifyAppleTransaction(parsed.data),
+            userID: getUser(req).userID,
+        });
+    });
+
+    router.post("/billing/google/purchases", protect, async (req, res) => {
+        const parsed = GooglePurchaseVerificationRequestSchema.safeParse(
+            req.body,
+        );
+        if (!parsed.success) {
+            res.status(400).json({
+                error: "Invalid Google Play purchase payload",
+                issues: parsed.error.issues,
+            });
+            return;
+        }
+
+        await handleVerifiedPurchase(req, res, {
+            db,
+            eventType: "google_purchase_verified",
+            notify,
+            purchase: await verifyGooglePurchase(parsed.data),
+            userID: getUser(req).userID,
+        });
+    });
+
+    router.post("/billing/webhooks/apple", async (req, res) => {
+        const parsed = AppleServerNotificationRequestSchema.safeParse(req.body);
+        if (!parsed.success) {
+            res.status(400).json({
+                error: "Invalid Apple server notification payload",
+                issues: parsed.error.issues,
+            });
+            return;
+        }
+
+        const notification = decodeAppleServerNotificationPayload(
+            parsed.data.signedPayload,
+        );
+        const signedTransactionInfo = notification.data?.signedTransactionInfo;
+        if (!signedTransactionInfo) {
+            res.sendStatus(202);
+            return;
+        }
+
+        const purchase = await verifyAppleTransaction({
+            signedTransactionInfo,
+        });
+        const userID = await db.retrieveStoreSubscriptionOwner({
+            environment: purchase.environment,
+            externalOriginalID: purchase.externalOriginalID,
+            platform: purchase.platform,
+        });
+        if (!userID) {
+            res.sendStatus(202);
+            return;
+        }
+
+        await handleVerifiedPurchase(req, res, {
+            db,
+            eventType: `apple_webhook_${notification.notificationType ?? "unknown"}`,
+            notify,
+            purchase,
+            userID,
+        });
+    });
+
+    router.post("/billing/webhooks/google", async (req, res) => {
+        const parsed = GooglePlayDeveloperNotificationRequestSchema.safeParse(
+            req.body,
+        );
+        if (!parsed.success) {
+            res.status(400).json({
+                error: "Invalid Google Play notification payload",
+                issues: parsed.error.issues,
+            });
+            return;
+        }
+        const notification = decodeGooglePlayPubSubNotificationPayload(
+            req.body,
+        );
+        const purchaseToken =
+            notification.subscriptionNotification?.purchaseToken;
+        if (!purchaseToken) {
+            res.sendStatus(202);
+            return;
+        }
+
+        const purchase = await verifyGooglePurchase({
+            packageName: notification.packageName,
+            productID: notification.subscriptionNotification?.subscriptionId,
+            purchaseToken,
+        });
+        const userID = await db.retrieveStoreSubscriptionOwner({
+            environment: purchase.environment,
+            platform: purchase.platform,
+            purchaseToken,
+        });
+        if (!userID) {
+            res.sendStatus(202);
+            return;
+        }
+
+        await handleVerifiedPurchase(req, res, {
+            db,
+            eventType: "google_webhook_subscription",
+            notify,
+            purchase,
+            userID,
+        });
+    });
+
+    if (devBillingGrantRoutesEnabled()) {
+        router.post("/__dev/billing/grants", async (req, res) => {
+            if (!devBillingGrantRoutesEnabled()) {
+                res.sendStatus(404);
+                return;
+            }
+            if (!devApiKeyMatches(req)) {
+                res.sendStatus(403);
+                return;
+            }
+            const parsed = devGrantPayload.safeParse(req.body);
+            if (!parsed.success) {
+                res.status(400).json({
+                    error: "Invalid dev billing grant payload",
+                    issues: parsed.error.issues,
+                });
+                return;
+            }
+
+            const entitlements = await db.setAccountEntitlementTier(
+                parsed.data.userID,
+                parsed.data.tier,
+                {
+                    expiresAt: parsed.data.expiresAt ?? null,
+                    source: "store",
+                },
+            );
+            notify(
+                parsed.data.userID,
+                "accountEntitlementsChanged",
+                crypto.randomUUID(),
+                { tier: entitlements.tier },
+            );
+            sendWireResponse(req, res, entitlements);
+        });
+    }
+
+    router.use(
+        (
+            err: unknown,
+            _req: express.Request,
+            res: express.Response,
+            next: express.NextFunction,
+        ) => {
+            if (err instanceof BillingVerificationError) {
+                res.status(err.status).json({ error: err.message });
+                return;
+            }
+            next(err);
+        },
+    );
+
+    return router;
+};
+
+export function billingAccountPath(): string {
+    return "/billing/account";
+}
+
+export function billingAppleTransactionPath(): string {
+    return "/billing/apple/transactions";
+}
+
+export function billingDevGrantPath(): string {
+    return "/__dev/billing/grants";
+}
+
+export function billingGooglePurchasePath(): string {
+    return "/billing/google/purchases";
+}
+
+export function billingProductsPath(): string {
+    return "/billing/products";
+}
+
+export function billingUserPath(userID: string): string {
+    return `/user/${encodeURIComponent(userID)}/billing`;
+}
+
+async function handleVerifiedPurchase(
+    req: express.Request,
+    res: express.Response,
+    args: {
+        db: Database;
+        eventType: string;
+        notify: (
+            userID: string,
+            event: string,
+            transmissionID: string,
+            data?: unknown,
+            deviceID?: string,
+        ) => void;
+        purchase: VerifiedStorePurchase;
+        userID: string;
+    },
+): Promise<void> {
+    const product = resolveBillingProduct(args.purchase);
+    const subscription = await persistVerifiedPurchase(args.db, {
+        product,
+        purchase: args.purchase,
+        userID: args.userID,
+    });
+    await args.db.recordStoreTransaction({
+        eventType: args.eventType,
+        externalTransactionID: args.purchase.externalTransactionID,
+        rawPayload: args.purchase.rawPayload,
+        subscriptionID: subscription.subscriptionID,
+        userID: args.userID,
+    });
+    const entitlements = await args.db.recalculateStoreEntitlements(
+        args.userID,
+    );
+    args.notify(
+        args.userID,
+        "accountEntitlementsChanged",
+        crypto.randomUUID(),
+        {
+            tier: entitlements.tier,
+        },
+    );
+
+    const state: BillingAccountState = {
+        entitlements,
+        subscriptions: await args.db.retrieveBillingSubscriptions(args.userID),
+    };
+    sendWireResponse(req, res, state);
+}
+
+async function persistVerifiedPurchase(
+    db: Database,
+    args: {
+        product: BillingProduct;
+        purchase: VerifiedStorePurchase;
+        userID: string;
+    },
+): Promise<BillingSubscription> {
+    const input: StoreSubscriptionUpsertInput = {
+        environment: args.purchase.environment,
+        expiresAt: args.purchase.expiresAt,
+        externalOriginalID: args.purchase.externalOriginalID,
+        externalTransactionID: args.purchase.externalTransactionID,
+        platform: args.purchase.platform,
+        productID: args.product.productID,
+        purchaseToken: args.purchase.purchaseToken,
+        rawPayload: args.purchase.rawPayload,
+        status: args.purchase.status,
+        storeProductID: args.product.storeProductID,
+        tier: args.product.tier,
+        userID: args.userID,
+    };
+    return db.upsertStoreSubscription(input);
+}

package/src/server/entitlements.ts

@@ -0,0 +1,104 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import type { Database } from "../Database.ts";
+
+import express from "express";
+
+import { AccountTierSchema, datetime } from "@vex-chat/types";
+
+import { z } from "zod/v4";
+
+import { devApiKeyMatches } from "./rateLimit.ts";
+import { getParam, getUser } from "./utils.ts";
+import { sendWireResponse } from "./wireResponse.ts";
+
+import { protect } from "./index.ts";
+
+const devEntitlementPatchPayload = z.object({
+    expiresAt: datetime.nullable().optional(),
+    tier: AccountTierSchema,
+});
+
+export function devEntitlementRoutesEnabled(
+    env: NodeJS.ProcessEnv = process.env,
+): boolean {
+    return (
+        env["NODE_ENV"] !== "production" &&
+        env["VEX_ENABLE_DEV_ENTITLEMENTS"] === "1" &&
+        (env["DEV_API_KEY"]?.trim().length ?? 0) > 0
+    );
+}
+
+export const getEntitlementRouter = (
+    db: Database,
+    notify: (
+        userID: string,
+        event: string,
+        transmissionID: string,
+        data?: unknown,
+        deviceID?: string,
+    ) => void,
+) => {
+    const router = express.Router();
+
+    router.get("/user/:id/entitlements", protect, async (req, res) => {
+        const userDetails = getUser(req);
+        const userID = getParam(req, "id");
+        if (userDetails.userID !== userID) {
+            res.sendStatus(401);
+            return;
+        }
+
+        const entitlements = await db.retrieveAccountEntitlements(userID);
+        sendWireResponse(req, res, entitlements);
+    });
+
+    if (!devEntitlementRoutesEnabled()) {
+        return router;
+    }
+
+    router.patch("/__dev/user/:id/entitlements", protect, async (req, res) => {
+        if (!devEntitlementRoutesEnabled()) {
+            res.sendStatus(404);
+            return;
+        }
+        const userDetails = getUser(req);
+        const userID = getParam(req, "id");
+        if (userDetails.userID !== userID) {
+            res.sendStatus(401);
+            return;
+        }
+        if (!devApiKeyMatches(req)) {
+            res.sendStatus(403);
+            return;
+        }
+
+        const parsed = devEntitlementPatchPayload.safeParse(req.body);
+        if (!parsed.success) {
+            res.status(400).json({
+                error: "Invalid entitlement payload",
+                issues: parsed.error.issues,
+            });
+            return;
+        }
+
+        const entitlements = await db.setAccountEntitlementTier(
+            userID,
+            parsed.data.tier,
+            {
+                expiresAt: parsed.data.expiresAt ?? null,
+                source: "dev_override",
+            },
+        );
+        notify(userID, "accountEntitlementsChanged", crypto.randomUUID(), {
+            tier: entitlements.tier,
+        });
+        sendWireResponse(req, res, entitlements);
+    });
+
+    return router;
+};

package/src/server/index.ts

@@ -32,7 +32,9 @@ import { verifyPreKeyWsSignature } from "../utils/preKeySignature.ts";
 import { spireXSignOpenAsync } from "../utils/spireXSignOpenAsync.ts";
 
 import { getAvatarRouter } from "./avatar.ts";
+import { getBillingRouter } from "./billing.ts";
 import { getCliPasskeyPageRouter } from "./cliPasskeyPage.ts";
+import { getEntitlementRouter } from "./entitlements.ts";
 import { errorHandler } from "./errors.ts";
 import { getFileRouter } from "./file.ts";
 import { getInviteRouter } from "./invite.ts";
@@ -255,6 +257,8 @@ export const initApp = (
     const userRouter = getUserRouter(db, tokenValidator, notify);
     const fileRouter = getFileRouter(db);
     const avatarRouter = getAvatarRouter();
+    const billingRouter = getBillingRouter(db, notify);
+    const entitlementRouter = getEntitlementRouter(db, notify);
     const inviteRouter = getInviteRouter(db, tokenValidator, notify);
     const passkeyRouter = getPasskeyRouter(db);
     const passkeyDeviceRouter = getPasskeyDeviceRouter(
@@ -1024,6 +1028,8 @@ export const initApp = (
     // an authenticated device) and `/auth/passkey/...` (public
     // sign-in). The router itself defines the full path on each
     // route handler.
+    api.use(billingRouter);
+    api.use(entitlementRouter);
     api.use(passkeyRouter);
     api.use(passkeyDeviceRouter);