Add SignatureBytes assertion, guard, and coercion methods (#901)

* do it

* do it

* add docs

* update docs

* ship it

* ship it

* Add changeset

* Update packages/keys/src/__tests__/signatures-test.ts

Co-authored-by: Steven Luscher <steveluscher@users.noreply.github.com>

* Update packages/keys/src/__typetests__/signatures-typetest.ts

Co-authored-by: Steven Luscher <steveluscher@users.noreply.github.com>

* Update packages/keys/src/__tests__/signatures-test.ts

Co-authored-by: Steven Luscher <steveluscher@users.noreply.github.com>

* address nits

* fix typetest

* remove empty line

---------

Co-authored-by: Steven Luscher <steveluscher@users.noreply.github.com>

Author: guibescos

.changeset/chilly-shoes-rest.md

@@ -0,0 +1,5 @@
+---
+"@solana/keys": patch
+---
+
+Added assertion (`assertIsSignatureBytes`), guard (`isSignatureBytes`), and coercion (`signatureBytes`) methods to make it easier to work with callsites that demand a `SignatureBytes` type

docs/content/api/index.mdx

@@ -831,18 +831,21 @@ Welcome to the Solana Kit API Reference! It covers a total of **39 packages** mo
 
 </div>
 
-<p className="text-xs tracking-wider uppercase mt-8 -mb-2 text-linen-500 dark:text-linen-400">Functions (10)</p>
+<p className="text-xs tracking-wider uppercase mt-8 -mb-2 text-linen-500 dark:text-linen-400">Functions (13)</p>
 
 <div className="*:columns-[20rem] *:gap-8">
 
 [assertIsSignature](/api/functions/assertIsSignature) \
+[assertIsSignatureBytes](/api/functions/assertIsSignatureBytes) \
 [createKeyPairFromBytes](/api/functions/createKeyPairFromBytes) \
 [createKeyPairFromPrivateKeyBytes](/api/functions/createKeyPairFromPrivateKeyBytes) \
 [createPrivateKeyFromBytes](/api/functions/createPrivateKeyFromBytes) \
 [generateKeyPair](/api/functions/generateKeyPair) \
 [getPublicKeyFromPrivateKey](/api/functions/getPublicKeyFromPrivateKey) \
 [isSignature](/api/functions/isSignature) \
+[isSignatureBytes](/api/functions/isSignatureBytes) \
 [signature](/api/functions/signature) \
+[signatureBytes](/api/functions/signatureBytes) \
 [signBytes](/api/functions/signBytes) \
 [verifySignature](/api/functions/verifySignature)
 

packages/keys/src/__tests__/coercions-test.ts

@@ -4,7 +4,7 @@ import {
     SolanaError,
 } from '@solana/errors';
 
-import { Signature, signature } from '../signatures';
+import { Signature, signature, signatureBytes } from '../signatures';
 
 describe('signature', () => {
     it('can coerce to `Signature`', () => {
@@ -36,3 +36,19 @@ describe('signature', () => {
         );
     });
 });
+
+describe('signatureBytes', () => {
+    it('can coerce to `SignatureBytes`', () => {
+        const raw = new Uint8Array(64);
+        const coerced = signatureBytes(raw);
+        expect(coerced).toBe(raw);
+    });
+    it.each([63, 65])('throws on a `SignatureBytes` whose byte length is %s', actualLength => {
+        const thisThrows = () => signatureBytes(new Uint8Array(actualLength));
+        expect(thisThrows).toThrow(
+            new SolanaError(SOLANA_ERROR__KEYS__INVALID_SIGNATURE_BYTE_LENGTH, {
+                actualLength,
+            }),
+        );
+    });
+});

packages/keys/src/__tests__/signatures-test.ts

@@ -2,7 +2,7 @@ import { createEncoder, VariableSizeEncoder } from '@solana/codecs-core';
 import { getBase58Encoder } from '@solana/codecs-strings';
 
 import { createPrivateKeyFromBytes } from '../private-key';
-import { SignatureBytes, signBytes, verifySignature } from '../signatures';
+import { assertIsSignatureBytes, SignatureBytes, signBytes, verifySignature } from '../signatures';
 
 jest.mock('@solana/codecs-strings', () => ({
     ...jest.requireActual('@solana/codecs-strings'),
@@ -14,7 +14,7 @@ const MOCK_DATA_SIGNATURE = new Uint8Array([
     66, 111, 184, 228, 239, 189, 127, 46, 23, 168, 117, 69, 58, 143, 132, 164, 112, 189, 203, 228, 183, 151, 0, 23, 179,
     181, 52, 75, 112, 225, 150, 128, 184, 164, 36, 21, 101, 205, 115, 28, 127, 221, 24, 135, 229, 8, 69, 232, 16, 225,
     44, 229, 17, 236, 206, 174, 102, 207, 79, 253, 96, 7, 174, 10,
-]) as SignatureBytes;
+]);
 const MOCK_PRIVATE_KEY_BYTES = new Uint8Array([
     0xeb, 0xfa, 0x65, 0xeb, 0x93, 0xdc, 0x79, 0x15, 0x7a, 0xba, 0xde, 0xa2, 0xf7, 0x94, 0x37, 0x9d, 0xfc, 0x07, 0x1d,
     0x68, 0x86, 0x87, 0x37, 0x6d, 0xc5, 0xd5, 0xa0, 0x54, 0x12, 0x1d, 0x34, 0x4a,
@@ -143,6 +143,33 @@ describe('assertIsSignature()', () => {
     });
 });
 
+describe('assertIsSignatureBytes()', () => {
+    it('throws when supplied an empty byte array', () => {
+        expect(() => {
+            assertIsSignatureBytes(new Uint8Array(0));
+        }).toThrow();
+    });
+    it.each([63, 65])('throws when the byte array has a length of %s', length => {
+        expect(() => {
+            assertIsSignatureBytes(new Uint8Array(length));
+        }).toThrow();
+    });
+    it('does not throw when supplied a zeroed 64-byte bytearray', () => {
+        expect(() => {
+            assertIsSignatureBytes(new Uint8Array(64));
+        }).not.toThrow();
+    });
+    it('does not throw when supplied a 64-byte signature as a bytearray', () => {
+        expect(() => {
+            assertIsSignatureBytes(MOCK_DATA_SIGNATURE);
+        }).not.toThrow();
+    });
+    it('returns undefined when supplied a 64-byte byte array', () => {
+        // 64 bytes [0, ..., 0]
+        expect(assertIsSignatureBytes(new Uint8Array(64))).toBeUndefined();
+    });
+});
+
 describe('sign', () => {
     it('produces the expected signature given a private key', async () => {
         expect.assertions(1);
@@ -171,7 +198,7 @@ describe('verify', () => {
     });
     it('returns `true` when the correct signature is supplied for a given payload', async () => {
         expect.assertions(1);
-        const result = await verifySignature(mockPublicKey, MOCK_DATA_SIGNATURE, MOCK_DATA);
+        const result = await verifySignature(mockPublicKey, MOCK_DATA_SIGNATURE as SignatureBytes, MOCK_DATA);
         expect(result).toBe(true);
     });
     it('returns `false` when a bad signature is supplied for a given payload', async () => {

packages/keys/src/__typetests__/signatures-typetest.ts

@@ -1,6 +1,6 @@
 import { EncodedString } from '@solana/nominal-types';
 
-import { Signature, signature } from '../signatures';
+import { Signature, signature, SignatureBytes, signatureBytes } from '../signatures';
 
 // [DESCRIBE] signature()
 {
@@ -18,3 +18,20 @@ import { Signature, signature } from '../signatures';
         signature satisfies EncodedString<string, 'base58'>;
     }
 }
+
+// [DESCRIBE] signatureBytes()
+{
+    // It returns a `SignatureBytes`
+    {
+        signatureBytes(new Uint8Array(0)) satisfies SignatureBytes;
+    }
+}
+
+// [DESCRIBE] SignatureBytes
+{
+    // It satisfies the `Uint8Array` type
+    {
+        const signatureBytes = null as unknown as SignatureBytes;
+        signatureBytes satisfies Uint8Array;
+    }
+}

packages/keys/src/signatures.ts

@@ -68,7 +68,41 @@ export function assertIsSignature(putativeSignature: string): asserts putativeSi
     }
     // Slow-path; actually attempt to decode the input string.
     const bytes = base58Encoder.encode(putativeSignature);
-    const numBytes = bytes.byteLength;
+    assertIsSignatureBytes(bytes);
+}
+
+/**
+ * Asserts that an arbitrary `ReadonlyUint8Array` is an Ed25519 signature.
+ *
+ * Useful when you receive a `ReadonlyUint8Array` from an external interface (like the browser wallets' `signMessage` API) that you expect to
+ * represent an Ed25519 signature.
+ *
+ * @example
+ * ```ts
+ * import { assertIsSignatureBytes } from '@solana/keys';
+ *
+ * // Imagine a function that verifies a signature.
+ * function verifySignature() {
+ *     // We know only that the input conforms to the `ReadonlyUint8Array` type.
+ *     const signatureBytes: ReadonlyUint8Array = signatureBytesInput;
+ *     try {
+ *         // If this type assertion function doesn't throw, then
+ *         // Typescript will upcast `signatureBytes` to `SignatureBytes`.
+ *         assertIsSignatureBytes(signatureBytes);
+ *         // At this point, `signatureBytes` is a `SignatureBytes` that can be used with `verifySignature`.
+ *         if (!(await verifySignature(publicKey, signatureBytes, data))) {
+ *             throw new Error('The data were *not* signed by the private key associated with `publicKey`');
+ *         }
+ *     } catch (e) {
+ *         // `signatureBytes` turned out not to be a 64-byte Ed25519 signature
+ *     }
+ * }
+ * ```
+ */
+export function assertIsSignatureBytes(
+    putativeSignatureBytes: ReadonlyUint8Array,
+): asserts putativeSignatureBytes is SignatureBytes {
+    const numBytes = putativeSignatureBytes.byteLength;
     if (numBytes !== 64) {
         throw new SolanaError(SOLANA_ERROR__KEYS__INVALID_SIGNATURE_BYTE_LENGTH, {
             actualLength: numBytes,
@@ -110,11 +144,30 @@ export function isSignature(putativeSignature: string): putativeSignature is Sig
     }
     // Slow-path; actually attempt to decode the input string.
     const bytes = base58Encoder.encode(putativeSignature);
-    const numBytes = bytes.byteLength;
-    if (numBytes !== 64) {
-        return false;
-    }
-    return true;
+    return isSignatureBytes(bytes);
+}
+
+/**
+ * A type guard that accepts a `ReadonlyUint8Array` as input. It will both return `true` if the `ReadonlyUint8Array` conforms to
+ * the {@link SignatureBytes} type and will refine the type for use in your program.
+ *
+ * @example
+ * ```ts
+ * import { isSignatureBytes } from '@solana/keys';
+ *
+ * if (isSignatureBytes(signatureBytes)) {
+ *     // At this point, `signatureBytes` has been refined to a
+ *     // `SignatureBytes` that can be used with `verifySignature`.
+ *     if (!(await verifySignature(publicKey, signatureBytes, data))) {
+ *         throw new Error('The data were *not* signed by the private key associated with `publicKey`');
+ *     }
+ * } else {
+ *     setError(`${signatureBytes} is not a 64-byte Ed25519 signature`);
+ * }
+ * ```
+ */
+export function isSignatureBytes(putativeSignatureBytes: ReadonlyUint8Array): putativeSignatureBytes is SignatureBytes {
+    return putativeSignatureBytes.byteLength === 64;
 }
 
 /**
@@ -155,6 +208,25 @@ export function signature(putativeSignature: string): Signature {
     return putativeSignature;
 }
 
+/**
+ * This helper combines _asserting_ that a `ReadonlyUint8Array` is an Ed25519 signature with _coercing_ it to the
+ * {@link SignatureBytes} type. It's best used with untrusted input.
+ *
+ * @example
+ * ```ts
+ * import { signatureBytes } from '@solana/keys';
+ *
+ * const signature = signatureBytes(userSuppliedSignatureBytes);
+ * if (!(await verifySignature(publicKey, signature, data))) {
+ *     throw new Error('The data were *not* signed by the private key associated with `publicKey`');
+ * }
+ * ```
+ */
+export function signatureBytes(putativeSignatureBytes: ReadonlyUint8Array): SignatureBytes {
+    assertIsSignatureBytes(putativeSignatureBytes);
+    return putativeSignatureBytes;
+}
+
 /**
  * Given a public [`CryptoKey`](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey), some
  * {@link SignatureBytes}, and a `Uint8Array` of data, this method will return `true` if the