@molecule/api-resource-user 1.0.0

package/dist/handlers/updatePlan.js

@@ -0,0 +1,242 @@
+import { get, getAnalytics, getLogger } from '@molecule/api-bond';
+import { findById } from '@molecule/api-database';
+import { t } from '@molecule/api-i18n';
+import { isConfigNotConfiguredError, } from '@molecule/api-payments';
+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();
+/**
+ * Updates a user's subscription plan. Uses the bonded PlanService to look up plan metadata and
+ * delegates to the appropriate bonded PaymentProvider based on the plan's `platformKey`. Handles
+ * cross-platform subscription cancellation when switching providers. Returns a checkout URL
+ * (status 201) for new subscriptions, or directly updates the user record for in-place changes
+ * and free plan downgrades.
+ * @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 plan updates.
+ */
+export const updatePlan = ({ name, tableName, schema: _schema }) => {
+    const updateResource = resourceUpdate({
+        name,
+        tableName,
+        schema: updatePlanPropsSchema,
+    });
+    return async (req) => {
+        try {
+            const id = req.params.id;
+            const { planKey } = req.body;
+            if (!planKey && planKey !== '') {
+                return {
+                    statusCode: 400,
+                    body: { error: t('user.error.planKeyRequired'), errorKey: 'user.error.planKeyRequired' },
+                };
+            }
+            // Get the user.
+            const user = await findById(tableName, id);
+            if (!user) {
+                return {
+                    statusCode: 404,
+                    body: { error: t('user.error.notFound'), errorKey: 'user.error.notFound' },
+                };
+            }
+            // Try to get plans from bond.
+            const plans = get('plans');
+            if (plans) {
+                const plan = plans.findPlan(planKey);
+                const previousPlan = plans.findPlan(user.planKey || '');
+                if (!plan) {
+                    return {
+                        statusCode: 400,
+                        body: { error: t('user.error.invalidPlan'), errorKey: 'user.error.invalidPlan' },
+                    };
+                }
+                // If switching away from a different platform, cancel the previous subscription.
+                if (previousPlan &&
+                    previousPlan.platformKey &&
+                    previousPlan.platformKey !== plan.platformKey) {
+                    const previousProvider = get('payments', previousPlan.platformKey);
+                    if (previousProvider?.cancelSubscription) {
+                        await previousProvider.cancelSubscription({ userId: user.id });
+                    }
+                }
+                // Delegate to platform-specific payment provider if available.
+                if (plan.platformKey) {
+                    const paymentProvider = get('payments', plan.platformKey);
+                    if (paymentProvider?.updateSubscription) {
+                        const result = await paymentProvider.updateSubscription({
+                            userId: user.id,
+                            newProductId: plan.platformProductId,
+                            previousProductId: previousPlan?.platformProductId,
+                        });
+                        if (result.checkoutUrl) {
+                            // New subscription requires checkout — return the URL to the client.
+                            analytics
+                                .track({
+                                name: 'user.plan_checkout_created',
+                                userId: id,
+                                properties: {
+                                    previousPlanKey: previousPlan?.planKey,
+                                    newPlanKey: plan.planKey,
+                                    platformKey: plan.platformKey,
+                                },
+                            })
+                                .catch(() => { });
+                            return { statusCode: 201, body: { checkoutUrl: result.checkoutUrl } };
+                        }
+                        if (result.updated) {
+                            // Subscription was updated in-place — update the user record.
+                            analytics
+                                .track({
+                                name: 'user.plan_updated',
+                                userId: id,
+                                properties: {
+                                    previousPlanKey: previousPlan?.planKey,
+                                    newPlanKey: plan.planKey,
+                                    platformKey: plan.platformKey,
+                                },
+                            })
+                                .catch(() => { });
+                            const updated = await updateResource({
+                                id,
+                                props: {
+                                    planKey: plan.planKey,
+                                    planExpiresAt: result.subscription?.expiresAt,
+                                    planAutoRenews: result.subscription?.autoRenews,
+                                },
+                            });
+                            // Drop the cached plan key so the plan change takes effect
+                            // immediately, not after the entitlements cache TTL.
+                            invalidateEntitlementsCacheSafe(id);
+                            return updated;
+                        }
+                        analytics
+                            .track({
+                            name: 'user.plan_update_failed',
+                            userId: id,
+                            properties: {
+                                previousPlanKey: previousPlan?.planKey,
+                                newPlanKey: plan.planKey,
+                                platformKey: plan.platformKey,
+                            },
+                        })
+                            .catch(() => { });
+                        return {
+                            statusCode: 400,
+                            body: {
+                                error: t('user.error.failedToUpdateSubscription'),
+                                errorKey: 'user.error.failedToUpdateSubscription',
+                            },
+                        };
+                    }
+                    // The plan is tied to a payment platform, but the bonded provider has
+                    // no in-place `updateSubscription` (e.g. Apple/Google receipt-only
+                    // providers). NEVER direct-set a paid planKey without a positive
+                    // provider confirmation — activation MUST go through receipt
+                    // verification (POST /users/:id/verify-payment/:provider). Falling
+                    // through here previously let a user self-grant a paid (Pro) plan with
+                    // no payment.
+                    return {
+                        statusCode: 400,
+                        body: {
+                            error: t('user.error.subscriptionActivationRequiresVerification', undefined, {
+                                defaultValue: 'Subscription activation must go through receipt verification — use POST /users/:id/verify-payment/:provider.',
+                            }),
+                            errorKey: 'user.error.subscriptionActivationRequiresVerification',
+                        },
+                    };
+                }
+                // No platform handler — free-plan downgrade only.
+                if (plan.planKey === '') {
+                    // Switching to free plan. Keep current planKey if subscription hasn't expired yet.
+                    const now = new Date().getTime();
+                    const expires = new Date(user.planExpiresAt || 0).getTime();
+                    analytics
+                        .track({
+                        name: 'user.plan_updated',
+                        userId: id,
+                        properties: { previousPlanKey: previousPlan?.planKey, newPlanKey: '' },
+                    })
+                        .catch(() => { });
+                    const downgraded = await updateResource({
+                        id,
+                        props: {
+                            planKey: now > expires ? plan.planKey : (user.planKey ?? plan.planKey),
+                            planAutoRenews: false,
+                        },
+                    });
+                    // Drop the cached plan key so the downgrade takes effect
+                    // immediately, not after the entitlements cache TTL.
+                    invalidateEntitlementsCacheSafe(id);
+                    return downgraded;
+                }
+                // A non-free plan with NO payment platform handler cannot be confirmed
+                // by any provider — refuse to grant it. Only the free plan ('') may be
+                // written without provider confirmation (handled above); every paid
+                // planKey must go through a provider `updateSubscription`
+                // (checkout/in-place) or receipt verification
+                // (POST /users/:id/verify-payment/:provider). This closes the
+                // self-grant escalation where a user PATCHed a paid planKey directly.
+                return {
+                    statusCode: 400,
+                    body: {
+                        error: t('user.error.subscriptionActivationRequiresVerification', undefined, {
+                            defaultValue: 'Subscription activation must go through receipt verification — use POST /users/:id/verify-payment/:provider.',
+                        }),
+                        errorKey: 'user.error.subscriptionActivationRequiresVerification',
+                    },
+                };
+            }
+            // No plans service bonded — only allow downgrade to free plan.
+            // Upgrades MUST go through a bonded PlanService + PaymentProvider to prevent
+            // privilege escalation (users setting planKey to a paid tier without payment).
+            if (planKey !== '') {
+                return {
+                    statusCode: 400,
+                    body: {
+                        error: t('user.error.failedToUpdatePlan'),
+                        errorKey: 'user.error.failedToUpdatePlan',
+                    },
+                };
+            }
+            analytics
+                .track({
+                name: 'user.plan_updated',
+                userId: id,
+                properties: { newPlanKey: planKey },
+            })
+                .catch(() => { });
+            const result = await updateResource({ id, props: { planKey, planAutoRenews: false } });
+            // Drop the cached plan key so the downgrade takes effect immediately,
+            // not after the entitlements cache TTL.
+            invalidateEntitlementsCacheSafe(id);
+            return result;
+        }
+        catch (error) {
+            // A bonded payment provider rethrows a tagged config-not-configured
+            // error (e.g. STRIPE_SECRET_KEY unset) instead of swallowing it — pass
+            // its REAL statusCode/errorKey through instead of flattening it to a
+            // generic 500. Otherwise a missing secret is indistinguishable from an
+            // unexpected server error at the exact moment a user tries to upgrade.
+            if (isConfigNotConfiguredError(error)) {
+                logger.warn(error.message, { errorKey: error.errorKey });
+                return {
+                    statusCode: error.statusCode,
+                    body: { error: error.message, errorKey: error.errorKey },
+                };
+            }
+            logger.error(error);
+            return {
+                statusCode: 500,
+                body: {
+                    error: t('user.error.failedToUpdatePlan'),
+                    errorKey: 'user.error.failedToUpdatePlan',
+                },
+            };
+        }
+    };
+};
+//# sourceMappingURL=updatePlan.js.map

