feat(core): let the backend decide whether a request is served

apps/docs/docs/pages/account/index.mdx

@@ -122,8 +122,8 @@ Configuration for creating or loading an account. React Native options (`nativeG
 interface AccountConfig {
   /** Chain ID for the account */
   chainId: number;
-  /** API key for JAW services (required) */
-  apiKey: string;
+  /** API key for JAW services, if the caller has one */
+  apiKey?: string;
   /** Custom paymaster URL for gas sponsorship */
   paymasterUrl?: string;
   /** Custom paymaster context for gas sponsorship */

apps/docs/docs/pages/configuration/apiKey.mdx

@@ -3,7 +3,11 @@
 Your JAW API key for authentication with JAW services.
 
 **Type:** `string`
-**Required:** Yes
+**Required:** In [app-specific mode](/configuration/mode/app-specific). Optional in cross-platform mode, which is the default.
+
+In cross-platform mode the SDK sends whatever it has and the backend decides whether to answer. With a key, the request is attributed to the project that key belongs to, and the allowed domains below are what the key is checked against. Without a key, the caller is identified by the origin the request comes from, and only origins registered with JustaName are served, so ask the team to register yours before dropping the option.
+
+App-specific mode always needs a key, because it hands one to the UI handler your application implements. `JAW.create()` rejects an app-specific configuration without one.
 
 ## Usage
 
@@ -27,6 +31,14 @@ const jaw = JAW.create({
 });
 ```
 
+### Without a key
+
+```typescript
+const connector = jaw({ appName: 'My DApp' });
+```
+
+Requests then carry no `api-key` parameter, and the origin your application runs on is what names it. An origin nobody registered is refused.
+
 ## How to Get an API Key
 
 1. Visit the [JAW Dashboard](https://dashboard.jaw.id/)

apps/docs/docs/pages/configuration/index.mdx

@@ -117,7 +117,7 @@ await jaw.disconnect();
 
 ## Minimal Configuration
 
-The only required option is `apiKey`:
+Every option is optional in cross-platform mode, the default. A request without an [apiKey](/configuration/apiKey) is identified by the origin it comes from, which JustaName has to have registered beforehand.
 
 ```typescript
 // Wagmi
@@ -127,6 +127,8 @@ const connector = jaw({ apiKey: 'your-api-key' });
 const jaw = JAW.create({ apiKey: 'your-api-key' });
 ```
 
+[App-specific mode](/configuration/mode/app-specific) is the exception: it requires `apiKey` and a `uiHandler`.
+
 ## Related
 
 - [Wagmi Integration](/wagmi) - Using with Wagmi

apps/keys-jaw-id/src/app/page.tsx

@@ -11,6 +11,7 @@ import type { TransactionRequestData } from '../components/TransactionModal';
 import { useAuth, usePasskeys } from '../hooks';
 import { SignInScreen, type AuthenticatedAccount } from '../components/OnboardingSection';
 import { PasskeyManager, type PasskeyAccount } from '@jaw.id/core';
+import { setDappOrigin } from '@jaw.id/core/internal';
 import { SiweModal } from '../components/SiweModal';
 import { ensureIntNumber, type SignInWithEthereumCapabilityRequest } from '@jaw.id/core';
 import { ConnectModal } from '../components/ConnectModal';
@@ -317,6 +318,11 @@ function KeysJawIdAppContent({
         if (message.data.apiKey) {
           setApiKey(message.data.apiKey);
         }
+        // The keyless counterpart of that bootstrap. Without a key the origin is the only
+        // thing that names the dApp, and the account screen below reads addresses over the
+        // proxy before any handshake runs. The message that triggered this handler is what
+        // locked the origin, so it is already available here.
+        setDappOrigin(communicator.getOrigin() || undefined);
 
         // Apply the dApp's theme tokens so the embedded dialog matches its
         // look & feel (accent color, border radius, light/dark), translated
@@ -560,9 +566,14 @@ function KeysJawIdAppContent({
       }
 
       // Get origin and set it as current context
-      const origin = communicator.getOrigin() || '';
+      const origin = communicator.getOrigin() ?? '';
       setCurrentOrigin(origin);
       cryptoHandler.setOrigin(origin);
+      // Our own Origin is the same whichever dApp opened us, so the backend
+      // cannot tell which one a call belongs to unless we say. An unknown origin
+      // goes through as unset rather than as '': it clears whatever the last
+      // request left behind, so a call is never credited to the wrong dApp.
+      setDappOrigin(origin || undefined);
 
       const peerPublicKey = request.sender;
       const method = request.content.handshake.method;
@@ -720,10 +731,14 @@ function KeysJawIdAppContent({
 
     try {
       // Load session for this origin
-      const origin = communicator.getOrigin() || '';
+      const origin = communicator.getOrigin() ?? '';
 
       // Update React state with current origin (needed for useAuth hook)
       setCurrentOrigin(origin);
+      // Set again rather than relying on the handshake having run in this
+      // document: the origin the backend is told comes from the request being
+      // served, not from an earlier one.
+      setDappOrigin(origin || undefined);
 
       // Reply to the SDK with a reconnect-required sentinel (tied to this
       // request id, carries no secret) so it re-establishes a session against

apps/keys-jaw-id/src/components/AddFundsModal/index.tsx

@@ -16,6 +16,7 @@ import {
   type Address,
 } from '@jaw.id/core';
 import { useAuth } from '../../hooks';
+import { apiKeyFromChain } from '../../lib/api-key';
 
 export interface AddFundsModalProps {
   /** The dapp's raw params, validated here before anything renders. */
@@ -67,17 +68,7 @@ export const AddFundsModal = ({
     }
   }, [params]);
 
-  const prodApiKey = useMemo(() => {
-    if (apiKey) return apiKey;
-    if (chain?.rpcUrl) {
-      try {
-        return new URL(chain.rpcUrl).searchParams.get('api-key') || '';
-      } catch {
-        return '';
-      }
-    }
-    return '';
-  }, [apiKey, chain?.rpcUrl]);
+  const prodApiKey = useMemo(() => apiKeyFromChain(apiKey, chain?.rpcUrl), [apiKey, chain?.rpcUrl]);
 
   const mainnetRpcUrl = prodApiKey ? `${JAW_RPC_URL}?chainId=1&api-key=${prodApiKey}` : `${JAW_RPC_URL}?chainId=1`;
 

apps/keys-jaw-id/src/components/ConnectModal/index.tsx

@@ -6,6 +6,7 @@ import { useMemo, useState } from 'react';
 import type { chain } from '../../lib/sdk-types';
 import { getChainNameFromId } from '../../lib/chain-handlers';
 import { standardErrorCodes, JAW_RPC_URL } from '@jaw.id/core';
+import { apiKeyFromChain } from '../../lib/api-key';
 
 export interface ConnectModalProps {
   origin: string;
@@ -33,36 +34,18 @@ export const ConnectModal = ({
   const [isProcessing, setIsProcessing] = useState<boolean>(false);
 
   // Extract API key from rpcUrl if not provided as prop
-  const effectiveApiKey = useMemo(() => {
-    if (apiKey) return apiKey;
-    if (chain?.rpcUrl) {
-      try {
-        const url = new URL(chain.rpcUrl);
-        return url.searchParams.get('api-key') || '';
-      } catch {
-        return '';
-      }
-    }
-    return '';
-  }, [apiKey, chain?.rpcUrl]);
+  const effectiveApiKey = useMemo(() => apiKeyFromChain(apiKey, chain?.rpcUrl), [apiKey, chain?.rpcUrl]);
 
   // Get chain name and icon
   const chainName = useMemo(() => (chain ? getChainNameFromId(chain.id) : undefined), [chain]);
   const chainIcon = useChainIconURI(chain?.id || 1, effectiveApiKey, 24);
 
-  // Extract API key from chain.rpcUrl for mainnet RPC URL
-  const mainnetRpcUrl = useMemo(() => {
-    if (chain?.rpcUrl) {
-      try {
-        const url = new URL(chain.rpcUrl);
-        const apiKey = url.searchParams.get('api-key');
-        return apiKey ? `${JAW_RPC_URL}?chainId=1&api-key=${apiKey}` : `${JAW_RPC_URL}?chainId=1`;
-      } catch {
-        return `${JAW_RPC_URL}?chainId=1`;
-      }
-    }
-    return `${JAW_RPC_URL}?chainId=1`;
-  }, [chain?.rpcUrl]);
+  // Mainnet, for ENS, under whatever key this request carries: the same one the
+  // chain icon above resolves with, so the two cannot disagree about who is asking.
+  const mainnetRpcUrl = useMemo(
+    () => (effectiveApiKey ? `${JAW_RPC_URL}?chainId=1&api-key=${effectiveApiKey}` : `${JAW_RPC_URL}?chainId=1`),
+    [effectiveApiKey]
+  );
 
   const handleConnect = async () => {
     try {

apps/keys-jaw-id/src/components/Eip712Modal/index.tsx

@@ -7,6 +7,7 @@ import { useCallback, useMemo, useState } from 'react';
 import type { chain } from '../../lib/sdk-types';
 import { getChainNameFromId } from '../../lib/chain-handlers';
 import { standardErrorCodes, JAW_RPC_URL } from '@jaw.id/core';
+import { apiKeyFromChain } from '../../lib/api-key';
 
 export interface Eip712ModalProps {
   origin: string;
@@ -56,18 +57,7 @@ export const Eip712Modal = ({
   const [signatureStatus, setSignatureStatus] = useState<string>('');
 
   // Extract API key for other uses (chain icon, mainnet RPC)
-  const effectiveApiKey = useMemo(() => {
-    if (apiKey) return apiKey;
-    if (chain?.rpcUrl) {
-      try {
-        const url = new URL(chain.rpcUrl);
-        return url.searchParams.get('api-key') || '';
-      } catch {
-        return '';
-      }
-    }
-    return '';
-  }, [apiKey, chain?.rpcUrl]);
+  const effectiveApiKey = useMemo(() => apiKeyFromChain(apiKey, chain?.rpcUrl), [apiKey, chain?.rpcUrl]);
 
   // Compute mainnet RPC URL for JustaName SDK (ENS resolution)
   const mainnetRpcUrl = useMemo(() => {

apps/keys-jaw-id/src/components/PermissionModal/index.tsx

@@ -32,6 +32,7 @@ import {
   handleGetCapabilitiesRequest,
   type FeeTokenCapability,
 } from '@jaw.id/core';
+import { apiKeyFromChain } from '../../lib/api-key';
 
 // Known function selectors mapping
 // Permission request data
@@ -149,22 +150,7 @@ export const PermissionModal = ({
   const [feeTokens, setFeeTokens] = useState<FeeTokenOption[]>([]);
   const [feeTokensLoading, setFeeTokensLoading] = useState<boolean>(true);
 
-  // Extract API key from rpcUrl if not provided as prop
-  const extractedApiKey = useMemo(() => {
-    if (apiKey) return apiKey;
-
-    if (chain?.rpcUrl) {
-      try {
-        const url = new URL(chain.rpcUrl);
-        return url.searchParams.get('api-key') || '';
-      } catch (error) {
-        console.error('Failed to parse rpcUrl:', error);
-        return '';
-      }
-    }
-
-    return '';
-  }, [apiKey, chain?.rpcUrl]);
+  const extractedApiKey = useMemo(() => apiKeyFromChain(apiKey, chain?.rpcUrl), [apiKey, chain?.rpcUrl]);
 
   // Note: Account initialization is handled by useSessionAccount hook
 
@@ -493,7 +479,10 @@ export const PermissionModal = ({
     let isMounted = true;
 
     const fetchFeeTokensData = async () => {
-      if (!viemChain || !extractedApiKey) {
+      // The chain, and nothing else: keyless the capabilities come back on the
+      // origin, and gating on the key here left this dialog without its fee row
+      // while the transaction dialog of the same session showed one.
+      if (!viemChain) {
         setFeeTokensLoading(false);
         return;
       }
@@ -504,7 +493,7 @@ export const PermissionModal = ({
         // Fetch capabilities from JAW RPC
         const capabilities = await handleGetCapabilitiesRequest(
           { method: 'wallet_getCapabilities', params: [] },
-          extractedApiKey || '',
+          extractedApiKey,
           true // showTestnets
         );
 

apps/keys-jaw-id/src/components/SignatureModal/index.tsx

@@ -7,6 +7,7 @@ import { useCallback, useMemo, useState } from 'react';
 import type { chain } from '../../lib/sdk-types';
 import { getChainNameFromId } from '../../lib/chain-handlers';
 import { standardErrorCodes, JAW_RPC_URL } from '@jaw.id/core';
+import { apiKeyFromChain } from '../../lib/api-key';
 
 export interface SignatureModalProps {
   origin: string;
@@ -48,18 +49,7 @@ export const SignatureModal = ({
   const [signatureStatus, setSignatureStatus] = useState<string>('');
 
   // Extract API key for other uses (chain icon, mainnet RPC)
-  const effectiveApiKey = useMemo(() => {
-    if (apiKey) return apiKey;
-    if (chain?.rpcUrl) {
-      try {
-        const url = new URL(chain.rpcUrl);
-        return url.searchParams.get('api-key') || '';
-      } catch {
-        return '';
-      }
-    }
-    return '';
-  }, [apiKey, chain?.rpcUrl]);
+  const effectiveApiKey = useMemo(() => apiKeyFromChain(apiKey, chain?.rpcUrl), [apiKey, chain?.rpcUrl]);
 
   // Compute mainnet RPC URL for JustaName SDK (ENS resolution)
   const mainnetRpcUrl = useMemo(() => {

apps/keys-jaw-id/src/components/SiweModal/index.tsx

@@ -7,6 +7,7 @@ import { useCallback, useMemo, useState } from 'react';
 import type { chain } from '../../lib/sdk-types';
 import { getChainNameFromId } from '../../lib/chain-handlers';
 import { standardErrorCodes, JAW_RPC_URL } from '@jaw.id/core';
+import { apiKeyFromChain } from '../../lib/api-key';
 
 export interface SiweModalProps {
   origin: string;
@@ -50,18 +51,7 @@ export const SiweModal = ({
   const [siweStatus, setSiweStatus] = useState<string>('');
 
   // Extract API key for other uses (chain icon, mainnet RPC)
-  const effectiveApiKey = useMemo(() => {
-    if (apiKey) return apiKey;
-    if (chain?.rpcUrl) {
-      try {
-        const url = new URL(chain.rpcUrl);
-        return url.searchParams.get('api-key') || '';
-      } catch {
-        return '';
-      }
-    }
-    return '';
-  }, [apiKey, chain?.rpcUrl]);
+  const effectiveApiKey = useMemo(() => apiKeyFromChain(apiKey, chain?.rpcUrl), [apiKey, chain?.rpcUrl]);
 
   // Compute mainnet RPC URL for JustaName SDK (ENS resolution)
   const mainnetRpcUrl = useMemo(() => {

apps/keys-jaw-id/src/components/TransactionModal/index.tsx

@@ -25,6 +25,7 @@ import {
   JAW_RPC_URL,
   type FeeTokenCapability,
 } from '@jaw.id/core';
+import { apiKeyFromChain } from '../../lib/api-key';
 
 // Transaction execution result
 export interface TransactionResult {
@@ -103,18 +104,7 @@ export const TransactionModal = ({
   const [feeTokensLoading, setFeeTokensLoading] = useState(false);
 
   // Extract API key from rpcUrl if not provided as prop
-  const effectiveApiKey = useMemo(() => {
-    if (apiKey) return apiKey;
-    if (chain?.rpcUrl) {
-      try {
-        const url = new URL(chain.rpcUrl);
-        return url.searchParams.get('api-key') || '';
-      } catch {
-        return '';
-      }
-    }
-    return '';
-  }, [apiKey, chain?.rpcUrl]);
+  const effectiveApiKey = useMemo(() => apiKeyFromChain(apiKey, chain?.rpcUrl), [apiKey, chain?.rpcUrl]);
 
   // Determine if sponsored based on transactionRequest or prop
   const isSponsored = useMemo(() => {
@@ -302,7 +292,7 @@ export const TransactionModal = ({
         // Fetch capabilities from JAW RPC
         const capabilities = await handleGetCapabilitiesRequest(
           { method: 'wallet_getCapabilities', params: [] },
-          effectiveApiKey || '',
+          effectiveApiKey,
           true // showTestnets
         );