@pylonsync/stripe 0.3.83

package/src/plans.ts

@@ -0,0 +1,57 @@
+/**
+ * Plan resolution helpers — map a Stripe subscription item back to
+ * the app's plan name, and the reverse (plan name → price id) for
+ * checkout session creation.
+ *
+ * Stripe sometimes elides `nickname` / `lookup_key` on webhook
+ * payloads (the price object is shallow-expanded), which made
+ * yapless's old plan-derivation function silently demote orgs to
+ * "pending" after a successful checkout. We try three signals in
+ * order so the resolver still works when any one is missing:
+ *
+ *   1. price.lookup_key (operator-set, most stable)
+ *   2. price.nickname   (often elided on webhooks)
+ *   3. price.id matched against the plan catalog's priceId/annualPriceId
+ */
+
+import type { StripePlan, StripeSubscription } from "./types";
+
+export function findPlanByName(
+	plans: StripePlan[],
+	name: string,
+): StripePlan | undefined {
+	return plans.find((p) => p.name === name);
+}
+
+export interface ResolvedPlan {
+	plan: StripePlan | null;
+	annual: boolean;
+}
+
+export function planFromSubscription(
+	plans: StripePlan[],
+	sub: StripeSubscription,
+): ResolvedPlan {
+	const item = sub.items.data[0];
+	if (!item) return { plan: null, annual: false };
+	const priceId = item.price.id;
+	const key = item.price.lookup_key ?? item.price.nickname ?? undefined;
+	if (key) {
+		const byKey = plans.find((p) => p.name === key);
+		if (byKey) return { plan: byKey, annual: byKey.annualPriceId === priceId };
+	}
+	for (const p of plans) {
+		if (p.priceId === priceId) return { plan: p, annual: false };
+		if (p.annualPriceId === priceId) return { plan: p, annual: true };
+	}
+	return { plan: null, annual: false };
+}
+
+export function periodEndFromSubscription(
+	sub: StripeSubscription,
+): string | null {
+	const ts =
+		sub.items.data[0]?.current_period_end ?? sub.current_period_end ?? null;
+	if (!ts) return null;
+	return new Date(ts * 1000).toISOString();
+}

package/src/safe-url.test.ts

@@ -0,0 +1,71 @@
+import { expect, test } from "bun:test";
+
+import { assertSafeRedirectUrl } from "./safe-url";
+
+test("accepts URL on the PYLON_PUBLIC_URL host", () => {
+	expect(() =>
+		assertSafeRedirectUrl(
+			"https://api.getyapless.com/dashboard?welcome=1",
+			"https://api.getyapless.com",
+		),
+	).not.toThrow();
+});
+
+test("accepts subdomain of the PYLON_PUBLIC_URL host", () => {
+	// PYLON_PUBLIC_URL=https://api.acme.com → www.acme.com allowed.
+	// (The check is suffix-based on the trailing dot, so api.acme.com
+	// allows *.acme.com? — we actually allow only hosts ending in
+	// `.<host>`, so we accept "ext.api.acme.com" but NOT "acme.com"
+	// or "www.acme.com". This is intentional — the SyncProjectCors
+	// helper in pylon-cloud emits the apex/www variants explicitly.)
+	expect(() =>
+		assertSafeRedirectUrl(
+			"https://ext.api.getyapless.com/cb",
+			"https://api.getyapless.com",
+		),
+	).not.toThrow();
+});
+
+test("rejects unrelated host", () => {
+	expect(() =>
+		assertSafeRedirectUrl(
+			"https://attacker.example.com/steal",
+			"https://api.getyapless.com",
+		),
+	).toThrow(/not on the allowed host/);
+});
+
+test("accepts localhost in dev", () => {
+	expect(() =>
+		assertSafeRedirectUrl("http://localhost:3000/cb", "https://api.x.com"),
+	).not.toThrow();
+});
+
+test("explicit extraHost widens the allowlist", () => {
+	expect(() =>
+		assertSafeRedirectUrl(
+			"https://www.getyapless.com/dashboard",
+			"https://api.getyapless.com",
+			{ extraHost: "www.getyapless.com" },
+		),
+	).not.toThrow();
+});
+
+test("extraOrigins (PYLON_CORS_ORIGIN-style) parses comma list", () => {
+	expect(() =>
+		assertSafeRedirectUrl(
+			"https://www.getyapless.com/dashboard",
+			"https://api.getyapless.com",
+			{
+				extraOrigins:
+					"https://getyapless.com,https://www.getyapless.com,https://pylon-yapless.fly.dev",
+			},
+		),
+	).not.toThrow();
+});
+
+test("malformed URLs throw a clear error", () => {
+	expect(() => assertSafeRedirectUrl("not-a-url", "https://x.com")).toThrow(
+		/invalid URL/,
+	);
+});