package/dist/handlers/updatePlan.js.map

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

package/dist/handlers/verifyTwoFactor.d.ts

@@ -0,0 +1,46 @@
+import type { MoleculeRequest } from '@molecule/api-resource';
+import type * as types from '../types.js';
+/** Request body for two-factor authentication operations (setup, enable, or disable). */
+export interface VerifyTwoFactorRequest extends MoleculeRequest {
+    body: {
+        token?: string;
+        action?: 'setup' | 'enable' | 'disable';
+    };
+}
+/**
+ * Handles two-factor authentication lifecycle via `@molecule/api-two-factor`:
+ * - `setup`: Generates a TOTP secret and returns QR code URLs for authenticator apps.
+ * - `enable`: Verifies a TOTP token against the pending secret, then activates 2FA.
+ * - `disable`: Verifies a TOTP token against the active secret, then deactivates 2FA.
+ * @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 two-factor authentication operations.
+ */
+export declare const verifyTwoFactor: ({ name: _name, tableName, schema: _schema }: types.Resource) => (req: VerifyTwoFactorRequest) => Promise<{
+    statusCode: number;
+    body: {
+        error: string;
+        errorKey: string;
+        twoFactorEnabled?: undefined;
+    };
+} | {
+    statusCode: number;
+    body: {
+        secret: string;
+        keyUrl: string;
+        QRImageUrl: string;
+        error?: undefined;
+        errorKey?: undefined;
+        twoFactorEnabled?: undefined;
+    };
+} | {
+    statusCode: number;
+    body: {
+        twoFactorEnabled: boolean;
+        error?: undefined;
+        errorKey?: undefined;
+    };
+}>;
+//# sourceMappingURL=verifyTwoFactor.d.ts.map

