Add connection proof, reliable provider detection, and provider docs

- Content script runs at document_start for early injection
- Injected script listens for xcp-wallet#discover for re-announcement
- xcp_requestAccounts returns { accounts, proof } with auto-signed
  BIP-322 proof of address ownership (no user signing prompt)
- Proof includes origin, nonce, timestamp, and verification hints
- Add PROVIDER.md documenting all provider methods and SDK usage

Author: droplister

PROVIDER.md

@@ -0,0 +1,257 @@
+# XCP Wallet Provider API
+
+The XCP Wallet browser extension injects a provider at `window.xcpwallet` on all HTTPS pages. Websites use this provider to connect wallets, sign messages, compose transactions, and broadcast to the Bitcoin network.
+
+## Detection
+
+The provider is injected at `document_start` — before page scripts run. Two detection methods:
+
+```js
+// Synchronous (provider already injected)
+if (window.xcpwallet) {
+  // ready
+}
+
+// Asynchronous (wait for injection)
+window.addEventListener('xcp-wallet#initialized', () => {
+  // window.xcpwallet is now available
+});
+
+// Request re-announcement (for SPAs that mount after injection)
+window.dispatchEvent(new Event('xcp-wallet#discover'));
+```
+
+## Provider Interface
+
+```ts
+interface XcpProvider {
+  request(args: { method: string; params?: unknown[] }): Promise<unknown>
+  on(event: string, handler: (...args: any[]) => void): void
+  removeListener(event: string, handler: (...args: any[]) => void): void
+}
+```
+
+## Methods
+
+### Connection
+
+#### `xcp_requestAccounts`
+
+Connect to the wallet. Opens a popup for user approval on first connection.
+
+Returns a connection proof — a BIP-322 signature proving the user controls the address. The proof message is generated by the extension (not the website) and includes the requesting origin, a random nonce, and a timestamp.
+
+```js
+const result = await xcpwallet.request({ method: 'xcp_requestAccounts' });
+// {
+//   accounts: ['bc1q...'],
+//   proof: {
+//     address: 'bc1q...',
+//     message: 'xcp-wallet\norigin:https://example.com\nnonce:a1b2c3d4\nissued:1711130400',
+//     signature: '<BIP-322 signature>',
+//     verification: {
+//       method: 'BIP-322',
+//       format: 'p2wpkh'   // address format used for signing
+//     }
+//   }
+// }
+```
+
+**Proof verification (server-side):**
+
+1. Parse the `message` — verify `origin` matches your domain and `issued` is recent (< 5 minutes)
+2. Verify the BIP-322 signature against the `address` using the `verification.format` hint
+3. Optionally store the `nonce` to prevent replay
+
+The proof is auto-signed during connection — no additional user prompt beyond the connect approval.
+
+#### `xcp_accounts`
+
+Get currently connected accounts. No popup — returns empty array if not connected or wallet is locked.
+
+```js
+const accounts = await xcpwallet.request({ method: 'xcp_accounts' });
+// ['bc1q...'] or []
+```
+
+#### `xcp_disconnect`
+
+Disconnect the current site.
+
+```js
+await xcpwallet.request({ method: 'xcp_disconnect' });
+// true
+```
+
+### Signing
+
+All signing methods require an active connection and open a popup for user approval.
+
+#### `xcp_signMessage`
+
+Sign a message with the active address using BIP-322.
+
+```js
+const result = await xcpwallet.request({
+  method: 'xcp_signMessage',
+  params: ['Hello, world!']
+});
+// { signature: '<base64 BIP-322 signature>' }
+```
+
+An optional second parameter can specify the address (must match the active address):
+
+```js
+params: ['Hello, world!', 'bc1q...']
+```
+
+#### `xcp_signTransaction`
+
+Sign a raw transaction hex.
+
+```js
+const result = await xcpwallet.request({
+  method: 'xcp_signTransaction',
+  params: [{ hex: '0200000001...' }]
+});
+// { hex: '<signed transaction hex>' }
+
+// Also accepts a plain string:
+params: ['0200000001...']
+```
+
+#### `xcp_signPsbt`
+
+Sign a PSBT (Partially Signed Bitcoin Transaction).
+
+```js
+const result = await xcpwallet.request({
+  method: 'xcp_signPsbt',
+  params: [{
+    hex: '<PSBT hex>',
+    signInputs: { 'bc1q...': [0, 1] },  // optional: which inputs to sign
+    sighashTypes: [0x01]                  // optional: sighash types
+  }]
+});
+// { hex: '<signed PSBT hex>' }
+```
+
+### Broadcasting
+
+#### `xcp_broadcastTransaction`
+
+Broadcast a signed transaction to the Bitcoin network. Includes replay protection — the same transaction cannot be broadcast twice.
+
+```js
+const result = await xcpwallet.request({
+  method: 'xcp_broadcastTransaction',
+  params: ['<signed transaction hex>']
+});
+// { txid: '<64-char transaction hash>' }
+```
+
+### Read-Only
+
+#### `xcp_getBalances`
+
+Get BTC and token balances for the connected address.
+
+```js
+const result = await xcpwallet.request({ method: 'xcp_getBalances' });
+// { address: 'bc1q...', btc: { ... }, xcp: { ... }, tokens: [...] }
+```
+
+#### `xcp_chainId`
+
+```js
+await xcpwallet.request({ method: 'xcp_chainId' });
+// '0x0' (Bitcoin mainnet)
+```
+
+#### `xcp_getNetwork`
+
+```js
+await xcpwallet.request({ method: 'xcp_getNetwork' });
+// 'mainnet'
+```
+
+## Events
+
+```js
+// Account changed (address switch or connect/disconnect)
+xcpwallet.on('accountsChanged', (accounts) => {
+  // accounts: string[] — empty on disconnect
+});
+
+// Wallet disconnected this site
+xcpwallet.on('disconnect', () => {
+  // Connection revoked
+});
+```
+
+## SDK
+
+An SDK is available for React/Next.js applications at [`lib/wallet/sdk`](https://github.com/XCP/exchange/tree/master/apps/web/src/lib/wallet/sdk). Copy the `sdk/` folder into your project:
+
+```
+lib/wallet/
+├── sdk/
+│   ├── constants.ts   — validation patterns, error codes
+│   ├── detect.ts      — provider detection with race condition handling
+│   ├── errors.ts      — user-friendly error messages
+│   ├── index.ts       — public exports
+│   ├── provider.ts    — typed XcpWallet wrapper class
+│   ├── types.ts       — TypeScript interfaces
+│   └── verify.ts      — connection proof validation
+├── wallet-context.tsx — React context provider (useWallet hook)
+└── useCompose.ts      — compose → sign → broadcast pipeline
+```
+
+### React usage
+
+```tsx
+import { WalletProvider, useWallet } from '@/lib/wallet/wallet-context';
+
+// Wrap your app
+<WalletProvider>{children}</WalletProvider>
+
+// In components
+const { status, address, connectionProof, connect, disconnect } = useWallet();
+// status: 'not_detected' | 'disconnected' | 'connected'
+```
+
+### Direct usage (non-React)
+
+```ts
+import { detectProvider, XcpWallet } from '@/lib/wallet/sdk';
+
+const provider = await detectProvider();
+const wallet = new XcpWallet(provider);
+const { accounts, proof } = await wallet.connect();
+```
+
+### Proof verification
+
+```ts
+import { validateProof } from '@/lib/wallet/sdk';
+
+// Client-side (structural checks only)
+const result = await validateProof(proof, 'https://example.com', address);
+
+// Server-side (with cryptographic verification)
+const result = await validateProof(proof, origin, address, {
+  verifySignature: async (message, signature, addr) => {
+    // Use your BIP-322 verification library
+    return await verifyBIP322(message, signature, addr);
+  }
+});
+```
+
+## Security
+
+- **Origin validation**: The content script provides the origin — page JavaScript cannot spoof it
+- **Connection proof**: BIP-322 signature proving address ownership, message format controlled by extension
+- **Rate limiting**: Connection, transaction, and API requests are rate-limited per origin
+- **Replay protection**: Broadcast transactions are tracked to prevent double-submission
+- **Parameter validation**: All inputs are type-checked and size-limited (max 1MB)
+- **CSP analysis**: Sites without Content Security Policy generate console warnings

src/entrypoints/content.ts

@@ -7,6 +7,7 @@ const matches = ['https://*/*', 'http://localhost/*', 'http://127.0.0.1/*'];
 
 export default defineContentScript({
   matches,
+  runAt: 'document_start',
   async main(ctx) {
     /**
      * CRITICAL: Send "ready" signal to background immediately

src/entrypoints/injected.ts

@@ -112,10 +112,12 @@ export default defineUnlistedScript(() => {
     }
 
     // Update accounts state from account-related responses
-    if (data?.method === 'xcp_requestAccounts' || data?.method === 'xcp_accounts') {
-      if (Array.isArray(data.result)) {
-        updateAccounts(data.result);
-      }
+    if (data?.method === 'xcp_requestAccounts') {
+      // New shape: { accounts: string[], proof: ... }
+      const accts = data.result?.accounts ?? data.result;
+      if (Array.isArray(accts)) updateAccounts(accts);
+    } else if (data?.method === 'xcp_accounts') {
+      if (Array.isArray(data.result)) updateAccounts(data.result);
     }
 
     pending.resolve(data?.result);
@@ -206,6 +208,14 @@ export default defineUnlistedScript(() => {
     enumerable: true
   });
 
+  // Announce provider is available
   window.dispatchEvent(new Event('xcp-wallet#initialized'));
+
+  // Re-announce whenever a dApp asks — handles dApps that load before the
+  // content script injects, or single-page apps that mount later.
+  window.addEventListener('xcp-wallet#discover', () => {
+    window.dispatchEvent(new Event('xcp-wallet#initialized'));
+  });
+
   console.log('XCP Wallet provider initialized');
 });

src/services/__tests__/providerService.test.ts

@@ -56,6 +56,9 @@ vi.mock('@/utils/wallet/walletManager', () => ({
   },
 }));
 vi.mock('@/utils/storage/signMessageRequestStorage');
+vi.mock('@/utils/blockchain/bitcoin/messageSigner', () => ({
+  signMessage: vi.fn().mockResolvedValue({ signature: 'mock-proof-sig', address: 'bc1qtest123' }),
+}));
 vi.mock('@/utils/storage/signPsbtRequestStorage');
 vi.mock('@/services/updateService');
 vi.mock('@/utils/provider/approvalQueue');
@@ -191,7 +194,7 @@ describe('ProviderService', () => {
       updateWalletAddressFormat: vi.fn(),
       updateWalletPinnedAssets: vi.fn(),
       getUnencryptedMnemonic: vi.fn(),
-      getPrivateKey: vi.fn(),
+      getPrivateKey: vi.fn().mockResolvedValue({ hex: 'deadbeef'.repeat(8), wif: 'test-wif', compressed: true }),
       removeWallet: vi.fn(),
       getPreviewAddressForFormat: vi.fn(),
       signTransaction: vi.fn(),
@@ -310,9 +313,10 @@ describe('ProviderService', () => {
           'https://test.com',
           'xcp_requestAccounts',
           []
-        );
+        ) as any;
 
-        expect(result).toEqual(['bc1qtest123']);
+        expect(result.accounts).toEqual(['bc1qtest123']);
+        expect(result.proof).toBeDefined();
       });
 
       it('should request permission if not connected', async () => {
@@ -335,8 +339,9 @@ describe('ProviderService', () => {
           'wallet1'       // activeWallet.id from mock (no hyphen)
         );
 
-        // Should return the accounts
-        expect(result).toEqual(['bc1qtest123']);
+        // Should return accounts with proof
+        expect((result as any).accounts).toEqual(['bc1qtest123']);
+        expect((result as any).proof).toBeDefined();
       });
 
     });