package/src/safe-url.ts

@@ -0,0 +1,82 @@
+/**
+ * URL allowlist for Stripe Checkout `success_url` + `cancel_url`.
+ *
+ * The bug we're closing: hardcoded allowlists ("yapless.com" vs the
+ * actual "getyapless.com") cause every checkout button to throw
+ * "URL is not on the allowed host" in prod. Reading allowlist from
+ * `ctx.env.PYLON_PUBLIC_URL` (which Pylon Cloud auto-sets) eliminates
+ * the whole bug class — the same env that drives OAuth callbacks +
+ * SAML responses also drives Stripe redirect validation.
+ *
+ * Defense:
+ *   - Allowed origins = [PYLON_PUBLIC_URL host] + extras provided
+ *     by the app (e.g. its marketing root if different from the API
+ *     host) + localhost/127.0.0.1 in dev.
+ *   - Subdomain match (api.acme.com → also allows www.acme.com via
+ *     suffix logic) is intentional: SaaS apps almost always serve
+ *     frontend + backend under sibling subdomains, and forcing the
+ *     app to list every subdomain creates the same hardcoding bug
+ *     this is trying to prevent.
+ */
+
+export interface AssertSafeUrlOptions {
+	/** Comma-separated list pulled from `ctx.env.PYLON_CORS_ORIGIN` */
+	extraOrigins?: string;
+	/** Single hostname override (legacy `YAPLESS_BASE_HOST`-style env). */
+	extraHost?: string;
+	/** Default: PYLON_DEV_MODE → true. Apps can force-disable for tests. */
+	allowLocalhost?: boolean;
+}
+
+export function assertSafeRedirectUrl(
+	url: string,
+	publicUrl: string | undefined,
+	opts: AssertSafeUrlOptions = {},
+): void {
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new Error(`invalid URL: ${url}`);
+	}
+	const host = parsed.hostname;
+	const allowed = collectAllowedHosts(publicUrl, opts);
+	for (const a of allowed) {
+		if (host === a) return;
+		if (host.endsWith(`.${a}`)) return;
+	}
+	const allowList = allowed.length > 0 ? allowed.join(", ") : "(none)";
+	throw new Error(`URL ${url} is not on the allowed host (${allowList})`);
+}
+
+function collectAllowedHosts(
+	publicUrl: string | undefined,
+	opts: AssertSafeUrlOptions,
+): string[] {
+	const out = new Set<string>();
+	if (publicUrl) {
+		try {
+			out.add(new URL(publicUrl).hostname);
+		} catch {
+			// ignore — malformed env shouldn't crash checkout
+		}
+	}
+	if (opts.extraHost) out.add(opts.extraHost);
+	if (opts.extraOrigins) {
+		for (const o of opts.extraOrigins.split(",")) {
+			const trimmed = o.trim();
+			if (!trimmed) continue;
+			try {
+				out.add(new URL(trimmed).hostname);
+			} catch {
+				// Bare hostname (no scheme) — accept as-is.
+				out.add(trimmed);
+			}
+		}
+	}
+	if (opts.allowLocalhost ?? true) {
+		out.add("localhost");
+		out.add("127.0.0.1");
+	}
+	return Array.from(out);
+}

package/src/signature.test.ts