package/dist/handlers/verifyTwoFactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifyTwoFactor.d.ts","sourceRoot":"","sources":["../../src/handlers/verifyTwoFactor.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D,OAAO,KAAK,KAAK,KAAK,MAAM,aAAa,CAAA;AAKzC,yFAAyF;AACzF,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC7D,IAAI,EAAE;QACJ,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAA;KACxC,CAAA;CACF;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAAI,6CAA6C,KAAK,CAAC,QAAQ,MAC3E,KAAK,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;EAsK1C,CAAA"}

package/dist/handlers/verifyTwoFactor.js

@@ -0,0 +1,162 @@
+import { getAnalytics, getLogger } from '@molecule/api-bond';
+import { get } from '@molecule/api-config';
+import { findById, updateById } from '@molecule/api-database';
+import { t } from '@molecule/api-i18n';
+const analytics = getAnalytics();
+const logger = getLogger();
+/**
+ * Handles two-factor authentication lifecycle via `@molecule/api-two-factor`:
+ * - `setup`: Generates a TOTP secret and returns QR code URLs for authenticator apps.
+ * - `enable`: Verifies a TOTP token against the pending secret, then activates 2FA.
+ * - `disable`: Verifies a TOTP token against the active secret, then deactivates 2FA.
+ * @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 two-factor authentication operations.
+ */
+export const verifyTwoFactor = ({ name: _name, tableName, schema: _schema }) => {
+    return async (req) => {
+        try {
+            const id = req.params.id;
+            const { token, action } = req.body;
+            // Get user secrets.
+            const secrets = await findById(`${tableName}Secrets`, id);
+            if (!secrets) {
+                return {
+                    statusCode: 404,
+                    body: { error: t('user.error.notFound'), errorKey: 'user.error.notFound' },
+                };
+            }
+            const twoFactor = await import('@molecule/api-two-factor').catch(() => null);
+            if (!twoFactor) {
+                return {
+                    statusCode: 500,
+                    body: {
+                        error: t('user.error.twoFactorNotAvailable'),
+                        errorKey: 'user.error.twoFactorNotAvailable',
+                    },
+                };
+            }
+            if (action === 'setup') {
+                // Generate a new secret and return QR code.
+                const secret = twoFactor.generateSecret();
+                // Store as pending secret.
+                await updateById(`${tableName}Secrets`, id, { pendingTwoFactorSecret: secret });
+                const appName = get('APP_NAME', 'App') ?? 'App';
+                const user = await findById(tableName, id);
+                const urls = await twoFactor.getUrls({
+                    username: user?.username || id,
+                    service: appName,
+                    secret,
+                });
+                return { statusCode: 200, body: { ...urls, secret } };
+            }
+            if (action === 'enable') {
+                if (!token) {
+                    return {
+                        statusCode: 400,
+                        body: { error: t('user.error.tokenRequired'), errorKey: 'user.error.tokenRequired' },
+                    };
+                }
+                if (!secrets.pendingTwoFactorSecret) {
+                    return {
+                        statusCode: 400,
+                        body: {
+                            error: t('user.error.noPendingTwoFactorSetup'),
+                            errorKey: 'user.error.noPendingTwoFactorSetup',
+                        },
+                    };
+                }
+                // Verify the token against the pending secret.
+                const verifyResult = await twoFactor.verify({
+                    secret: secrets.pendingTwoFactorSecret,
+                    token,
+                    // Reject a code whose time step was already consumed (replay protection).
+                    afterTimeStep: secrets.lastTwoFactorTimeStep,
+                });
+                if (!verifyResult.valid) {
+                    return {
+                        statusCode: 403,
+                        body: { error: t('user.error.invalidToken'), errorKey: 'user.error.invalidToken' },
+                    };
+                }
+                // Move pending secret to active and enable 2FA. Persist the consumed
+                // time step so the enabling code can't be replayed (single-use).
+                await updateById(`${tableName}Secrets`, id, {
+                    twoFactorSecret: secrets.pendingTwoFactorSecret,
+                    pendingTwoFactorSecret: null,
+                    ...(verifyResult.timeStep !== undefined
+                        ? { lastTwoFactorTimeStep: verifyResult.timeStep }
+                        : {}),
+                });
+                await updateById(tableName, id, {
+                    twoFactorEnabled: true,
+                    updatedAt: new Date().toISOString(),
+                });
+                analytics.track({ name: 'user.two_factor_enabled', userId: id }).catch(() => { });
+                return { statusCode: 200, body: { twoFactorEnabled: true } };
+            }
+            if (action === 'disable') {
+                if (!token) {
+                    return {
+                        statusCode: 400,
+                        body: { error: t('user.error.tokenRequired'), errorKey: 'user.error.tokenRequired' },
+                    };
+                }
+                if (!secrets.twoFactorSecret) {
+                    return {
+                        statusCode: 400,
+                        body: {
+                            error: t('user.error.twoFactorNotEnabled'),
+                            errorKey: 'user.error.twoFactorNotEnabled',
+                        },
+                    };
+                }
+                // Verify the token against the current secret.
+                const verifyResult = await twoFactor.verify({
+                    secret: secrets.twoFactorSecret,
+                    token,
+                    // Reject a code whose time step was already consumed (replay protection).
+                    afterTimeStep: secrets.lastTwoFactorTimeStep,
+                });
+                if (!verifyResult.valid) {
+                    return {
+                        statusCode: 403,
+                        body: { error: t('user.error.invalidToken'), errorKey: 'user.error.invalidToken' },
+                    };
+                }
+                // Disable 2FA. Persist the consumed time step so the disabling code
+                // can't be replayed (single-use) within its validity window.
+                await updateById(`${tableName}Secrets`, id, {
+                    twoFactorSecret: null,
+                    pendingTwoFactorSecret: null,
+                    ...(verifyResult.timeStep !== undefined
+                        ? { lastTwoFactorTimeStep: verifyResult.timeStep }
+                        : {}),
+                });
+                await updateById(tableName, id, {
+                    twoFactorEnabled: false,
+                    updatedAt: new Date().toISOString(),
+                });
+                analytics.track({ name: 'user.two_factor_disabled', userId: id }).catch(() => { });
+                return { statusCode: 200, body: { twoFactorEnabled: false } };
+            }
+            return {
+                statusCode: 400,
+                body: { error: t('user.error.invalidAction'), errorKey: 'user.error.invalidAction' },
+            };
+        }
+        catch (error) {
+            logger.error(error);
+            return {
+                statusCode: 500,
+                body: {
+                    error: t('user.error.twoFactorOperationFailed'),
+                    errorKey: 'user.error.twoFactorOperationFailed',
+                },
+            };
+        }
+    };
+};
+//# sourceMappingURL=verifyTwoFactor.js.map

