ox 0.10.2 → 0.10.4

package/tempo/SignatureEnvelope.ts

@@ -1,4 +1,5 @@
-import type * as Address from '../core/Address.js'
+import * as Address from '../core/Address.js'
+import type * as Bytes from '../core/Bytes.js'
 import * as Errors from '../core/Errors.js'
 import * as Hex from '../core/Hex.js'
 import type {
@@ -10,15 +11,22 @@ import type {
   UnionPartialBy,
 } from '../core/internal/types.js'
 import * as Json from '../core/Json.js'
+import * as ox_P256 from '../core/P256.js'
 import type * as PublicKey from '../core/PublicKey.js'
+import * as ox_Secp256k1 from '../core/Secp256k1.js'
 import * as Signature from '../core/Signature.js'
 import type * as WebAuthnP256 from '../core/WebAuthnP256.js'
+import * as ox_WebAuthnP256 from '../core/WebAuthnP256.js'
 
 /** Signature type identifiers for encoding/decoding */
 const serializedP256Type = '0x01'
 const serializedWebAuthnType = '0x02'
 const serializedKeychainType = '0x03'
 
+/** Serialized magic identifier for Tempo signature envelopes. */
+export const magicBytes =
+  '0x7777777777777777777777777777777777777777777777777777777777777777' // 32 "T"s
+
 /**
  * Statically determines the signature type of an envelope at compile time.
  *
@@ -283,7 +291,11 @@ export declare namespace assert {
  * @returns The deserialized signature envelope.
  * @throws `CoercionError` if the serialized value cannot be coerced to a valid signature envelope.
  */
-export function deserialize(serialized: Serialized): SignatureEnvelope {
+export function deserialize(value: Serialized): SignatureEnvelope {
+  const serialized = value.endsWith(magicBytes.slice(2))
+    ? Hex.slice(value, 0, -Hex.size(magicBytes))
+    : value
+
   const size = Hex.size(serialized)
 
   // Backward compatibility: 65 bytes means secp256k1 without type identifier
@@ -763,13 +775,17 @@ export function getType<
  */
 export function serialize(
   envelope: UnionPartialBy<SignatureEnvelope, 'prehash'>,
+  options: serialize.Options = {},
 ): Serialized {
   const type = getType(envelope)
 
   // Backward compatibility: no type identifier for secp256k1
   if (type === 'secp256k1') {
     const secp256k1 = envelope as Secp256k1
-    return Signature.toHex(secp256k1.signature)
+    return Hex.concat(
+      Signature.toHex(secp256k1.signature),
+      options.magic ? magicBytes : '0x',
+    )
   }
 
   if (type === 'p256') {
@@ -782,6 +798,7 @@ export function serialize(
       Hex.fromNumber(p256.publicKey.x, { size: 32 }),
       Hex.fromNumber(p256.publicKey.y, { size: 32 }),
       Hex.fromNumber(p256.prehash ? 1 : 0, { size: 1 }),
+      options.magic ? magicBytes : '0x',
     )
   }
 
@@ -800,6 +817,7 @@ export function serialize(
       Hex.fromNumber(webauthn.signature.s, { size: 32 }),
       Hex.fromNumber(webauthn.publicKey.x, { size: 32 }),
       Hex.fromNumber(webauthn.publicKey.y, { size: 32 }),
+      options.magic ? magicBytes : '0x',
     )
   }
 
@@ -809,12 +827,23 @@ export function serialize(
       serializedKeychainType,
       keychain.userAddress,
       serialize(keychain.inner),
+      options.magic ? magicBytes : '0x',
     )
   }
 
   throw new CoercionError({ envelope })
 }
 
+export declare namespace serialize {
+  type Options = {
+    /**
+     * Whether to serialize the signature envelope with the Tempo magic identifier.
+     * This is useful for being able to distinguish between Tempo and non-Tempo (e.g. ERC-1271) signatures.
+     */
+    magic?: boolean | undefined
+  }
+}
+
 /**
  * Converts a signature envelope to RPC format.
  *
@@ -922,6 +951,179 @@ export declare namespace validate {
   type ErrorType = Errors.GlobalErrorType
 }
 
+/**
+ * Verifies a signature envelope against a digest/payload.
+ *
+ * Supports `secp256k1`, `p256`, and `webAuthn` signature types.
+ *
+ * :::warning
+ * `keychain` signatures are not supported and will return `false`.
+ * :::
+ *
+ * @example
+ * ### Secp256k1
+ *
+ * ```ts twoslash
+ * import { SignatureEnvelope } from 'ox/tempo'
+ * import { Secp256k1 } from 'ox'
+ *
+ * const privateKey = Secp256k1.randomPrivateKey()
+ * const publicKey = Secp256k1.getPublicKey({ privateKey })
+ * const payload = '0xdeadbeef'
+ *
+ * const signature = Secp256k1.sign({ payload, privateKey })
+ * const envelope = SignatureEnvelope.from(signature)
+ *
+ * const valid = SignatureEnvelope.verify(envelope, {
+ *   payload,
+ *   publicKey,
+ * })
+ * // @log: true
+ * ```
+ *
+ * @example
+ * ### P256
+ *
+ * For P256 signatures, the `address` or `publicKey` must match the embedded
+ * public key in the signature envelope.
+ *
+ * ```ts twoslash
+ * import { SignatureEnvelope } from 'ox/tempo'
+ * import { P256 } from 'ox'
+ *
+ * const privateKey = P256.randomPrivateKey()
+ * const publicKey = P256.getPublicKey({ privateKey })
+ * const payload = '0xdeadbeef'
+ *
+ * const signature = P256.sign({ payload, privateKey })
+ * const envelope = SignatureEnvelope.from({ prehash: false, publicKey, signature })
+ *
+ * const valid = SignatureEnvelope.verify(envelope, {
+ *   payload,
+ *   publicKey,
+ * })
+ * // @log: true
+ * ```
+ *
+ * @example
+ * ### WebCryptoP256
+ *
+ * ```ts twoslash
+ * import { SignatureEnvelope } from 'ox/tempo'
+ * import { WebCryptoP256 } from 'ox'
+ *
+ * const { privateKey, publicKey } = await WebCryptoP256.createKeyPair()
+ * const payload = '0xdeadbeef'
+ *
+ * const signature = await WebCryptoP256.sign({ payload, privateKey })
+ * const envelope = SignatureEnvelope.from({ prehash: true, publicKey, signature })
+ *
+ * const valid = SignatureEnvelope.verify(envelope, {
+ *   payload,
+ *   publicKey,
+ * })
+ * // @log: true
+ * ```
+ *
+ * @example
+ * ### WebAuthnP256
+ *
+ * ```ts twoslash
+ * import { SignatureEnvelope } from 'ox/tempo'
+ * import { WebAuthnP256 } from 'ox'
+ *
+ * const credential = await WebAuthnP256.createCredential({ name: 'Example' })
+ * const payload = '0xdeadbeef'
+ *
+ * const { metadata, signature } = await WebAuthnP256.sign({
+ *   challenge: payload,
+ *   credentialId: credential.id,
+ * })
+ * const envelope = SignatureEnvelope.from({
+ *   metadata,
+ *   signature,
+ *   publicKey: credential.publicKey,
+ * })
+ *
+ * const valid = SignatureEnvelope.verify(envelope, {
+ *   payload,
+ *   publicKey: credential.publicKey,
+ * })
+ * // @log: true
+ * ```
+ *
+ * @param parameters - Verification parameters.
+ * @returns `true` if the signature is valid, `false` otherwise.
+ */
+export function verify(
+  signature: SignatureEnvelope,
+  parameters: verify.Parameters,
+): boolean {
+  const { payload } = parameters
+
+  const address = (() => {
+    if (parameters.address) return parameters.address
+    if (parameters.publicKey) return Address.fromPublicKey(parameters.publicKey)
+    return undefined
+  })()
+  if (!address) return false
+
+  try {
+    const envelope = from(signature)
+
+    if (envelope.type === 'secp256k1') {
+      if (!address) return false
+      return ox_Secp256k1.verify({
+        address,
+        payload,
+        signature: envelope.signature,
+      })
+    }
+
+    if (envelope.type === 'p256') {
+      const envelopeAddress = Address.fromPublicKey(envelope.publicKey)
+      if (!Address.isEqual(envelopeAddress, address)) return false
+      return ox_P256.verify({
+        hash: envelope.prehash,
+        publicKey: envelope.publicKey,
+        payload,
+        signature: envelope.signature,
+      })
+    }
+
+    if (envelope.type === 'webAuthn') {
+      const envelopeAddress = Address.fromPublicKey(envelope.publicKey)
+      if (!Address.isEqual(envelopeAddress, address)) return false
+      return ox_WebAuthnP256.verify({
+        challenge: Hex.from(payload),
+        metadata: envelope.metadata,
+        publicKey: envelope.publicKey,
+        signature: envelope.signature,
+      })
+    }
+
+    return false
+  } catch {
+    return false
+  }
+}
+
+export declare namespace verify {
+  type Parameters = {
+    /** Payload that was signed. */
+    payload: Hex.Hex | Bytes.Bytes
+  } & OneOf<
+    | {
+        /** Public key that signed the payload. */
+        publicKey: PublicKey.PublicKey
+      }
+    | {
+        /** Address that signed the payload. */
+        address: Address.Address
+      }
+  >
+}
+
 /**
  * Error thrown when a signature envelope cannot be coerced to a valid type.
  */

package/version.ts

@@ -1,2 +1,2 @@
 /** @internal */
-export const version = '0.10.2'
+export const version = '0.10.4'