@@ -0,0 +1,93 @@
+import { expect, test } from "bun:test";
+
+import { verifyStripeSignature } from "./signature";
+
+const SECRET = "whsec_test_secret_value";
+const RAW_BODY = '{"id":"evt_test","type":"customer.subscription.created"}';
+
+async function hmacHex(secret: string, payload: string): Promise<string> {
+	const enc = new TextEncoder();
+	const key = await crypto.subtle.importKey(
+		"raw",
+		enc.encode(secret),
+		{ name: "HMAC", hash: "SHA-256" },
+		false,
+		["sign"],
+	);
+	const sig = await crypto.subtle.sign("HMAC", key, enc.encode(payload));
+	return [...new Uint8Array(sig)]
+		.map((b) => b.toString(16).padStart(2, "0"))
+		.join("");
+}
+
+async function signedHeader(
+	secret: string,
+	rawBody: string,
+	tsSecs: number,
+): Promise<string> {
+	const sig = await hmacHex(secret, `${tsSecs}.${rawBody}`);
+	return `t=${tsSecs},v1=${sig}`;
+}
+
+test("verify accepts a valid signature within tolerance", async () => {
+	const now = 1_700_000_000;
+	const header = await signedHeader(SECRET, RAW_BODY, now);
+	const result = await verifyStripeSignature(SECRET, RAW_BODY, header, {
+		nowSecs: now,
+	});
+	expect(result).toBe(true);
+});
+
+test("verify rejects a stale timestamp (replay window)", async () => {
+	const eventTs = 1_700_000_000;
+	const now = eventTs + 10 * 60; // 10 min later
+	const header = await signedHeader(SECRET, RAW_BODY, eventTs);
+	const result = await verifyStripeSignature(SECRET, RAW_BODY, header, {
+		nowSecs: now,
+	});
+	expect(result).toBe("REPLAYED");
+});
+
+test("verify rejects a tampered body", async () => {
+	const now = 1_700_000_000;
+	const header = await signedHeader(SECRET, RAW_BODY, now);
+	const result = await verifyStripeSignature(
+		SECRET,
+		`${RAW_BODY}x`, // body changed after signing
+		header,
+		{ nowSecs: now },
+	);
+	expect(result).toBe("INVALID_SIGNATURE");
+});
+
+test("verify rejects a wrong secret", async () => {
+	const now = 1_700_000_000;
+	const header = await signedHeader(SECRET, RAW_BODY, now);
+	const result = await verifyStripeSignature(
+		"whsec_different",
+		RAW_BODY,
+		header,
+		{ nowSecs: now },
+	);
+	expect(result).toBe("INVALID_SIGNATURE");
+});
+
+test("verify reports MISSING_HEADER on null/undefined", async () => {
+	expect(await verifyStripeSignature(SECRET, RAW_BODY, null)).toBe(
+		"MISSING_HEADER",
+	);
+	expect(await verifyStripeSignature(SECRET, RAW_BODY, undefined)).toBe(
+		"MISSING_HEADER",
+	);
+});
+
+test("verify accepts either of multiple v1 signatures (secret rotation)", async () => {
+	const now = 1_700_000_000;
+	const sigOld = await hmacHex("whsec_old", `${now}.${RAW_BODY}`);
+	const sigNew = await hmacHex(SECRET, `${now}.${RAW_BODY}`);
+	const header = `t=${now},v1=${sigOld},v1=${sigNew}`;
+	const result = await verifyStripeSignature(SECRET, RAW_BODY, header, {
+		nowSecs: now,
+	});
+	expect(result).toBe(true);
+});

package/src/signature.ts