package/dist/handlers/verifyTwoFactor.js.map

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

package/dist/i18n.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Locale registration for the user resource.
+ *
+ * @module
+ */
+/**
+ * The i18n registered.
+ */
+export declare const i18nRegistered = true;
+//# sourceMappingURL=i18n.d.ts.map

package/dist/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH;;GAEG;AACH,eAAO,MAAM,cAAc,OAAO,CAAA"}

package/dist/i18n.js

@@ -0,0 +1,25 @@
+/**
+ * Locale registration for the user resource.
+ *
+ * @module
+ */
+import { registerLocaleModule } from '@molecule/api-i18n';
+try {
+    const userLocales = await import('@molecule/api-locales-user');
+    registerLocaleModule(userLocales);
+}
+catch (_error) {
+    // Locale package not available (not built or not installed).
+}
+try {
+    const paymentLocales = await import('@molecule/api-locales-user-payments');
+    registerLocaleModule(paymentLocales);
+}
+catch (_error) {
+    // Locale package not available (not built or not installed).
+}
+/**
+ * The i18n registered.
+ */
+export const i18nRegistered = true;
+//# sourceMappingURL=i18n.js.map

package/dist/i18n.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.js","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAEzD,IAAI,CAAC;IACH,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,4BAA4B,CAAC,CAAA;IAC9D,oBAAoB,CAAC,WAAW,CAAC,CAAA;AACnC,CAAC;AAAC,OAAO,MAAM,EAAE,CAAC;IAChB,6DAA6D;AAC/D,CAAC;AAED,IAAI,CAAC;IACH,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC,qCAAqC,CAAC,CAAA;IAC1E,oBAAoB,CAAC,cAAc,CAAC,CAAA;AACtC,CAAC;AAAC,OAAO,MAAM,EAAE,CAAC;IAChB,6DAA6D;AAC/D,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The `user` resource types, schema, and definition.
+ *
+ * @remarks
+ * The user record is split across TWO schemas — pick the right one or you leak credentials:
+ * - **{@link Props} (`propsSchema`)** — SAFE, client-facing fields (username, name, email,
+ *   `emailVerified`, `twoFactorEnabled`, plan). This is what handlers return and what lives
+ *   in the `users` table.
+ * - **{@link SecretProps} (`secretPropsSchema`)** — SERVER-ONLY secrets: `passwordHash`, the
+ *   TOTP `twoFactorSecret` (and its pending-setup value). Stored in a SEPARATE secrets table
+ *   and NEVER serialized to the client. Note the pair `twoFactorEnabled` (safe boolean, in
+ *   `Props`) vs `twoFactorSecret` (secret, in `SecretProps`).
+ *
+ * When you extend the user, put a secret (token, hash, key, provider refresh token) in
+ * `SecretProps`; put a display field in `Props`. **Never add a secret to `Props`, never
+ * return a secrets-table value in a response or log, and never `res.json(userRow)` a raw DB
+ * row** — return `Props`.
+ *
+ * Auth is ALREADY wired globally (the router's `verifyMiddleware` → `res.locals.session`),
+ * so a handler reads the current user with `getUserId(res)` and does NOT add per-route auth
+ * middleware (see the `auth` skill). Scope every custom user query by the authenticated id.
+ *
+ * On the CLIENT, the bearer token is held IN MEMORY only — a `localStorage` copy is
+ * XSS-exfiltratable and is forbidden. The session is restored after a reload via the
+ * httpOnly cookie + `GET /users/me`; don't persist the token yourself.
+ *
+ * **Client-facing endpoints** (mounted under the app's `/api` prefix → `/api/users/...`).
+ * The auth CLIENT (`useAuth()` → `login` / `register` / `logout` / `refresh`) already wraps
+ * login / signup / logout — do NOT hand-roll those against the raw routes. The rest have NO
+ * client method; call them with raw `http.*`. Use these EXACT paths — a weak model guesses
+ * `/api/auth/*` or `/api/user` (singular), and neither exists:
+ * - `POST   /api/users/forgot-password` — request a reset email (body `{ email }`)
+ * - `POST   /api/users/reset-password` — confirm with the emailed token (body `{ token, password }`)
+ * - `PATCH  /api/users/:id` — update profile fields (name, username, email, bio); NOT `PUT /api/user`
+ * - `PATCH  /api/users/:id/password` — change password · `DELETE /api/users/:id` — delete account
+ * - `PATCH  /api/users/:id/plan` — update the subscription plan
+ * - `GET    /api/users/me` — the current user (session restore) · `GET /api/users/:id` — read one
+ * The full, authoritative route list is the `routes` export (see `routes.ts`).
+ *
+ * @example
+ * ```ts
+ * // Extend safely: a display field in Props, a secret in SecretProps.
+ * //   propsSchema:       { …, timezone: z.string().optional() }           // safe → client
+ * //   secretPropsSchema: { …, passwordResetToken: z.string().optional() } // server-only, secrets table
+ *
+ * // A custom handler returns SAFE props — never the secrets row.
+ * router.get('/me/timezone', async (req, res) => {
+ *   const userId = getUserId(res)
+ *   if (!userId) return res.status(401).json({ error: 'Authentication required.' })
+ *   const user = await findById('users', userId) // the users table holds Props only
+ *   res.json({ timezone: user?.timezone })        // never spread a secrets-table row here
+ * })
+ * ```
+ *
+ * @e2e
+ * Integration checklist — drive the real UI (live preview, no mocks), adapt
+ * each item to this app's actual screens/flows, and check every box off one
+ * by one. A box you can't check is an integration bug to fix — not a skip:
+ * - [ ] A new user can sign up with email + password and lands authenticated (the
+ *   UI reflects the signed-in user, e.g. their name/menu appears).
+ * - [ ] Any flow that emails a link/code (signup verification, password reset)
+ *   round-trips: the sandbox CAPTURES the message instead of sending — read it
+ *   with the `read_activity` tool (filter type 'email') and follow the link/code
+ *   in its payload; never mock the flow or modify production code to expose it.
+ * - [ ] Logging out and logging back in with the same credentials reaches the same
+ *   account and its data.
+ * - [ ] The session survives a full page reload (restored via the httpOnly cookie +
+ *   `GET /users/me` — never from a token persisted in localStorage).
+ * - [ ] A wrong password shows a visible error and does NOT authenticate.
+ * - [ ] Authenticated-only screens are unreachable when logged out (redirect to
+ *   login or an explicit denial — never a blank page).
+ * - [ ] A profile/account edit (e.g. display name) persists across a reload.
+ *
+ * @module
+ */
+export * as authorization from './authorization.js';
+export * as authorizers from './authorizers/index.js';
+export * from './browser-guard.js';
+export * as handlers from './handlers/index.js';
+export * from './i18n.js';
+export * from './requestHandlerMap.js';
+export * from './resource.js';
+export * from './routes.js';
+export * from './schema.js';
+export * from './secrets.js';
+export * as types from './types.js';
+export * as utilities from './utilities/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAA;AACnD,OAAO,KAAK,WAAW,MAAM,wBAAwB,CAAA;AACrD,cAAc,oBAAoB,CAAA;AAClC,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAA;AAC/C,cAAc,WAAW,CAAA;AACzB,cAAc,wBAAwB,CAAA;AACtC,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAA"}