@molecule/api-resource-user 1.0.0

package/dist/handlers/oauthAuthorize.js

@@ -0,0 +1,141 @@
+import crypto from 'node:crypto';
+import { get } from '@molecule/api-bond';
+import { get as getConfig } from '@molecule/api-config';
+import { t } from '@molecule/api-i18n';
+import * as authorization from '../authorization.js';
+/** TTL for the OAuth `state` + PKCE `verifier` cookies (one flow's lifetime). */
+const OAUTH_COOKIE_MAX_AGE_MS = 5 * 60 * 1000;
+/**
+ * Validate a client-supplied return path so the post-login redirect can only
+ * land somewhere on the app's own origin. Accepts a same-origin absolute path
+ * (`/login`), rejects anything protocol-relative (`//evil.com`), scheme-ful
+ * (`https://…`), or backslash-tricky — those would turn the `redirect_uri` we
+ * send the provider into an open redirect.
+ *
+ * @param value - The raw `redirect_to` query value.
+ * @returns The validated path, or `''` (the app origin root) when invalid/absent.
+ */
+const sanitizeRedirectPath = (value) => {
+    if (typeof value !== 'string' || value === '') {
+        return '';
+    }
+    if (!value.startsWith('/') || value.startsWith('//') || value.includes('\\')) {
+        return '';
+    }
+    return value;
+};
+/**
+ * OAuth initiation — `GET /users/oauth/:provider`.
+ *
+ * The missing first half of the OAuth flow whose second half is
+ * `logInOAuth` (`POST /users/log-in/oauth`): generates the CSRF `state` and
+ * a per-session PKCE S256 verifier, stores BOTH in httpOnly cookies (the
+ * exact names + attributes `logInOAuth` reads and clears —
+ * `getAuthCookieName('oauth_state')` / `('oauth_verifier')` with
+ * `getAuthCookieOptions()`), then 302-redirects the browser to the
+ * provider's authorization URL.
+ *
+ * Provider knowledge stays in the bond: the handler asks the bonded OAuth
+ * provider (`get('oauth', :provider)`) for its authorize URL via its
+ * optional `getAuthorizeUrl` builder (see `@molecule/api-oauth`). A
+ * provider that is not bonded, lacks the builder, or is unconfigured
+ * (builder returns `null`, e.g. missing client id) yields a clean 404/503 —
+ * never a crash.
+ *
+ * The `redirect_uri` sent to the provider is `APP_ORIGIN` plus an optional
+ * validated same-origin `redirect_to` path from the query string (the page
+ * that initiated the flow, e.g. `/login`, where the app's OAuth callback
+ * handling is mounted). The path is sanitized so this can never become an
+ * open redirect; the state cookie — not `redirect_uri` — is the CSRF
+ * control.
+ *
+ * @returns A request handler that responds `302` with a `Location` header
+ * pointing at the provider's authorization URL.
+ */
+export const oauthAuthorize = () => {
+    return async (req, res) => {
+        const provider = req.params?.provider;
+        if (!provider) {
+            return {
+                statusCode: 400,
+                body: { error: t('user.error.badRequest'), errorKey: 'user.error.badRequest' },
+            };
+        }
+        const oauthProvider = get('oauth', provider);
+        if (!oauthProvider?.getAuthorizeUrl) {
+            return {
+                statusCode: 404,
+                body: {
+                    error: t('user.error.oauthServerNotConfigured', { server: provider }),
+                    errorKey: 'user.error.oauthServerNotConfigured',
+                },
+            };
+        }
+        // CSRF state — the callback (`logInOAuth`) requires the provider-echoed
+        // `state` to equal this cookie (timing-safe), so a forged cross-site
+        // callback can't plant a session.
+        const state = crypto.randomBytes(32).toString('hex');
+        // Per-request PKCE (S256). The verifier binds the authorization code to
+        // THIS session — the only control that blocks authorization-code
+        // injection (RFC 9700 §2.1); `state` binds the session, NOT the code. The
+        // verifier lives in an httpOnly cookie read SERVER-SIDE by `logInOAuth`,
+        // never exposed to page JavaScript or trusted from the request body.
+        const codeVerifier = crypto.randomBytes(32).toString('base64url');
+        const codeChallenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url');
+        // SET with the exact same name + attribute source `logInOAuth` CLEARS with
+        // (one source of truth — a mismatched attribute leaves an undeletable
+        // cookie): `__Host-` names in production, `SameSite=None; Partitioned` in
+        // the cross-site live preview, plain Lax cookies in top-level dev.
+        const cookieOptions = authorization.getAuthCookieOptions();
+        res.cookie(authorization.getAuthCookieName('oauth_state'), state, {
+            ...cookieOptions,
+            httpOnly: true,
+            maxAge: OAUTH_COOKIE_MAX_AGE_MS,
+        });
+        res.cookie(authorization.getAuthCookieName('oauth_verifier'), codeVerifier, {
+            ...cookieOptions,
+            httpOnly: true,
+            maxAge: OAUTH_COOKIE_MAX_AGE_MS,
+        });
+        // redirect_uri = the app origin + a validated same-origin path. When
+        // APP_ORIGIN is unset, omit redirect_uri entirely so the provider falls
+        // back to its registered callback URL (standard OAuth behavior).
+        const appOrigin = getConfig('APP_ORIGIN', '');
+        const redirectTo = sanitizeRedirectPath(req.query?.redirect_to);
+        const redirectUri = appOrigin ? `${appOrigin}${redirectTo}` : undefined;
+        // Persist the sanitized return path so `logInOAuth` can reconstruct the
+        // IDENTICAL redirect_uri at token exchange — RFC 6749 §4.1.3 requires the
+        // exchange redirect_uri to equal the authorization one byte-for-byte, and
+        // GitHub/Google enforce it (mismatch → `redirect_uri_mismatch`, which used
+        // to sink every flow started from a non-root page like /login). httpOnly +
+        // one-time-use, same cookie contract as oauth_state/oauth_verifier.
+        res.cookie(authorization.getAuthCookieName('oauth_redirect'), redirectTo, {
+            ...cookieOptions,
+            httpOnly: true,
+            maxAge: OAUTH_COOKIE_MAX_AGE_MS,
+        });
+        const authorizeUrl = oauthProvider.getAuthorizeUrl({
+            redirectUri,
+            state,
+            codeChallenge,
+            codeChallengeMethod: 'S256',
+        });
+        if (!authorizeUrl) {
+            // Bonded but unconfigured (e.g. client id env var unset) — an
+            // operator problem, not a client one.
+            return {
+                statusCode: 503,
+                body: {
+                    error: t('user.error.oauthServerNotConfigured', { server: provider }),
+                    errorKey: 'user.error.oauthServerNotConfigured',
+                },
+            };
+        }
+        return {
+            statusCode: 302,
+            headers: { Location: authorizeUrl },
+            body: undefined,
+        };
+    };
+};
+//# sourceMappingURL=oauthAuthorize.js.map

