Chore/sign message clarificaitons

package.json

@@ -9,6 +9,9 @@
   "engines": {
     "node": ">=16"
   },
+  "workspaces": [
+    "packages/*"
+  ],
   "scripts": {
     "prettier": "npx prettier --write '{*,**/*}.{ts,tsx,js,jsx,css,json}'"
   },

packages/actions-spec/README.md

@@ -748,6 +748,48 @@ export type SignMessageData = {
 When received by the blink client, the user should be shown the plaintext `data`
 value and prompted to sign it with their wallet to generate a `signature`.
 
+The `data` can be a plaintext string or a structured `SignMessageData` object.
+
+When using `SignMessageData`, it must be formatted as a standardized, human-readable plaintext suitable for signing. 
+Both the client and server must generate the message using the same method to ensure proper verification.
+The following template must be used by both the Action API and the client to format `SignMessageData`:
+
+```
+${domain} wants you to sign a message with your account:
+${address}
+
+${statement}
+
+Chain ID: ${chainId}
+Nonce: ${nonce}
+Issued At: ${issuedAt}
+```
+
+If `chainId` is not provided, the `Chain ID` line should be omitted from the message to be signed.
+
+Client should not prefix, suffix or otherwise modify the `SignMessageData` value before signing it.
+Client should perform validation on the `SignMessageData` before signing to ensure that it meets expected criteria and to prevent potential security issues.
+
+The following function illustrates how to create a human-readable message text from `SignMessageData`:
+
+```ts
+export function createSignMessageText(input: SignMessageData): string {
+  let message = `${input.domain} wants you to sign a message with your account:\n`;
+  message += `${input.address}`;
+  message += `\n\n${input.statement}`;
+  const fields: string[] = [];
+
+  if (input.chainId) {
+    fields.push(`Chain ID: ${input.chainId}`);
+  }
+  fields.push(`Nonce: ${input.nonce}`);
+  fields.push(`Issued At: ${input.issuedAt}`);
+  message += `\n\n${fields.join("\n")}`;
+
+  return message;
+}
+```
+
 After signing, the blink client will continue the chain-of-actions by making a
 POST request to the provided `PostNextActionLink` endpoint with a payload
 similar to the normal `ActionPostRequest` fields (see

packages/actions-spec/package.json

@@ -41,7 +41,7 @@
     },
     {
       "name": "Alexey Tsymbal",
-      "url": "https://github.com/Baulore"
+      "url": "https://github.com/tsmbl"
     },
     {
       "name": "Filipp Sher",

packages/solana-actions/src/createPostResponse.ts

@@ -13,7 +13,7 @@ import {
   createActionIdentifierInstruction,
   getActionIdentityFromEnv,
 } from "./actionIdentity.js";
-import { ActionPostResponse } from "@solana/actions-spec";
+import { ActionPostResponse, TransactionResponse } from "@solana/actions-spec";
 
 /**
  * Thrown when the Action POST response cannot be created.
@@ -29,7 +29,7 @@ export interface CreateActionPostResponseArgs<
   TransactionType = Transaction | VersionedTransaction,
 > {
   /** POST response fields per the Solana Actions spec. */
-  fields: Omit<ActionPostResponse, "transaction"> & {
+  fields: Omit<TransactionResponse, "transaction"> & {
     /** Solana transaction to be base64 encoded. */
     transaction: TransactionType;
   };

packages/solana-actions/src/fetchTransaction.ts

@@ -1,4 +1,8 @@
-import { ActionPostRequest, ActionPostResponse } from "@solana/actions-spec";
+import {
+  ActionPostRequest,
+  ActionPostResponse,
+  TransactionResponse,
+} from "@solana/actions-spec";
 import { Commitment, Connection, PublicKey } from "@solana/web3.js";
 import { Transaction } from "@solana/web3.js";
 import fetch from "cross-fetch";
@@ -49,7 +53,7 @@ export async function fetchTransaction(
     body: JSON.stringify(fields),
   });
 
-  const json = (await response.json()) as ActionPostResponse;
+  const json = (await response.json()) as TransactionResponse;
   if (!json?.transaction) throw new FetchActionError("missing transaction");
   if (typeof json.transaction !== "string")
     throw new FetchActionError("invalid transaction");

packages/solana-actions/src/index.ts

@@ -10,3 +10,4 @@ export * from "./fetchTransaction.js";
 export * from "./findReference.js";
 export * from "./createPostResponse.js";
 export * from "./actionIdentity.js";
+export * from "./signMessageData.js";

packages/solana-actions/src/signMessageData.ts

@@ -0,0 +1,147 @@
+import type { SignMessageData } from "@solana/actions-spec";
+
+export interface SignMessageVerificationOptions {
+  expectedAddress?: string;
+  expectedDomains?: string[];
+  expectedChainIds?: string[];
+  issuedAtThreshold?: number;
+}
+
+export enum SignMessageVerificationErrorType {
+  ADDRESS_MISMATCH = "ADDRESS_MISMATCH",
+  DOMAIN_MISMATCH = "DOMAIN_MISMATCH",
+  CHAIN_ID_MISMATCH = "CHAIN_ID_MISMATCH",
+  ISSUED_TOO_FAR_IN_THE_PAST = "ISSUED_TOO_FAR_IN_THE_PAST",
+  ISSUED_TOO_FAR_IN_THE_FUTURE = "ISSUED_TOO_FAR_IN_THE_FUTURE",
+  INVALID_DATA = "INVALID_DATA",
+}
+
+const DOMAIN =
+  "(?<domain>[^\\n]+?) wants you to sign a message with your account:\\n";
+const ADDRESS = "(?<address>[^\\n]+)(?:\\n|$)";
+const STATEMENT = "(?:\\n(?<statement>[\\S\\s]*?)(?:\\n|$))";
+const CHAIN_ID = "(?:\\nChain ID: (?<chainId>[^\\n]+))?";
+const NONCE = "\\nNonce: (?<nonce>[^\\n]+)";
+const ISSUED_AT = "\\nIssued At: (?<issuedAt>[^\\n]+)";
+const FIELDS = `${CHAIN_ID}${NONCE}${ISSUED_AT}`;
+const MESSAGE = new RegExp(`^${DOMAIN}${ADDRESS}${STATEMENT}${FIELDS}\\n*$`);
+
+/**
+ * Create a human-readable message text for the user to sign.
+ *
+ * @param input The data to be signed.
+ * @returns The message text.
+ */
+export function createSignMessageText(input: SignMessageData): string {
+  let message = `${input.domain} wants you to sign a message with your account:\n`;
+  message += `${input.address}`;
+  message += `\n\n${input.statement}`;
+  const fields: string[] = [];
+
+  if (input.chainId) {
+    fields.push(`Chain ID: ${input.chainId}`);
+  }
+  fields.push(`Nonce: ${input.nonce}`);
+  fields.push(`Issued At: ${input.issuedAt}`);
+  message += `\n\n${fields.join("\n")}`;
+
+  return message;
+}
+
+/**
+ * Parse the sign message text to extract the data to be signed.
+ * @param text The message text to be parsed.
+ */
+export function parseSignMessageText(text: string): SignMessageData | null {
+  const match = MESSAGE.exec(text);
+  if (!match) return null;
+  const groups = match.groups;
+  if (!groups) return null;
+
+  return {
+    domain: groups.domain,
+    address: groups.address,
+    statement: groups.statement,
+    nonce: groups.nonce,
+    chainId: groups.chainId,
+    issuedAt: groups.issuedAt,
+  };
+}
+
+/**
+ * Verify the sign message data before signing.
+ * @param data The data to be signed.
+ * @param opts Options for verification, including the expected address, chainId, issuedAt, and domains.
+ *
+ * @returns An array of errors if the verification fails.
+ */
+export function verifySignMessageData(
+  data: SignMessageData,
+  opts: SignMessageVerificationOptions,
+) {
+  if (
+    !data.address ||
+    !data.domain ||
+    !data.issuedAt ||
+    !data.nonce ||
+    !data.statement
+  ) {
+    return [SignMessageVerificationErrorType.INVALID_DATA];
+  }
+
+  try {
+    const {
+      expectedAddress,
+      expectedChainIds,
+      issuedAtThreshold,
+      expectedDomains,
+    } = opts;
+    const errors: SignMessageVerificationErrorType[] = [];
+    const now = Date.now();
+
+    // verify if parsed address is same as the expected address
+    if (expectedAddress && data.address !== expectedAddress) {
+      errors.push(SignMessageVerificationErrorType.ADDRESS_MISMATCH);
+    }
+
+    if (expectedDomains) {
+      const expectedDomainsNormalized = expectedDomains.map(normalizeDomain);
+      const normalizedDomain = normalizeDomain(data.domain);
+
+      if (!expectedDomainsNormalized.includes(normalizedDomain)) {
+        errors.push(SignMessageVerificationErrorType.DOMAIN_MISMATCH);
+      }
+    }
+
+    if (
+      expectedChainIds &&
+      data.chainId &&
+      !expectedChainIds.includes(data.chainId)
+    ) {
+      errors.push(SignMessageVerificationErrorType.CHAIN_ID_MISMATCH);
+    }
+
+    if (issuedAtThreshold !== undefined) {
+      const iat = Date.parse(data.issuedAt);
+      if (Math.abs(iat - now) > issuedAtThreshold) {
+        if (iat < now) {
+          errors.push(
+            SignMessageVerificationErrorType.ISSUED_TOO_FAR_IN_THE_PAST,
+          );
+        } else {
+          errors.push(
+            SignMessageVerificationErrorType.ISSUED_TOO_FAR_IN_THE_FUTURE,
+          );
+        }
+      }
+    }
+
+    return errors;
+  } catch (e) {
+    return [SignMessageVerificationErrorType.INVALID_DATA];
+  }
+}
+
+function normalizeDomain(domain: string): string {
+  return domain.replace(/^www\./, "");
+}