@prefabs.tech/fastify-phone-auth 0.0.0-stage → 0.95.1

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# @prefabs.tech/fastify-phone-auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [Fastify](https://github.com/fastify/fastify) plugin that adds phone/SMS OTP passwordless login to an API built on [@prefabs.tech/fastify-user](../user/), backed by the [Twilio Verify](https://www.twilio.com/docs/verify) API.
+
+## Why this plugin?
+
+SuperTokens ships a Passwordless recipe, but wiring it to Twilio Verify and to your own `users` table is a surprising amount of work — SuperTokens wants to own the OTP, Twilio Verify wants to own the OTP, and neither knows about your database. This plugin exists to:
+
+- **Bridge SuperTokens and Twilio Verify**: Twilio Verify generates, delivers and checks the real OTP; SuperTokens is handed a placeholder code so its own flow still completes. All of that is hidden behind one plugin registration.
+- **Keep the auth package lean**: passwordless is opt-in. Apps that do not use it never install `twilio`, and `@prefabs.tech/fastify-user` carries no passwordless config surface.
+- **Initialise the recipe automatically**: registering this plugin is all it takes — the SuperTokens Passwordless recipe is contributed to `@prefabs.tech/fastify-user`'s recipe list for you.
+- **Create the local user row**: on first sign-in a matching row is created in your `users` table with the phone number and a synthetic `<phoneNumber>@<fallbackEmailDomain>` email, since SuperTokens requires an email.
+- **Own the `phone_number` column**: an idempotent migration adds it to the users table, the `User` type from `@prefabs.tech/fastify-user` is augmented with `phoneNumber?: string`, and the GraphQL `User` type is extended at runtime — no wiring on your side.
+- **Support local development without Twilio**: a dev mode and a per-number bypass list accept a fixed OTP so you can develop and test without sending real SMS.
+
+## Requirements
+
+Peer dependencies (install compatible versions — see [package.json](./package.json)):
+
+- [@prefabs.tech/fastify-config](../config/)
+- [@prefabs.tech/fastify-error-handler](../error-handler/)
+- [@prefabs.tech/fastify-slonik](../slonik/)
+- [@prefabs.tech/fastify-user](../user/)
+- [`fastify`](https://www.npmjs.com/package/fastify)
+- [`fastify-plugin`](https://www.npmjs.com/package/fastify-plugin)
+- [`slonik`](https://www.npmjs.com/package/slonik)
+- [`supertokens-node`](https://www.npmjs.com/package/supertokens-node)
+
+## Installation
+
+Install with npm:
+
+```bash
+npm install @prefabs.tech/fastify-config @prefabs.tech/fastify-error-handler @prefabs.tech/fastify-slonik @prefabs.tech/fastify-user @prefabs.tech/fastify-phone-auth fastify fastify-plugin slonik supertokens-node
+```
+
+Install with pnpm:
+
+```bash
+pnpm add --filter "@scope/project" @prefabs.tech/fastify-config @prefabs.tech/fastify-error-handler @prefabs.tech/fastify-slonik @prefabs.tech/fastify-user @prefabs.tech/fastify-phone-auth fastify fastify-plugin slonik supertokens-node
+```
+
+## Usage
+
+### Register the plugin — before `@prefabs.tech/fastify-user`
+
+SuperTokens allows exactly one global `init()`, and `@prefabs.tech/fastify-user` performs it while it is being registered. This plugin therefore has to be registered **first**, so its recipe is in the list by the time that happens.
+
+```typescript
+import configPlugin from "@prefabs.tech/fastify-config";
+import phoneAuthPlugin from "@prefabs.tech/fastify-phone-auth";
+import slonikPlugin from "@prefabs.tech/fastify-slonik";
+import userPlugin from "@prefabs.tech/fastify-user";
+import Fastify from "fastify";
+
+const fastify = Fastify();
+
+await fastify.register(configPlugin, { config });
+await fastify.register(slonikPlugin);
+await fastify.register(phoneAuthPlugin); // contributes the recipe
+await fastify.register(userPlugin); // runs supertokens.init()
+```
+
+Registering it after `@prefabs.tech/fastify-user` throws:
+
+```
+SuperTokens is already initialised. Register SuperTokens recipe plugins before @prefabs.tech/fastify-user.
+```
+
+### Configuration
+
+```typescript
+const config: ApiConfig = {
+  // ...
+  phoneAuth: {
+    fallbackEmailDomain: "example.com",
+    twilio: {
+      accountSid: process.env.TWILIO_ACCOUNT_SID,
+      authToken: process.env.TWILIO_AUTH_TOKEN,
+      verifyServiceSid: process.env.TWILIO_VERIFY_SERVICE_SID,
+    },
+  },
+};
+```
+
+For local development, skip Twilio entirely:
+
+```typescript
+phoneAuth: {
+  devModeOtp: "123456",
+  enableDevMode: true,
+  fallbackEmailDomain: "example.com",
+}
+```
+
+See the [developer guide](./GUIDE.md) for the full configuration reference, the SuperTokens endpoints this exposes, and the override hooks.

package/dist/prefabs-tech-fastify-phone-auth.cjs

@@ -0,0 +1,8 @@
+Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));let c=require("twilio");c=s(c,1);let l=require("@prefabs.tech/fastify-user"),u=require("fastify-plugin");u=s(u,1);let d=require("slonik"),f=require("supertokens-node/recipe/passwordless");f=s(f,1);let p=require("@prefabs.tech/fastify-error-handler"),m=require("@prefabs.tech/fastify-slonik"),h=require("supertokens-node"),g=require("supertokens-node/recipe/userroles");g=s(g,1);var _=`PHONE`,v=`USER_INPUT_CODE`,y={SIGNUP_FAILED_ERROR:`SIGNUP_FAILED_ERROR`},b=`000000`,x=e=>{if(!e)throw Error("Twilio config is missing for phone auth. Add `phoneAuth.twilio` to your app config.");if(!e.verifyServiceSid)throw Error(`phoneAuth.twilio.verifyServiceSid is required for phone auth verification`);if(!e.accountSid||!e.authToken)throw Error(`phoneAuth.twilio.accountSid and phoneAuth.twilio.authToken are required for phone auth verification`);return{client:(0,c.default)(e.accountSid,e.authToken),verifyServiceSid:e.verifyServiceSid}},S=`
+  extend type User {
+    phoneNumber: String
+  }
+`,C=async e=>{e.graphql?.schema?.getType(`User`)&&await e.graphql.extendSchema(S)},w=e=>{let t=e.user.tables?.users?.name||l.TABLE_USERS;return d.sql.unsafe`
+    ALTER TABLE ${d.sql.identifier([t])}
+    ADD COLUMN IF NOT EXISTS phone_number VARCHAR ( 20 );
+  `},T=async(e,t)=>{await t.connect(async t=>{await t.query(w(e))})},E=(e,t)=>async n=>{let r=n.userContext.roles||[t.config.user.role||l.ROLE_USER];if(!await(0,l.areRolesExist)(r))throw new p.CustomError(`At least one role from ${r.join(`, `)} does not exist.`,y.SIGNUP_FAILED_ERROR);let i=await e.consumeCode(n);if(i.status!==`OK`)return i;let a=(0,h.getRequestFromUserContext)(n.userContext)?.original,o=(0,l.getUserService)(a?.config||t.config,a?.slonik||t.slonik,a?.dbSchema),s=i.user.phoneNumber,c=t.config.phoneAuth?.fallbackEmailDomain||t.config.appName.toLowerCase().replaceAll(/\s+/g,``)+`.com`,u=s?`${s}@${c}`:i.user.email;if(!u||!s)throw await(0,h.deleteUser)(i.user.id),Error(`Phone auth user missing phone number or email`);let d;if(i.createdNewUser){try{if(d=await o.create({email:u,id:i.user.id,phoneNumber:s}),!d)throw Error(`User not found`)}catch(e){throw await(0,h.deleteUser)(i.user.id),e}d.roles=r,i.user={...i.user,...d};for(let e of r){let n=await g.default.addRoleToUser(i.user.id,e);n.status!==`OK`&&t.log.error(n.status)}}else await o.update(i.user.id,{lastLoginAt:(0,m.formatDate)(new Date(Date.now()))}).catch(e=>{t.log.error(`Unable to update lastLoginAt for userId ${i.user.id}`),t.log.error(e)});return{...i,user:{...i.user,email:u,phoneNumber:s}}},D=(e,t,n)=>e.status===`OK`?{...e,user:{...e.user,email:e.user.email??`${t}@${n}`}}:e,O=(e,t)=>async n=>{if(n.userContext.roles||=[t.config.user.role||l.ROLE_USER],e.consumeCodePOST===void 0)throw Error(`Should never come here`);if(!(`userInputCode`in n)||n.userInputCode===void 0)return e.consumeCodePOST(n);let r=t.config.phoneAuth;if(!r)throw Error(`Phone auth config is missing`);let i=r.enableDevMode===!0,a=await f.default.listCodesByPreAuthSessionId({preAuthSessionId:n.preAuthSessionId});if(!a||!a.phoneNumber)return{status:`RESTART_FLOW_ERROR`};let{phoneNumber:o}=a,s=r.bypassSmsFor??[],c=r.fallbackEmailDomain??``;if(i||s.includes(o))return D(await e.consumeCodePOST(n),o,c);let u,d;try{({client:u,verifyServiceSid:d}=x(r.twilio))}catch(e){return t.log.error(e),{status:`RESTART_FLOW_ERROR`}}try{return(await u.verify.v2.services(d).verificationChecks.create({code:n.userInputCode,to:o})).status===`approved`?D(await e.consumeCodePOST({...n,userInputCode:b}),o,c):{failedCodeInputAttemptCount:1,maximumCodeInputAttempts:5,status:`INCORRECT_USER_INPUT_CODE_ERROR`}}catch(e){return t.log.error(e,`Twilio Verify verification check failed`),{status:`RESTART_FLOW_ERROR`}}},k=e=>{let t=e.config.phoneAuth;if(!t)throw Error("Phone auth config is missing. Add `phoneAuth` to your app config.");let n=t.enableDevMode===!0,r=t.devModeOtp;if(n&&!r)throw Error(`phoneAuth.devModeOtp is required when phoneAuth.enableDevMode is true`);let i=e=>(t.bypassSmsFor||[]).includes(e);return n||x(t.twilio),{contactMethod:t.contactMethod||`PHONE`,flowType:t.flowType||`USER_INPUT_CODE`,getCustomUserInputCode:async e=>{let t=e?.phoneNumber;return n||t&&i(t)?r:b},override:{apis:n=>{let r={};if(t.override?.apis){let i=t.override.apis,a;for(a in i){let t=i[a];t&&(r[a]=t(n,e))}}return{...n,consumeCodePOST:O(n,e),createCodePOST:async e=>(`phoneNumber`in e&&(e.userContext.phoneNumber=e.phoneNumber),n.createCodePOST(e)),...r}},functions:n=>{let r={};if(t.override?.functions){let i=t.override.functions,a;for(a in i){let t=i[a];t&&(r[a]=t(n,e))}}return{...n,consumeCode:E(n,e),...r}}},...n?{createAndSendCustomTextMessage:async()=>{e.log.info(`Skipping phone auth SMS delivery in development environment. Use default OTP [${r}] for testing.`)}}:{smsDelivery:{override:n=>({...n,sendSms:async n=>{if(i(n.phoneNumber)){e.log.info(`Skipping SMS for test number ${n.phoneNumber}.`);return}let{client:r,verifyServiceSid:a}=x(t.twilio);try{await r.verify.v2.services(a).verifications.create({channel:`sms`,to:n.phoneNumber})}catch(t){throw e.log.error(t,`Twilio Verify failed to send OTP`),t}}})}}}},A=e=>{let t=e.config.phoneAuth?.recipe;return typeof t==`function`?f.default.init(t(e)):f.default.init(k(e))},j=(0,u.default)(async e=>{if(e.config.phoneAuth?.enabled===!1){e.log.info(`fastify-phone-auth plugin is not enabled`);return}e.log.info(`Registering fastify-phone-auth plugin`),(0,l.addSupertokensRecipe)(e,A),e.addHook(`onReady`,async()=>{await T(e.config,e.slonik),await C(e)})});exports.DEFAULT_CONTACT_METHOD=_,exports.DEFAULT_FLOW_TYPE=v,exports.ERROR_CODES=y,exports.TWILIO_VERIFY_PLACEHOLDER_CODE=b,exports.consumeCode=E,exports.consumeCodePOST=O,exports.default=j,exports.getPasswordlessRecipeConfig=k,exports.getTwilioClient=x,exports.initPasswordlessRecipe=A;

package/dist/prefabs-tech-fastify-phone-auth.js

@@ -0,0 +1,184 @@
+import e from "twilio";
+import { ROLE_USER as t, TABLE_USERS as n, addSupertokensRecipe as r, areRolesExist as i, getUserService as a } from "@prefabs.tech/fastify-user";
+import o from "fastify-plugin";
+import { sql as s } from "slonik";
+import c from "supertokens-node/recipe/passwordless";
+import { CustomError as l } from "@prefabs.tech/fastify-error-handler";
+import { formatDate as u } from "@prefabs.tech/fastify-slonik";
+import { deleteUser as d, getRequestFromUserContext as f } from "supertokens-node";
+import p from "supertokens-node/recipe/userroles";
+//#region src/constants.ts
+var m = "PHONE", h = "USER_INPUT_CODE", g = { SIGNUP_FAILED_ERROR: "SIGNUP_FAILED_ERROR" }, _ = "000000", v = (t) => {
+	if (!t) throw Error("Twilio config is missing for phone auth. Add `phoneAuth.twilio` to your app config.");
+	if (!t.verifyServiceSid) throw Error("phoneAuth.twilio.verifyServiceSid is required for phone auth verification");
+	if (!t.accountSid || !t.authToken) throw Error("phoneAuth.twilio.accountSid and phoneAuth.twilio.authToken are required for phone auth verification");
+	return {
+		client: e(t.accountSid, t.authToken),
+		verifyServiceSid: t.verifyServiceSid
+	};
+}, y = "\n  extend type User {\n    phoneNumber: String\n  }\n", b = async (e) => {
+	e.graphql?.schema?.getType("User") && await e.graphql.extendSchema(y);
+}, x = (e) => {
+	let t = e.user.tables?.users?.name || n;
+	return s.unsafe`
+    ALTER TABLE ${s.identifier([t])}
+    ADD COLUMN IF NOT EXISTS phone_number VARCHAR ( 20 );
+  `;
+}, S = async (e, t) => {
+	await t.connect(async (t) => {
+		await t.query(x(e));
+	});
+}, C = (e, n) => async (r) => {
+	let o = r.userContext.roles || [n.config.user.role || t];
+	if (!await i(o)) throw new l(`At least one role from ${o.join(", ")} does not exist.`, g.SIGNUP_FAILED_ERROR);
+	let s = await e.consumeCode(r);
+	if (s.status !== "OK") return s;
+	let c = f(r.userContext)?.original, m = a(c?.config || n.config, c?.slonik || n.slonik, c?.dbSchema), h = s.user.phoneNumber, _ = n.config.phoneAuth?.fallbackEmailDomain || n.config.appName.toLowerCase().replaceAll(/\s+/g, "") + ".com", v = h ? `${h}@${_}` : s.user.email;
+	if (!v || !h) throw await d(s.user.id), Error("Phone auth user missing phone number or email");
+	let y;
+	if (s.createdNewUser) {
+		try {
+			if (y = await m.create({
+				email: v,
+				id: s.user.id,
+				phoneNumber: h
+			}), !y) throw Error("User not found");
+		} catch (e) {
+			throw await d(s.user.id), e;
+		}
+		y.roles = o, s.user = {
+			...s.user,
+			...y
+		};
+		for (let e of o) {
+			let t = await p.addRoleToUser(s.user.id, e);
+			t.status !== "OK" && n.log.error(t.status);
+		}
+	} else await m.update(s.user.id, { lastLoginAt: u(new Date(Date.now())) }).catch((e) => {
+		n.log.error(`Unable to update lastLoginAt for userId ${s.user.id}`), n.log.error(e);
+	});
+	return {
+		...s,
+		user: {
+			...s.user,
+			email: v,
+			phoneNumber: h
+		}
+	};
+}, w = (e, t, n) => e.status === "OK" ? {
+	...e,
+	user: {
+		...e.user,
+		email: e.user.email ?? `${t}@${n}`
+	}
+} : e, T = (e, n) => async (r) => {
+	if (r.userContext.roles ||= [n.config.user.role || t], e.consumeCodePOST === void 0) throw Error("Should never come here");
+	if (!("userInputCode" in r) || r.userInputCode === void 0) return e.consumeCodePOST(r);
+	let i = n.config.phoneAuth;
+	if (!i) throw Error("Phone auth config is missing");
+	let a = i.enableDevMode === !0, o = await c.listCodesByPreAuthSessionId({ preAuthSessionId: r.preAuthSessionId });
+	if (!o || !o.phoneNumber) return { status: "RESTART_FLOW_ERROR" };
+	let { phoneNumber: s } = o, l = i.bypassSmsFor ?? [], u = i.fallbackEmailDomain ?? "";
+	if (a || l.includes(s)) return w(await e.consumeCodePOST(r), s, u);
+	let d, f;
+	try {
+		({client: d, verifyServiceSid: f} = v(i.twilio));
+	} catch (e) {
+		return n.log.error(e), { status: "RESTART_FLOW_ERROR" };
+	}
+	try {
+		return (await d.verify.v2.services(f).verificationChecks.create({
+			code: r.userInputCode,
+			to: s
+		})).status === "approved" ? w(await e.consumeCodePOST({
+			...r,
+			userInputCode: _
+		}), s, u) : {
+			failedCodeInputAttemptCount: 1,
+			maximumCodeInputAttempts: 5,
+			status: "INCORRECT_USER_INPUT_CODE_ERROR"
+		};
+	} catch (e) {
+		return n.log.error(e, "Twilio Verify verification check failed"), { status: "RESTART_FLOW_ERROR" };
+	}
+}, E = (e) => {
+	let t = e.config.phoneAuth;
+	if (!t) throw Error("Phone auth config is missing. Add `phoneAuth` to your app config.");
+	let n = t.enableDevMode === !0, r = t.devModeOtp;
+	if (n && !r) throw Error("phoneAuth.devModeOtp is required when phoneAuth.enableDevMode is true");
+	let i = (e) => (t.bypassSmsFor || []).includes(e);
+	return n || v(t.twilio), {
+		contactMethod: t.contactMethod || "PHONE",
+		flowType: t.flowType || "USER_INPUT_CODE",
+		getCustomUserInputCode: async (e) => {
+			let t = e?.phoneNumber;
+			return n || t && i(t) ? r : _;
+		},
+		override: {
+			apis: (n) => {
+				let r = {};
+				if (t.override?.apis) {
+					let i = t.override.apis, a;
+					for (a in i) {
+						let t = i[a];
+						t && (r[a] = t(n, e));
+					}
+				}
+				return {
+					...n,
+					consumeCodePOST: T(n, e),
+					createCodePOST: async (e) => ("phoneNumber" in e && (e.userContext.phoneNumber = e.phoneNumber), n.createCodePOST(e)),
+					...r
+				};
+			},
+			functions: (n) => {
+				let r = {};
+				if (t.override?.functions) {
+					let i = t.override.functions, a;
+					for (a in i) {
+						let t = i[a];
+						t && (r[a] = t(n, e));
+					}
+				}
+				return {
+					...n,
+					consumeCode: C(n, e),
+					...r
+				};
+			}
+		},
+		...n ? { createAndSendCustomTextMessage: async () => {
+			e.log.info(`Skipping phone auth SMS delivery in development environment. Use default OTP [${r}] for testing.`);
+		} } : { smsDelivery: { override: (n) => ({
+			...n,
+			sendSms: async (n) => {
+				if (i(n.phoneNumber)) {
+					e.log.info(`Skipping SMS for test number ${n.phoneNumber}.`);
+					return;
+				}
+				let { client: r, verifyServiceSid: a } = v(t.twilio);
+				try {
+					await r.verify.v2.services(a).verifications.create({
+						channel: "sms",
+						to: n.phoneNumber
+					});
+				} catch (t) {
+					throw e.log.error(t, "Twilio Verify failed to send OTP"), t;
+				}
+			}
+		}) } }
+	};
+}, D = (e) => {
+	let t = e.config.phoneAuth?.recipe;
+	return typeof t == "function" ? c.init(t(e)) : c.init(E(e));
+}, O = o(async (e) => {
+	if (e.config.phoneAuth?.enabled === !1) {
+		e.log.info("fastify-phone-auth plugin is not enabled");
+		return;
+	}
+	e.log.info("Registering fastify-phone-auth plugin"), r(e, D), e.addHook("onReady", async () => {
+		await S(e.config, e.slonik), await b(e);
+	});
+});
+//#endregion
+export { m as DEFAULT_CONTACT_METHOD, h as DEFAULT_FLOW_TYPE, g as ERROR_CODES, _ as TWILIO_VERIFY_PLACEHOLDER_CODE, C as consumeCode, T as consumeCodePOST, O as default, E as getPasswordlessRecipeConfig, v as getTwilioClient, D as initPasswordlessRecipe };