# Custom signers (KMS and HSM)

Every SDK signing function takes a `signer`: any object with one method.

```ts
interface TypedDataSigner {
  signTypedData(
    domain: TypedDataDomain,
    types: Record<string, TypedDataField[]>,
    value: Record<string, unknown>,
  ): Promise<string>; // 65-byte signature, 0x-hex
}
```

An ethers `Wallet` fits as is. For production, keep the quote key in a KMS or HSM and wrap it.

## Wrap a KMS

Most KMS products sign a 32-byte digest and return `r` and `s` with no recovery byte. This adapter:

1. hashes the EIP-712 message;
2. asks your KMS to sign the digest;
3. folds `s` into the lower half, which the program requires;
4. finds the recovery byte by checking which one recovers your quote key.

```ts
import { Signature, TypedDataEncoder, recoverAddress, toBeHex, zeroPadValue } from 'ethers';
import { assertCanonicalSignature, type TypedDataSigner } from '@covrfun/maker-sdk';

const N = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n; // secp256k1 order

/** Wrap any KMS or HSM that signs a 32-byte digest and returns r and s (no v). */
export function kmsSigner(
  quoteKeyAddress: string,
  signDigest: (digest: string) => Promise<{ r: bigint; s: bigint }>,
): TypedDataSigner {
  return {
    async signTypedData(domain, types, value) {
      const digest = TypedDataEncoder.hash(domain, types, value);
      let { r, s } = await signDigest(digest);
      if (s > N / 2n) s = N - s; // the program accepts low-s only
      const rHex = zeroPadValue(toBeHex(r), 32), sHex = zeroPadValue(toBeHex(s), 32);
      for (const v of [27, 28] as const) {
        const signature = Signature.from({ r: rHex, s: sHex, v }).serialized;
        if (recoverAddress(digest, signature).toLowerCase() === quoteKeyAddress.toLowerCase()) {
          assertCanonicalSignature(signature);
          return signature;
        }
      }
      throw Error('KMS signature does not recover to the quote key');
    },
  };
}
```

`signIntent` and `signQuote` check the result again. They refuse a signature that does not recover to the maker named in the message, or one with a high `s`.

## Prove it with the golden vectors

The package ships `vectors/golden-vectors.json`. It holds every message type a desk signs, already signed with a public throwaway key:

```text
privateKey = keccak256(utf8("covr-maker-sdk-golden-vectors-v1"))
address    = 0x7B99e6A7407Fe0058119F4f13494C0b9cec35738
```

Each entry carries standard `eth_signTypedData_v4` JSON (`domain`, `types`, `primaryType`, `message`), the expected `digest` and the expected `signature`. Feed the typed data to your stack and compare:

- **Digests must match exactly.** A different digest means your encoding differs from covr's.
- **Signatures match exactly only for deterministic signers** (RFC 6979), such as ethers. Many KMS and HSM services pick a random nonce. Their signatures differ from the vectors and are still valid. For those, check that each signature recovers to the vector address and passes `assertCanonicalSignature`.

```ts
import { readFile } from 'node:fs/promises';
import { createRequire } from 'node:module';
import { Wallet, TypedDataEncoder, keccak256, recoverAddress, toUtf8Bytes } from 'ethers';
import { assertCanonicalSignature } from '@covrfun/maker-sdk';

const require = createRequire(import.meta.url);
const file = require.resolve('@covrfun/maker-sdk/vectors/golden-vectors.json');
const v = JSON.parse(await readFile(file, 'utf8'));

// The vectors' throwaway key. Replace this signer with your KMS or HSM adapter.
const signer = new Wallet(keccak256(toUtf8Bytes(v.key.seed)));

for (const name of ['registration', 'bidIntent', 'quote', 'withdrawal']) {
  const { domain, types, message } = v[name].typedData;
  const { EIP712Domain, ...signedTypes } = types; // ethers derives the domain type itself
  void EIP712Domain;
  const digest = TypedDataEncoder.hash(domain, signedTypes, message);
  const signature = await signer.signTypedData(domain, signedTypes, message);
  if (digest !== v[name].digest) { console.log(name.padEnd(12), 'DIGEST MISMATCH', digest); continue; }
  assertCanonicalSignature(signature); // throws on a high-s signature
  const recovers = recoverAddress(digest, signature) === v.key.address;
  // Deterministic signers (RFC 6979, like ethers) reproduce the vector exactly.
  // A random-nonce KMS gives a different, equally valid signature: it must still recover.
  console.log(name.padEnd(12), signature === v[name].signature ? 'match' : recovers ? 'valid (recovers)' : 'SIGNATURE MISMATCH');
}
```

Expected output:

```text
registration match
bidIntent    match
quote        match
withdrawal   match
```

To test your KMS adapter itself, import the throwaway key into a test KMS key and wrap it with `kmsSigner`. Then run the same loop, checking the digest exactly and the signature by recovery.

> [!CAUTION]
> The golden-vector key is public. Never fund it or register it.

---

Source: https://docs.covr.markets/guides/custom-signer · Part of covr Docs, https://docs.covr.markets/llms.txt