package/dist/handlers/oauthAuthorize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauthAuthorize.js","sourceRoot":"","sources":["../../src/handlers/oauthAuthorize.ts"],"names":[],"mappings":"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"}

package/dist/handlers/payments/handlePaymentNotification.d.ts

@@ -0,0 +1,28 @@
+import type { MoleculeRequest } from '@molecule/api-resource';
+import type * as types from '../../types.js';
+/**
+ * Generic payment notification handler that works with any bonded PaymentProvider. Reads the
+ * provider name from the `:provider` route parameter and dispatches based on `notificationFlow`:
+ * - `'webhook'` (Stripe-style): Calls `handleWebhookEvent()` to parse signed webhook payloads,
+ *   then looks up the user via PaymentRecordService by customer ID.
+ * - Default (Apple/Google-style): Calls `parseNotification()` for server-to-server notifications,
+ *   then looks up the user via PaymentRecordService by transaction ID.
+ *
+ * Updates the user's plan on renewal/change or clears it on cancellation/expiry/refund/revocation.
+ * Always returns 200 to acknowledge receipt.
+ * @param resource - The user resource configuration (name, tableName, schema).
+ * @param resource.name - The resource name.
+ * @param resource.tableName - The database table name for users.
+ * @param resource.schema - The validation schema for user properties.
+ * @returns A request handler for payment provider notifications.
+ */
+export declare const handlePaymentNotification: ({ name, tableName, schema: _schema }: types.Resource) => (req: MoleculeRequest) => Promise<{
+    statusCode: number;
+    body: string;
+} | {
+    statusCode: number;
+    body: {
+        error: string;
+    };
+}>;
+//# sourceMappingURL=handlePaymentNotification.d.ts.map

