Merge pull request #27 from bitsocialnet/feat/challenge-validate-settings

feat(challenge): add validateChallengeSettings and bump pkc-js to 0.0.85

Author: Rinse12

challenge/README.md

@@ -84,15 +84,25 @@ await community.edit({
 
 #### Challenge options
 
-All option values must be strings (pkc-js challenge convention).
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `chainTicker` | `"base"` | Chain where MintPass contract is deployed |
-| `contractAddress` | Known deployment per chain | If omitted and `chainTicker` is supported, defaults to the known MintPass deployment for that chain |
-| `requiredTokenType` | `"0"` | Required token type (0=SMS, 1=Email, 2+=future methods) |
-| `transferCooldownSeconds` | `"604800"` | Cooldown period after NFT transfer (1 week) |
-| `error` | Default message | Custom error message for users without NFT. Use `{authorAddress}` as a placeholder |
+All option values must be strings (pkc-js challenge convention). Options are validated on community edit/create/start (pkc-js `>= 0.0.85`): `chainTicker`, `contractAddress` and `requiredTokenType` are required, unknown option keys are rejected, and malformed values fail the edit instead of silently rejecting every author.
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `chainTicker` | yes | `"base"` | Chain where MintPass contract is deployed; `"base"` or `"eth"` |
+| `contractAddress` | yes | Base Sepolia deployment | MintPass contract address; must be a well-formed EVM address |
+| `requiredTokenType` | yes | `"0"` | Required token type (0=SMS, 1=Email, 2+=future methods); integer 0–65535 |
+| `bindToFirstAuthor` | no | `"true"` | Bind each tokenId to the first author that uses it in this community (`"true"`/`"false"`/`"1"`/`"0"`) |
+| `noChallengeUrl` | no | `"false"` | Fail immediately when the NFT is missing instead of showing the mintpass.org iframe (`"true"`/`"false"`/`"1"`/`"0"`) |
+| `transferCooldownSeconds` | no | `"604800"` | Cooldown period after NFT transfer (1 week); non-negative integer |
+| `error` | no | Default message | Custom error message for users without NFT. Use `{authorAddress}` as a placeholder |
+| `rpcUrl` | no | Chain default | Custom RPC URL (mainly for testing). **Must not** be listed in `publicOptions`; the challenge rejects that since RPC URLs often embed provider API keys |
+
+#### Public options
+
+`publicOptions` controls which options are written into the published community record. Recommended for MintPass:
+
+- Publish `chainTicker`, `contractAddress`, `requiredTokenType` and `noChallengeUrl` so clients can tell authors up front which MintPass they need (and, with `noChallengeUrl`, that no iframe verification will be offered). Publishing `error`, `bindToFirstAuthor` and `transferCooldownSeconds` is harmless and explains rejections; that is the owner's call.
+- Never publish `rpcUrl`.
 
 ### With bitsocial-cli
 

challenge/dist/mintpass.js

@@ -517,6 +517,43 @@ const getChallenge = async ({ challengeSettings, challengeRequestMessage, commun
         error: firstFailure || "Failed to verify MintPass"
     };
 };
+// Boolean-like option values accepted by getChallenge ("true"/"1" are truthy, everything else is falsy).
+// Anything outside this set is almost certainly a typo that would silently read as false.
+const BOOLEAN_OPTION_VALUES = new Set(["true", "false", "1", "0"]);
+// Tickers that _getChainProviderWithSafety / createViemClientForChain can actually resolve.
+const SUPPORTED_CHAIN_TICKERS = new Set(["eth", "base"]);
+const MAX_TOKEN_TYPE = 65535; // tokenType is a uint16 in the MintPass ABI
+const isNonNegativeIntegerString = (value) => /^\d+$/.test(value) && Number.isSafeInteger(Number(value));
+/**
+ * Semantic validation of challenge settings, run by pkc-js on community edit/create/start.
+ * Must stay sync and network-free. Presence of required options is enforced by pkc-js core
+ * via optionInputs; this hook checks that the values actually parse.
+ */
+const validateChallengeSettings = ({ challengeSettings }) => {
+    const options = challengeSettings.options || {};
+    const { chainTicker, contractAddress, requiredTokenType, transferCooldownSeconds, bindToFirstAuthor, noChallengeUrl } = options;
+    if (chainTicker !== undefined && !SUPPORTED_CHAIN_TICKERS.has(chainTicker)) {
+        throw Error(`Invalid option chainTicker "${chainTicker}": must be one of ${[...SUPPORTED_CHAIN_TICKERS].map((t) => `"${t}"`).join(", ")}`);
+    }
+    if (contractAddress !== undefined && !isAddress(contractAddress)) {
+        throw Error(`Invalid option contractAddress "${contractAddress}": must be a well-formed EVM address`);
+    }
+    if (requiredTokenType !== undefined && (!isNonNegativeIntegerString(requiredTokenType) || Number(requiredTokenType) > MAX_TOKEN_TYPE)) {
+        throw Error(`Invalid option requiredTokenType "${requiredTokenType}": must be an integer between 0 and ${MAX_TOKEN_TYPE}`);
+    }
+    if (transferCooldownSeconds !== undefined && !isNonNegativeIntegerString(transferCooldownSeconds)) {
+        throw Error(`Invalid option transferCooldownSeconds "${transferCooldownSeconds}": must be a non-negative integer`);
+    }
+    for (const [name, value] of [["bindToFirstAuthor", bindToFirstAuthor], ["noChallengeUrl", noChallengeUrl]]) {
+        if (value !== undefined && !BOOLEAN_OPTION_VALUES.has(value.toLowerCase())) {
+            throw Error(`Invalid option ${name} "${value}": must be one of "true", "false", "1", "0"`);
+        }
+    }
+    // rpcUrl commonly embeds a provider API key and is never needed by clients; refuse to publish it.
+    if (challengeSettings.publicOptions?.includes("rpcUrl")) {
+        throw Error('Option rpcUrl must not be in publicOptions: it may contain RPC provider credentials');
+    }
+};
 /**
  * Challenge file factory function
  */
@@ -526,7 +563,8 @@ function ChallengeFileFactory({ challengeSettings }) {
         getChallenge,
         optionInputs,
         type,
-        description
+        description,
+        validateChallengeSettings
     };
 }
 export default ChallengeFileFactory;

challenge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitsocial/mintpass-challenge",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "MintPass pkc-js challenge implementation",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,8 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "corepack yarn build && ./scripts/test-with-node.sh",
+    "test": "corepack yarn test:unit && ./scripts/test-with-node.sh",
+    "test:unit": "corepack yarn build && node --test test/validate-challenge-settings.test.js",
     "test:manual": "corepack yarn build && cd ../contracts && corepack yarn hardhat test ../challenge/test/mintpass-integration.test.js --network localhost",
     "clean": "rm -rf dist/",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
@@ -39,7 +40,7 @@
     "viem": "2.45.0"
   },
   "devDependencies": {
-    "@pkcprotocol/pkc-js": "0.0.16",
+    "@pkcprotocol/pkc-js": "0.0.85",
     "@types/chai": "^4.2.0",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.7.8",

challenge/src/mintpass.ts

@@ -643,6 +643,47 @@ const getChallenge = async ({
     } as ChallengeResultInput;
 };
 
+// Boolean-like option values accepted by getChallenge ("true"/"1" are truthy, everything else is falsy).
+// Anything outside this set is almost certainly a typo that would silently read as false.
+const BOOLEAN_OPTION_VALUES = new Set(["true", "false", "1", "0"]);
+// Tickers that _getChainProviderWithSafety / createViemClientForChain can actually resolve.
+const SUPPORTED_CHAIN_TICKERS = new Set(["eth", "base"]);
+const MAX_TOKEN_TYPE = 65535; // tokenType is a uint16 in the MintPass ABI
+const isNonNegativeIntegerString = (value: string) => /^\d+$/.test(value) && Number.isSafeInteger(Number(value));
+
+/**
+ * Semantic validation of challenge settings, run by pkc-js on community edit/create/start.
+ * Must stay sync and network-free. Presence of required options is enforced by pkc-js core
+ * via optionInputs; this hook checks that the values actually parse.
+ */
+const validateChallengeSettings: NonNullable<ChallengeFileInput["validateChallengeSettings"]> = ({ challengeSettings }) => {
+    const options = challengeSettings.options || {};
+    const { chainTicker, contractAddress, requiredTokenType, transferCooldownSeconds, bindToFirstAuthor, noChallengeUrl } = options;
+
+    if (chainTicker !== undefined && !SUPPORTED_CHAIN_TICKERS.has(chainTicker)) {
+        throw Error(`Invalid option chainTicker "${chainTicker}": must be one of ${[...SUPPORTED_CHAIN_TICKERS].map((t) => `"${t}"`).join(", ")}`);
+    }
+    if (contractAddress !== undefined && !isAddress(contractAddress)) {
+        throw Error(`Invalid option contractAddress "${contractAddress}": must be a well-formed EVM address`);
+    }
+    if (requiredTokenType !== undefined && (!isNonNegativeIntegerString(requiredTokenType) || Number(requiredTokenType) > MAX_TOKEN_TYPE)) {
+        throw Error(`Invalid option requiredTokenType "${requiredTokenType}": must be an integer between 0 and ${MAX_TOKEN_TYPE}`);
+    }
+    if (transferCooldownSeconds !== undefined && !isNonNegativeIntegerString(transferCooldownSeconds)) {
+        throw Error(`Invalid option transferCooldownSeconds "${transferCooldownSeconds}": must be a non-negative integer`);
+    }
+    for (const [name, value] of [["bindToFirstAuthor", bindToFirstAuthor], ["noChallengeUrl", noChallengeUrl]] as const) {
+        if (value !== undefined && !BOOLEAN_OPTION_VALUES.has(value.toLowerCase())) {
+            throw Error(`Invalid option ${name} "${value}": must be one of "true", "false", "1", "0"`);
+        }
+    }
+
+    // rpcUrl commonly embeds a provider API key and is never needed by clients; refuse to publish it.
+    if (challengeSettings.publicOptions?.includes("rpcUrl")) {
+        throw Error('Option rpcUrl must not be in publicOptions: it may contain RPC provider credentials');
+    }
+};
+
 /**
  * Challenge file factory function
  */
@@ -653,7 +694,8 @@ function ChallengeFileFactory({ challengeSettings }: { challengeSettings: Commun
         getChallenge,
         optionInputs,
         type,
-        description
+        description,
+        validateChallengeSettings
     };
 }