@@ -0,0 +1,88 @@
+/**
+ * Stripe webhook signature verification.
+ *
+ * Stripe signs every webhook payload with HMAC-SHA256 over
+ * `<timestamp>.<rawBody>` and includes the signature + timestamp in
+ * the `Stripe-Signature` header (format: `t=<unix>,v1=<sig>,...`).
+ *
+ * Spec: https://stripe.com/docs/webhooks/signatures
+ *
+ * Constants:
+ *   - 5-minute replay window (matches Stripe's CLI tool default).
+ *   - Constant-time signature compare to defeat timing oracles.
+ *
+ * Implementation uses the WebCrypto API (Bun + Node 20+) — no
+ * third-party crypto dep.
+ */
+
+const DEFAULT_TOLERANCE_SECS = 300;
+
+export type SignatureError =
+	| "MISSING_HEADER"
+	| "MISSING_TIMESTAMP"
+	| "MISSING_SIGNATURE"
+	| "REPLAYED"
+	| "INVALID_SIGNATURE";
+
+/**
+ * Returns `true` when the signature header matches an HMAC of the
+ * raw body under the given secret AND the timestamp is within the
+ * replay window. Returns a string error code otherwise.
+ *
+ * `nowSecs` lets tests inject a fixed clock; production should leave
+ * it undefined to use `Date.now()`.
+ */
+export async function verifyStripeSignature(
+	secret: string,
+	rawBody: string,
+	headerValue: string | undefined | null,
+	opts: { toleranceSecs?: number; nowSecs?: number } = {},
+): Promise<true | SignatureError> {
+	if (!headerValue) return "MISSING_HEADER";
+	const tolerance = opts.toleranceSecs ?? DEFAULT_TOLERANCE_SECS;
+	const now = opts.nowSecs ?? Math.floor(Date.now() / 1000);
+
+	// Header shape: `t=<unix>,v1=<sig>[,v1=<sig2>...]`. Multiple v1s
+	// appear during signing-secret rotation — accept either.
+	let timestamp: number | null = null;
+	const signatures: string[] = [];
+	for (const part of headerValue.split(",")) {
+		const [k, v] = part.split("=");
+		if (!k || !v) continue;
+		if (k.trim() === "t") timestamp = Number.parseInt(v.trim(), 10);
+		else if (k.trim() === "v1") signatures.push(v.trim());
+	}
+	if (timestamp === null || Number.isNaN(timestamp)) return "MISSING_TIMESTAMP";
+	if (signatures.length === 0) return "MISSING_SIGNATURE";
+	if (Math.abs(now - timestamp) > tolerance) return "REPLAYED";
+
+	const expected = await hmacSha256Hex(secret, `${timestamp}.${rawBody}`);
+	for (const sig of signatures) {
+		if (constantTimeEqualHex(sig, expected)) return true;
+	}
+	return "INVALID_SIGNATURE";
+}
+
+async function hmacSha256Hex(secret: string, payload: string): Promise<string> {
+	const enc = new TextEncoder();
+	const key = await crypto.subtle.importKey(
+		"raw",
+		enc.encode(secret),
+		{ name: "HMAC", hash: "SHA-256" },
+		false,
+		["sign"],
+	);
+	const sig = await crypto.subtle.sign("HMAC", key, enc.encode(payload));
+	return [...new Uint8Array(sig)]
+		.map((b) => b.toString(16).padStart(2, "0"))
+		.join("");
+}
+
+function constantTimeEqualHex(a: string, b: string): boolean {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) {
+		diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	}
+	return diff === 0;
+}

package/src/types.ts