package/dist/handlers/payments/handlePaymentNotification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlePaymentNotification.d.ts","sourceRoot":"","sources":["../../../src/handlers/payments/handlePaymentNotification.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAI7D,OAAO,KAAK,KAAK,KAAK,MAAM,gBAAgB,CAAA;AA6B5C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,yBAAyB,GAAI,sCAAsC,KAAK,CAAC,QAAQ,MAC9E,KAAK,eAAe;;;;;;;;EA6LnC,CAAA"}

package/dist/handlers/payments/handlePaymentNotification.js

@@ -0,0 +1,217 @@
+import { get, getAnalytics, getLogger } from '@molecule/api-bond';
+import { update as resourceUpdate } from '@molecule/api-resource';
+import { updatePlanPropsSchema } from '../../schema.js';
+import { invalidateEntitlementsCacheSafe } from '../../utilities/invalidateEntitlements.js';
+const analytics = getAnalytics();
+const logger = getLogger();
+/**
+ * Whether a parsed webhook subscription is in a state that should grant/extend
+ * the user's plan.
+ *
+ * Mirrors the verify path (`verifySubscription`): only an active/trialing
+ * subscription confers entitlement. A subscription surfaced as inactive
+ * (`isActive === false`) or with a non-granting status (past_due/unpaid/
+ * incomplete/incomplete_expired) must NOT advance `planExpiresAt` — this blocks
+ * a renewal-payment failure from extending premium for an unpaid cycle. When a
+ * provider surfaces no status at all, prior grant behavior is preserved.
+ * @param subscription - The parsed webhook subscription details.
+ * @returns `true` when the subscription is active/trialing (or status-unknown).
+ */
+const webhookSubscriptionGrantsEntitlement = (subscription) => {
+    if (subscription.isActive === false)
+        return false;
+    if (subscription.status !== undefined) {
+        return subscription.status === 'active' || subscription.status === 'trialing';
+    }
+    return true;
+};
+/**
+ * Generic payment notification handler that works with any bonded PaymentProvider. Reads the
+ * provider name from the `:provider` route parameter and dispatches based on `notificationFlow`:
+ * - `'webhook'` (Stripe-style): Calls `handleWebhookEvent()` to parse signed webhook payloads,
+ *   then looks up the user via PaymentRecordService by customer ID.
+ * - Default (Apple/Google-style): Calls `parseNotification()` for server-to-server notifications,
+ *   then looks up the user via PaymentRecordService by transaction ID.
+ *
+ * Updates the user's plan on renewal/change or clears it on cancellation/expiry/refund/revocation.
+ * Always returns 200 to acknowledge receipt.
+ * @param resource - The user resource configuration (name, tableName, schema).
+ * @param resource.name - The resource name.
+ * @param resource.tableName - The database table name for users.
+ * @param resource.schema - The validation schema for user properties.
+ * @returns A request handler for payment provider notifications.
+ */
+export const handlePaymentNotification = ({ name, tableName, schema: _schema }) => {
+    return async (req) => {
+        const okResponse = { statusCode: 200, body: 'OK' };
+        const providerName = req.params.provider;
+        if (!providerName)
+            return okResponse;
+        try {
+            const provider = get('payments', providerName);
+            if (!provider)
+                return okResponse;
+            const plans = get('plans');
+            if (!plans)
+                return okResponse;
+            const records = get('paymentRecords');
+            // Use the partial plan-props schema, NOT the full user `schema`. The
+            // resource's full schema makes `id`/`createdAt`/`updatedAt` required,
+            // which would reject the partial `{ planKey, planExpiresAt, planAutoRenews }`
+            // payload we want to apply here.
+            const updateUser = resourceUpdate({
+                name,
+                tableName,
+                schema: updatePlanPropsSchema,
+            });
+            const cancelTypes = ['canceled', 'expired', 'refund', 'revoked'];
+            // Dispatch based on notificationFlow (with method-existence fallback).
+            if (provider.notificationFlow === 'webhook' ||
+                (!provider.notificationFlow && provider.handleWebhookEvent)) {
+                // Stripe-style: signed webhook with event type in payload.
+                if (!provider.handleWebhookEvent)
+                    return okResponse;
+                const event = await provider.handleWebhookEvent(req);
+                if (!event) {
+                    return { statusCode: 400, body: { error: 'Invalid webhook event' } };
+                }
+                const subscription = event.subscription;
+                if (!subscription?.customerId)
+                    return okResponse;
+                // Find user by customer ID via PaymentRecordService.
+                const payment = records
+                    ? await records.findByCustomerData(providerName, 'customerId', subscription.customerId)
+                    : null;
+                if (!payment) {
+                    logger.error(`${providerName} webhook: no user found for customer ${subscription.customerId}`);
+                    return okResponse;
+                }
+                // Providers report the parent PRODUCT id on subscriptions, but apps
+                // register their catalogue with PRICE ids — try both.
+                const plan = (subscription.productId ? plans.findPlanByProductId(subscription.productId) : null) ??
+                    (subscription.priceId ? plans.findPlanByProductId(subscription.priceId) : null);
+                analytics
+                    .track({
+                    name: 'payment.notification_received',
+                    userId: payment.userId,
+                    properties: { provider: providerName, type: event.type },
+                })
+                    .catch(() => { });
+                if (cancelTypes.includes(event.type)) {
+                    await updateUser({
+                        id: payment.userId,
+                        props: {
+                            planKey: '',
+                            planAutoRenews: false,
+                        },
+                    });
+                    // Drop the cached plan key so the revocation takes effect
+                    // immediately, not after the entitlements cache TTL.
+                    invalidateEntitlementsCacheSafe(payment.userId);
+                    analytics
+                        .track({
+                        name: 'payment.subscription_canceled',
+                        userId: payment.userId,
+                        properties: { provider: providerName, type: event.type },
+                    })
+                        .catch(() => { });
+                }
+                else if (plan && webhookSubscriptionGrantsEntitlement(subscription)) {
+                    await updateUser({
+                        id: payment.userId,
+                        props: {
+                            planKey: plan.planKey,
+                            planExpiresAt: subscription.expiresAt,
+                            planAutoRenews: subscription.autoRenews,
+                        },
+                    });
+                    // Drop the cached plan key so the grant/renewal takes effect
+                    // immediately, not after the entitlements cache TTL.
+                    invalidateEntitlementsCacheSafe(payment.userId);
+                    analytics
+                        .track({
+                        name: 'payment.subscription_renewed',
+                        userId: payment.userId,
+                        properties: { provider: providerName, planKey: plan.planKey },
+                    })
+                        .catch(() => { });
+                }
+                else if (plan) {
+                    // A plan exists but the subscription is not in a granting state
+                    // (past_due/unpaid/incomplete/incomplete_expired) — e.g. a renewal
+                    // payment failed. Mirror `verifySubscription`: do NOT advance
+                    // planExpiresAt; leave the existing entitlement to lapse naturally.
+                    // Cancellation events are handled by the cancelTypes branch above.
+                    logger.info(`${providerName} webhook: subscription for user ${payment.userId} is not active ` +
+                        `(status=${subscription.status ?? 'unknown'}) — not extending entitlement`);
+                }
+                return okResponse;
+            }
+            // Apple/Google-style: server-to-server notification.
+            if (!provider.parseNotification)
+                return okResponse;
+            const notification = await provider.parseNotification(req.body);
+            if (!notification?.transactionId)
+                return okResponse;
+            // Find existing payment by transaction ID via PaymentRecordService.
+            const existingPayment = records
+                ? await records.findByTransaction(providerName, notification.transactionId)
+                : null;
+            if (!existingPayment)
+                return okResponse;
+            analytics
+                .track({
+                name: 'payment.notification_received',
+                userId: existingPayment.userId,
+                properties: { provider: providerName, type: notification.type },
+            })
+                .catch(() => { });
+            const plan = notification.productId ? plans.findPlanByProductId(notification.productId) : null;
+            if (cancelTypes.includes(notification.type)) {
+                await updateUser({
+                    id: existingPayment.userId,
+                    props: {
+                        planKey: '',
+                        planAutoRenews: false,
+                    },
+                });
+                // Drop the cached plan key so the revocation takes effect
+                // immediately, not after the entitlements cache TTL.
+                invalidateEntitlementsCacheSafe(existingPayment.userId);
+                analytics
+                    .track({
+                    name: 'payment.subscription_canceled',
+                    userId: existingPayment.userId,
+                    properties: { provider: providerName, type: notification.type },
+                })
+                    .catch(() => { });
+            }
+            else if (plan && notification.expiresAt) {
+                await updateUser({
+                    id: existingPayment.userId,
+                    props: {
+                        planKey: plan.planKey,
+                        planExpiresAt: notification.expiresAt,
+                        planAutoRenews: notification.autoRenews ?? true,
+                    },
+                });
+                // Drop the cached plan key so the grant/renewal takes effect
+                // immediately, not after the entitlements cache TTL.
+                invalidateEntitlementsCacheSafe(existingPayment.userId);
+                analytics
+                    .track({
+                    name: 'payment.subscription_renewed',
+                    userId: existingPayment.userId,
+                    properties: { provider: providerName, planKey: plan.planKey },
+                })
+                    .catch(() => { });
+            }
+            return okResponse;
+        }
+        catch (error) {
+            logger.error(`${providerName} handlePaymentNotification error:`, error);
+            return okResponse;
+        }
+    };
+};
+//# sourceMappingURL=handlePaymentNotification.js.map

