better-auth-sign-in-with-typed-data 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HiiiiD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# better-auth-sign-in-with-typed-data (SIWTD)
+
+A better-auth plugin for logging in by signing EIP-712 typed data, instead of
+an ERC-4361 (SIWE) plain-text message. Works with any EVM-style secp256k1
+wallet, including VeChain wallets (VeWorld, Sync2/Connex).
+
+Unlike the official `siwe` plugin, the typed-data schema (domain/types/
+message shape) is entirely up to you — the plugin only requires a `nonce`
+field inside the signed `message`, and a `chainId` in the signed `domain`.
+There is no email/password support: wallet address is the sole identity.
+
+## Install
+
+```bash
+bun add better-auth-sign-in-with-typed-data viem
+```
+
+## Server
+
+```ts
+import { betterAuth } from "better-auth";
+import { siwtd } from "better-auth-sign-in-with-typed-data";
+
+export const auth = betterAuth({
+  plugins: [
+    siwtd({
+      domain: { name: "my-app.example.com", chainId: 1 },
+      getNonce: async () => crypto.randomUUID().replace(/-/g, ""),
+    }),
+  ],
+});
+```
+
+## Client
+
+```ts
+import { createAuthClient } from "better-auth/client";
+import { siwtdClient } from "better-auth-sign-in-with-typed-data/client";
+
+export const authClient = createAuthClient({
+  plugins: [siwtdClient()],
+});
+
+const { data: nonceData } = await authClient.siwtd.nonce();
+
+const types = { Login: [{ name: "nonce", type: "string" }] } as const;
+const message = { nonce: nonceData.nonce };
+const domain = { name: "my-app.example.com", chainId: 1 };
+
+const signature = await walletClient.signTypedData({
+  domain,
+  types,
+  primaryType: "Login",
+  message,
+});
+
+const { data } = await authClient.siwtd.verify({
+  domain,
+  types,
+  primaryType: "Login",
+  message,
+  signature,
+});
+```
+
+## Options
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `domain` | yes | EIP-712 domain fields to check against the signed typed data. Only the fields you set here are enforced (`name`, `chainId`, `verifyingContract`, `version`). |
+| `getNonce` | yes | Returns a fresh nonce (8+ alphanumeric characters) for each `/siwtd/nonce` call. |
+| `ensLookup` | no | Resolve a display `name`/`avatar` for a wallet address on first login. |
+| `schema` | no | Override the `walletAddress` table schema. |
+
+## How verification works
+
+1. Client requests a nonce from `/siwtd/nonce`; the server stores it.
+2. Client signs an EIP-712 typed-data payload of its own design, as long as
+   the signed `message` includes that `nonce` and the signed `domain`
+   includes a `chainId`.
+3. Client submits `{ domain, types, primaryType, message, signature }` to
+   `/siwtd/verify`.
+4. The server atomically consumes the nonce (single use), checks the signed
+   `domain` against the plugin's configured `domain` option, and recovers
+   the signer's address from the signature via viem. The recovered address
+   is the only trusted source of wallet identity — any address-shaped field
+   inside `message` itself is ignored.
+5. On success, the server finds or creates a `user` + `walletAddress` +
+   `account` record for that address/chain, creates a session, and returns
+   a session token.
+
+## Testing
+
+```bash
+bun test
+```
+
+## Releasing
+
+Versioning uses [changesets](https://github.com/changesets/changesets), but
+nothing bumps automatically on every push to `master` — commits accumulate
+until you're ready to cut a release:
+
+1. On each PR that needs a release note, run `bunx changeset` and describe
+   the change; commit the generated file under `.changeset/`.
+2. When ready to release, manually run the `Version` workflow (Actions tab
+   → Version → Run workflow). It bumps the version, updates the changelog
+   from all pending changesets, commits straight to `master`, and pushes a
+   `vX.Y.Z` tag.
+3. The tag push triggers the `Publish` workflow, which builds and publishes
+   to npm.

package/dist/client.d.ts

@@ -0,0 +1,10 @@
+import type { siwtd } from "./index";
+export declare const siwtdClient: () => {
+    id: "siwtd";
+    $InferServerPlugin: ReturnType<typeof siwtd>;
+    pathMethods: {
+        "/siwtd/nonce": "POST";
+        "/siwtd/verify": "POST";
+    };
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,eAAO,MAAM,WAAW;;wBAGI,UAAU,CAAC,OAAO,KAAK,CAAC;;;;;CAMnD,CAAC"}

package/dist/client.js

@@ -0,0 +1,14 @@
+// client.ts
+var siwtdClient = () => {
+  return {
+    id: "siwtd",
+    $InferServerPlugin: {},
+    pathMethods: {
+      "/siwtd/nonce": "POST",
+      "/siwtd/verify": "POST"
+    }
+  };
+};
+export {
+  siwtdClient
+};

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import type { InferOptionSchema } from "better-auth/types";
+import * as z from "zod";
+import { schema, type WalletAddressSchema } from "./schema";
+import type { ENSLookupArgs, ENSLookupResult } from "./types";
+export interface SIWTDDomainOptions {
+    name?: string;
+    chainId?: number;
+    verifyingContract?: `0x${string}`;
+    version?: string;
+}
+export interface SIWTDPluginOptions {
+    domain: SIWTDDomainOptions;
+    getNonce: () => Promise<string>;
+    ensLookup?: (args: ENSLookupArgs) => Promise<ENSLookupResult>;
+    schema?: InferOptionSchema<typeof schema>;
+}
+export declare const siwtd: (options: SIWTDPluginOptions) => {
+    id: "siwtd";
+    schema: WalletAddressSchema;
+    endpoints: {
+        getSiwtdNonce: import("better-call").StrictEndpoint<"/siwtd/nonce", {
+            method: "POST";
+            body: z.ZodOptional<z.ZodObject<{}, z.core.$strict>>;
+        }, {
+            nonce: string;
+        }>;
+        verifySiwtdMessage: import("better-call").StrictEndpoint<"/siwtd/verify", {
+            method: "POST";
+            body: z.ZodObject<{
+                domain: z.ZodRecord<z.ZodString, z.ZodAny>;
+                types: z.ZodRecord<z.ZodString, z.ZodAny>;
+                primaryType: z.ZodString;
+                message: z.ZodRecord<z.ZodString, z.ZodAny>;
+                signature: z.ZodString;
+            }, z.core.$strict>;
+            requireRequest: true;
+        }, {
+            token: string;
+            success: boolean;
+            user: {
+                id: string;
+                walletAddress: `0x${string}`;
+                chainId: number;
+            };
+        }>;
+    };
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAQ,MAAM,mBAAmB,CAAC;AAQjE,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAAE,MAAM,EAAE,KAAK,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAiB,MAAM,SAAS,CAAC;AAE7E,MAAM,WAAW,kBAAkB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAChC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IAC9D,MAAM,CAAC,EAAE,iBAAiB,CAAC,OAAO,MAAM,CAAC,CAAC;CAC1C;AAkDD,eAAO,MAAM,KAAK,GAAI,SAAS,kBAAkB;;YAGC,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyOpE,CAAC"}

package/dist/index.js

@@ -0,0 +1,242 @@
+// index.ts
+import { APIError, createAuthEndpoint, isAPIError } from "better-auth/api";
+import { setSessionCookie } from "better-auth/cookies";
+import { mergeSchema } from "better-auth/db";
+import {
+  getAddress,
+  recoverTypedDataAddress
+} from "viem";
+import * as z from "zod";
+import { schema } from "./schema";
+var SIWTD_VERIFICATION_IDENTIFIER_PREFIX = "siwtd:";
+var VERIFICATION_IDENTIFIER_MAX_LENGTH = 255;
+var SIWTD_NONCE_MAX_LENGTH = VERIFICATION_IDENTIFIER_MAX_LENGTH - SIWTD_VERIFICATION_IDENTIFIER_PREFIX.length;
+var SIWTD_NONCE_ALPHANUMERIC_REGEX = /^[a-zA-Z0-9]+$/;
+var isValidSiwtdNonce = (nonce) => typeof nonce === "string" && nonce.length >= 8 && nonce.length <= SIWTD_NONCE_MAX_LENGTH && SIWTD_NONCE_ALPHANUMERIC_REGEX.test(nonce);
+var getSiwtdNonceBodySchema = z.object({}).strict().optional();
+var verifySiwtdBodySchema = z.object({
+  domain: z.record(z.string(), z.any()),
+  types: z.record(z.string(), z.any()),
+  primaryType: z.string().min(1),
+  message: z.record(z.string(), z.any()),
+  signature: z.string().min(1)
+}).strict();
+function domainMatches(expected, signed) {
+  if (expected.name !== undefined && expected.name !== signed.name)
+    return false;
+  if (expected.chainId !== undefined && expected.chainId !== signed.chainId)
+    return false;
+  if (expected.verifyingContract !== undefined && expected.verifyingContract.toLowerCase() !== signed.verifyingContract?.toLowerCase())
+    return false;
+  if (expected.version !== undefined && expected.version !== signed.version)
+    return false;
+  return true;
+}
+function createPlaceholderEmail(address) {
+  return `${address.toLowerCase()}@siwtd.invalid`;
+}
+var siwtd = (options) => {
+  return {
+    id: "siwtd",
+    schema: mergeSchema(schema, options?.schema),
+    endpoints: {
+      getSiwtdNonce: createAuthEndpoint("/siwtd/nonce", {
+        method: "POST",
+        body: getSiwtdNonceBodySchema
+      }, async (ctx) => {
+        const nonce = await options.getNonce();
+        if (!isValidSiwtdNonce(nonce)) {
+          throw new APIError("INTERNAL_SERVER_ERROR", {
+            message: `SIWTD getNonce must return 8-${SIWTD_NONCE_MAX_LENGTH} alphanumeric characters.`,
+            code: "SIWTD_INVALID_NONCE"
+          });
+        }
+        await ctx.context.internalAdapter.createVerificationValue({
+          identifier: `${SIWTD_VERIFICATION_IDENTIFIER_PREFIX}${nonce}`,
+          value: nonce,
+          expiresAt: new Date(Date.now() + 15 * 60 * 1000)
+        });
+        return ctx.json({ nonce });
+      }),
+      verifySiwtdMessage: createAuthEndpoint("/siwtd/verify", {
+        method: "POST",
+        body: verifySiwtdBodySchema,
+        requireRequest: true
+      }, async (ctx) => {
+        const { domain, types, primaryType, message, signature } = ctx.body;
+        const nonce = message.nonce;
+        if (typeof nonce !== "string" || !isValidSiwtdNonce(nonce)) {
+          throw new APIError("BAD_REQUEST", {
+            message: "message.nonce is required and must be a valid nonce."
+          });
+        }
+        try {
+          const verification = await ctx.context.internalAdapter.consumeVerificationValue(`${SIWTD_VERIFICATION_IDENTIFIER_PREFIX}${nonce}`);
+          if (!verification) {
+            throw new APIError("UNAUTHORIZED", {
+              message: "Invalid or expired nonce",
+              code: "UNAUTHORIZED_INVALID_OR_EXPIRED_NONCE"
+            });
+          }
+          if (!domainMatches(options.domain, domain)) {
+            throw new APIError("UNAUTHORIZED", {
+              message: "Signed domain does not match the expected domain",
+              code: "UNAUTHORIZED_DOMAIN_MISMATCH"
+            });
+          }
+          const signedChainId = domain.chainId;
+          if (typeof signedChainId !== "number" || signedChainId <= 0) {
+            throw new APIError("UNAUTHORIZED", {
+              message: "Signed domain is missing a valid chainId",
+              code: "UNAUTHORIZED_INVALID_CHAIN_ID"
+            });
+          }
+          let recovered;
+          try {
+            recovered = await recoverTypedDataAddress({
+              domain,
+              types,
+              primaryType,
+              message,
+              signature
+            });
+          } catch {
+            throw new APIError("UNAUTHORIZED", {
+              message: "Invalid signature",
+              code: "UNAUTHORIZED_INVALID_SIGNATURE"
+            });
+          }
+          const walletAddress = getAddress(recovered);
+          const expirationTime = message.expirationTime;
+          const notBefore = message.notBefore;
+          const now = Date.now();
+          if (typeof expirationTime === "string") {
+            const expiresAt = Date.parse(expirationTime);
+            if (!Number.isNaN(expiresAt) && now >= expiresAt) {
+              throw new APIError("UNAUTHORIZED", {
+                message: "Message has expired",
+                code: "UNAUTHORIZED_MESSAGE_EXPIRED"
+              });
+            }
+          }
+          if (typeof notBefore === "string") {
+            const notBeforeAt = Date.parse(notBefore);
+            if (!Number.isNaN(notBeforeAt) && now < notBeforeAt) {
+              throw new APIError("UNAUTHORIZED", {
+                message: "Message is not yet valid",
+                code: "UNAUTHORIZED_MESSAGE_NOT_YET_VALID"
+              });
+            }
+          }
+          let user = null;
+          const existingWalletAddress = await ctx.context.adapter.findOne({
+            model: "walletAddress",
+            where: [
+              { field: "address", operator: "eq", value: walletAddress },
+              { field: "chainId", operator: "eq", value: signedChainId }
+            ]
+          });
+          if (existingWalletAddress) {
+            user = await ctx.context.adapter.findOne({
+              model: "user",
+              where: [
+                {
+                  field: "id",
+                  operator: "eq",
+                  value: existingWalletAddress.userId
+                }
+              ]
+            });
+          } else {
+            const anyWalletAddress = await ctx.context.adapter.findOne({
+              model: "walletAddress",
+              where: [
+                { field: "address", operator: "eq", value: walletAddress }
+              ]
+            });
+            if (anyWalletAddress) {
+              user = await ctx.context.adapter.findOne({
+                model: "user",
+                where: [
+                  {
+                    field: "id",
+                    operator: "eq",
+                    value: anyWalletAddress.userId
+                  }
+                ]
+              });
+            }
+          }
+          if (!user) {
+            const { name, avatar } = await options.ensLookup?.({ walletAddress }) ?? {};
+            user = await ctx.context.internalAdapter.createUser({
+              name: name ?? walletAddress,
+              email: createPlaceholderEmail(walletAddress),
+              image: avatar ?? ""
+            }, { method: "siwtd" });
+            await ctx.context.adapter.create({
+              model: "walletAddress",
+              data: {
+                userId: user.id,
+                address: walletAddress,
+                chainId: signedChainId,
+                isPrimary: true,
+                createdAt: new Date
+              }
+            });
+            await ctx.context.internalAdapter.createAccount({
+              userId: user.id,
+              providerId: "siwtd",
+              accountId: `${walletAddress}:${signedChainId}`,
+              createdAt: new Date,
+              updatedAt: new Date
+            });
+          } else if (!existingWalletAddress) {
+            await ctx.context.adapter.create({
+              model: "walletAddress",
+              data: {
+                userId: user.id,
+                address: walletAddress,
+                chainId: signedChainId,
+                isPrimary: false,
+                createdAt: new Date
+              }
+            });
+            await ctx.context.internalAdapter.createAccount({
+              userId: user.id,
+              providerId: "siwtd",
+              accountId: `${walletAddress}:${signedChainId}`,
+              createdAt: new Date,
+              updatedAt: new Date
+            });
+          }
+          const session = await ctx.context.internalAdapter.createSession(user.id);
+          if (!session) {
+            throw new APIError("INTERNAL_SERVER_ERROR", {
+              message: "Failed to create session"
+            });
+          }
+          await setSessionCookie(ctx, { session, user });
+          return ctx.json({
+            token: session.token,
+            success: true,
+            user: {
+              id: user.id,
+              walletAddress,
+              chainId: signedChainId
+            }
+          });
+        } catch (error) {
+          if (isAPIError(error))
+            throw error;
+          throw new APIError("UNAUTHORIZED", {
+            message: "Something went wrong. Please try again later."
+          });
+        }
+      })
+    }
+  };
+};
+export {
+  siwtd
+};

package/dist/schema.d.ts

@@ -0,0 +1,33 @@
+export declare const schema: {
+    walletAddress: {
+        fields: {
+            userId: {
+                type: "string";
+                required: true;
+                references: {
+                    model: string;
+                    field: string;
+                };
+            };
+            address: {
+                type: "string";
+                required: true;
+            };
+            chainId: {
+                type: "number";
+                required: true;
+            };
+            isPrimary: {
+                type: "boolean";
+                required: true;
+                defaultValue: false;
+            };
+            createdAt: {
+                type: "date";
+                required: true;
+            };
+        };
+    };
+};
+export type WalletAddressSchema = typeof schema;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../schema.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BiB,CAAC;AAErC,MAAM,MAAM,mBAAmB,GAAG,OAAO,MAAM,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+export interface WalletAddress {
+    id: string;
+    userId: string;
+    address: string;
+    chainId: number;
+    isPrimary: boolean;
+    createdAt: Date;
+}
+export interface ENSLookupArgs {
+    walletAddress: string;
+}
+export interface ENSLookupResult {
+    name?: string;
+    avatar?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC7B,aAAa,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "better-auth-sign-in-with-typed-data",
+  "version": "0.1.0",
+  "description": "A better-auth plugin for logging in by signing EIP-712 typed data instead of a SIWE plain-text message.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HiiiiD/better-auth-sign-in-with-typed-data.git"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "rm -rf dist && bun build ./index.ts ./client.ts --target=node --outdir=dist --external '*' && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@better-auth/memory-adapter": "^1.7.5",
+    "@changesets/changelog-github": "^1.0.1",
+    "@changesets/cli": "^3.0.3",
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^7"
+  },
+  "dependencies": {
+    "@better-auth/core": "^1.7.5",
+    "better-auth": "^1.7.5",
+    "viem": "^2.56.8",
+    "zod": "^4.6.5"
+  }
+}