@@ -0,0 +1,259 @@
+/**
+ * Public type surface for `@pylonsync/stripe`.
+ *
+ * Shapes mirror Stripe's REST payloads at the level we actually use —
+ * we don't pull in the official `stripe` SDK's types because they
+ * change cadence + breadth doesn't match what apps need. If you need
+ * a field that's missing, add it here.
+ */
+
+export interface StripePlan {
+	/**
+	 * Stable internal name. Stored on Subscription.plan + used as the
+	 * `lookup_key` we set on Stripe prices via setup-stripe scripts.
+	 * Lowercase, dash-separated.
+	 */
+	name: string;
+	/**
+	 * Stripe Price id (price_...) for the monthly tier. Resolved
+	 * eagerly when the plan list is built (env-var indirection
+	 * stays at the call site, not threaded through the plugin).
+	 */
+	priceId: string;
+	/** Optional annual variant; surfaced as `annual: true` on upgrade. */
+	annualPriceId?: string;
+	/**
+	 * Free-trial config. When set, checkout sessions for this plan
+	 * default to `subscription_data.trial_period_days`. The plugin
+	 * enforces one-trial-per-customer at the Stripe API level — Stripe
+	 * itself rejects a second trial on the same customer when
+	 * `trial_from_plan: true` is used, but we additionally short-
+	 * circuit on the cloud side based on prior subscriptions to avoid
+	 * the round-trip rejection.
+	 */
+	freeTrial?: {
+		days: number;
+	};
+	/**
+	 * Per-plan entitlement limits. Stored on the Subscription row's
+	 * `limits` JSON column so app code can do quota checks without
+	 * re-reading the plan list. Values are app-defined (recordings,
+	 * seats, requests/mo — whatever the app meters).
+	 */
+	limits?: Record<string, number | boolean | string>;
+	/**
+	 * Seat-based billing. When set, `quantity` flows through to
+	 * Stripe Subscription + the Subscription row stores `seats`.
+	 */
+	seatPriceId?: string;
+}
+
+/**
+ * Reference-type for who owns a subscription. Most apps want `org`
+ * (multi-seat workspaces); single-user apps set this to `user`. The
+ * plugin doesn't care which — `referenceId` is just an opaque string
+ * that gets stamped on Subscription.referenceId and looked up via
+ * `getReference()` on webhook delivery.
+ */
+export type ReferenceType = "user" | "org" | "custom";
+
+export interface StripeConfig {
+	/**
+	 * Resolved at runtime from `ctx.env.STRIPE_SECRET_KEY` unless an
+	 * override is provided. Apps using multiple Stripe accounts (dev/
+	 * prod under one binary) can wire a selector here.
+	 */
+	getSecretKey?: (ctx: HandlerCtx) => string;
+	/**
+	 * Resolved at runtime from `ctx.env.STRIPE_WEBHOOK_SECRET`.
+	 * Same override pattern as `getSecretKey`.
+	 */
+	getWebhookSecret?: (ctx: HandlerCtx) => string;
+	/**
+	 * `user` — Subscription.referenceId = User.id. Customer is auto-
+	 * created on first checkout, stored as `User.stripeCustomerId`.
+	 * `org`  — Subscription.referenceId = Org.id. Customer is on
+	 *          `Org.stripeCustomerId`. RBAC: only owners/admins can
+	 *          upgrade/cancel.
+	 * `custom` — caller supplies their own referenceId + customer
+	 *           resolution via `resolveCustomer` hook.
+	 */
+	referenceType: ReferenceType;
+	/**
+	 * The plan catalog. Order matters: the first plan whose
+	 * `priceId`/`lookupKey` matches a Stripe subscription's items
+	 * wins on plan-derivation from webhook payloads.
+	 */
+	plans: StripePlan[];
+	/**
+	 * Which Stripe API version the client pins. Match this against
+	 * what your dashboard webhook subscription is set to receive,
+	 * otherwise field shapes drift.
+	 */
+	apiVersion?: string;
+	/**
+	 * Override the entity names the plugin reads/writes. Defaults
+	 * mirror the manifest entities exported from this package.
+	 */
+	entities?: {
+		subscription?: string;
+		/** Where stripeCustomerId lives. Required. */
+		customerHolder?: string;
+	};
+	/**
+	 * Lifecycle hooks. Called server-side after the plugin has
+	 * persisted its own state — apps add analytics, welcome emails,
+	 * cache invalidation here.
+	 */
+	hooks?: StripeHooks;
+	/**
+	 * RBAC gate for subscription mutation actions. Returns `true` to
+	 * allow, throws / returns `false` to deny. Defaults: for `org`
+	 * referenceType, allows owners + admins; for `user`, allows the
+	 * caller iff their auth.userId === referenceId.
+	 */
+	authorizeReference?: (
+		ctx: HandlerCtx,
+		args: { referenceId: string; action: SubscriptionAction },
+	) => Promise<boolean> | boolean;
+	/**
+	 * `custom` referenceType requires this hook to map referenceId
+	 * to a Stripe customer id (and create one if needed).
+	 */
+	resolveCustomer?: (
+		ctx: HandlerCtx,
+		referenceId: string,
+	) => Promise<{ customerId: string; email?: string }>;
+}
+
+export type SubscriptionAction =
+	| "upgrade"
+	| "cancel"
+	| "restore"
+	| "billingPortal"
+	| "list";
+
+export interface StripeHooks {
+	/** Fires after a Stripe customer is created. */
+	onCustomerCreate?: (
+		ctx: HandlerCtx,
+		args: { referenceId: string; customerId: string; email?: string },
+	) => Promise<void> | void;
+	/**
+	 * Fires after `customer.subscription.created` is persisted.
+	 * Includes the resolved plan name + the StripeSubscription row.
+	 */
+	onSubscriptionActivate?: (
+		ctx: HandlerCtx,
+		args: { referenceId: string; plan: string; subscription: StripeSubscription },
+	) => Promise<void> | void;
+	/** Fires after `customer.subscription.updated` (plan changes, renewals). */
+	onSubscriptionUpdate?: (
+		ctx: HandlerCtx,
+		args: { referenceId: string; plan: string; subscription: StripeSubscription },
+	) => Promise<void> | void;
+	/** Fires after `customer.subscription.deleted`. */
+	onSubscriptionCancel?: (
+		ctx: HandlerCtx,
+		args: { referenceId: string; subscription: StripeSubscription },
+	) => Promise<void> | void;
+	/** Fires after every invoice event the plugin processes. */
+	onInvoice?: (
+		ctx: HandlerCtx,
+		args: { referenceId: string; eventType: string; invoice: StripeInvoice },
+	) => Promise<void> | void;
+	/**
+	 * Catch-all for any Stripe webhook event the plugin doesn't have
+	 * built-in handling for. Useful for `payment_method.attached`,
+	 * `charge.dispute.created`, etc.
+	 */
+	onEvent?: (ctx: HandlerCtx, event: StripeEvent) => Promise<void> | void;
+	/**
+	 * Inject extra params into the Stripe Checkout Session create
+	 * call (tax, promo codes, idempotency key, custom_fields, etc.).
+	 * Plugin merges over the base shape, so you can override defaults
+	 * if you really want to.
+	 */
+	getCheckoutSessionParams?: (
+		ctx: HandlerCtx,
+		args: {
+			referenceId: string;
+			plan: StripePlan;
+			customerId: string;
+			successUrl: string;
+			cancelUrl: string;
+		},
+	) => Promise<Record<string, unknown>> | Record<string, unknown>;
+}
+
+export interface StripeEvent {
+	id: string;
+	type: string;
+	data: { object: Record<string, unknown> };
+	created: number;
+}
+
+export interface StripeSubscription {
+	id: string;
+	status:
+		| "active"
+		| "past_due"
+		| "canceled"
+		| "incomplete"
+		| "incomplete_expired"
+		| "trialing"
+		| "unpaid"
+		| "paused";
+	current_period_end?: number | null;
+	cancel_at_period_end?: boolean;
+	cancel_at?: number | null;
+	canceled_at?: number | null;
+	customer: string;
+	trial_start?: number | null;
+	trial_end?: number | null;
+	items: {
+		data: Array<{
+			id?: string;
+			current_period_end?: number | null;
+			quantity?: number;
+			price: {
+				id: string;
+				nickname?: string | null;
+				lookup_key?: string | null;
+			};
+		}>;
+	};
+}
+
+export interface StripeInvoice {
+	id: string;
+	status: string;
+	amount_paid?: number;
+	amount_due: number;
+	period_start: number;
+	period_end: number;
+	customer: string;
+	subscription?: string;
+	hosted_invoice_url?: string;
+}
+
+/**
+ * Handler-side `ctx` shape, narrowed to just the bits the plugin
+ * touches. The real ctx from `@pylonsync/functions` is wider; we
+ * type-guard the subset we depend on so the package compiles
+ * without a tight dep on the functions runtime types.
+ */
+export interface HandlerCtx {
+	env: Record<string, string | undefined>;
+	auth: { userId?: string | null; tenantId?: string | null; isAdmin?: boolean };
+	request?: {
+		headers: Record<string, string | undefined>;
+		rawBody: string;
+	};
+	runQuery: <T>(name: string, args: Record<string, unknown>) => Promise<T>;
+	runMutation: <T = unknown>(
+		name: string,
+		args: Record<string, unknown>,
+	) => Promise<T>;
+	error: (code: string, message: string) => Error;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["bun-types"]
+  },
+  "include": [
+    "src"
+  ]
+}