package/dist/handlers/payments/handlePaymentNotification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlePaymentNotification.js","sourceRoot":"","sources":["../../../src/handlers/payments/handlePaymentNotification.ts"],"names":[],"mappings":"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"}

package/dist/handlers/payments/registry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Payment handler registry.
+ *
+ * Exports generic payment handlers that work with any bonded payment
+ * provider via route parameters. No static imports of provider-specific
+ * code needed — adding a new payment provider requires only a new bond
+ * package and a registry entry.
+ *
+ * @module
+ */
+export { handlePaymentNotification } from './handlePaymentNotification.js';
+export { verifyPayment } from './verifyPayment.js';
+//# sourceMappingURL=registry.d.ts.map

package/dist/handlers/payments/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/handlers/payments/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAA;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/handlers/payments/registry.js

@@ -0,0 +1,13 @@
+/**
+ * Payment handler registry.
+ *
+ * Exports generic payment handlers that work with any bonded payment
+ * provider via route parameters. No static imports of provider-specific
+ * code needed — adding a new payment provider requires only a new bond
+ * package and a registry entry.
+ *
+ * @module
+ */
+export { handlePaymentNotification } from './handlePaymentNotification.js';
+export { verifyPayment } from './verifyPayment.js';
+//# sourceMappingURL=registry.js.map

package/dist/handlers/payments/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/handlers/payments/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAA;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/handlers/payments/verifyPayment.d.ts

@@ -0,0 +1,37 @@
+import type { MoleculeRequest } from '@molecule/api-resource';
+import type * as types from '../../types.js';
+/**
+ * Generic payment verification handler that works with any bonded PaymentProvider. Reads the
+ * provider name from the `:provider` route parameter and dispatches based on `verifyFlow`:
+ * - `'subscription'` (Stripe-style): Calls `verifySubscription(subscriptionId)`.
+ * - Default (Apple/Google-style): Calls `verifyReceipt()` or `verifyPurchase()` with a receipt
+ *   string and the plan's platform product ID.
+ *
+ * On successful verification, updates the user's plan (planKey, planExpiresAt, planAutoRenews)
+ * and stores the payment record via the bonded PaymentRecordService.
+ * @param resource - The user resource configuration (name, tableName, schema).
+ * @param resource.name - The resource name.
+ * @param resource.tableName - The database table name for users.
+ * @param resource.schema - The validation schema for user properties.
+ * @returns A request handler for payment verification.
+ */
+export declare const verifyPayment: ({ name, tableName, schema: _schema }: types.Resource) => (req: MoleculeRequest) => Promise<{
+    statusCode: number;
+    body: {
+        error: string;
+        errorKey: string;
+        props?: undefined;
+    };
+} | {
+    statusCode: number;
+    body: {
+        props: Pick<import("@molecule/api-resource/types").Props, "updatedAt"> & {
+            planKey?: string | undefined;
+            planExpiresAt?: string | undefined;
+            planAutoRenews?: boolean | undefined;
+        };
+        error?: undefined;
+        errorKey?: undefined;
+    };
+}>;
+//# sourceMappingURL=verifyPayment.d.ts.map

package/dist/handlers/payments/verifyPayment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifyPayment.d.ts","sourceRoot":"","sources":["../../../src/handlers/payments/verifyPayment.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAI7D,OAAO,KAAK,KAAK,KAAK,MAAM,gBAAgB,CAAA;AAM5C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,GAAI,sCAAsC,KAAK,CAAC,QAAQ,MAClE,KAAK,eAAe;;;;;aAGlB,CAAC;;;;;;;;;;;;;EAoZlB,CAAA"}