tempo.ts 0.0.5 → 0.1.0

package/src/ox/SignatureEnvelope.ts

@@ -0,0 +1,709 @@
+import * as Errors from 'ox/Errors'
+import * as Hex from 'ox/Hex'
+import * as Json from 'ox/Json'
+import type * as PublicKey from 'ox/PublicKey'
+import * as Signature from 'ox/Signature'
+import type * as WebAuthnP256 from 'ox/WebAuthnP256'
+import type {
+  Assign,
+  Compute,
+  IsNarrowable,
+  OneOf,
+  PartialBy,
+} from '../internal/types.js'
+
+/** Signature type identifiers for encoding/decoding */
+const serializedP256Type = '0x01'
+const serializedWebAuthnType = '0x02'
+
+/**
+ * Statically determines the signature type of an envelope at compile time.
+ *
+ * @example
+ * ```ts twoslash
+ * import type { SignatureEnvelope } from 'tempo.ts/ox'
+ *
+ * type Type = SignatureEnvelope.GetType<{ r: bigint; s: bigint; yParity: number }>
+ * // @log: 'secp256k1'
+ * ```
+ */
+export type GetType<
+  envelope extends PartialBy<SignatureEnvelope, 'type'> | unknown,
+> = unknown extends envelope
+  ? envelope extends unknown
+    ? Type
+    : never
+  : envelope extends { type: infer T extends Type }
+    ? T
+    : envelope extends {
+          signature: { r: bigint; s: bigint }
+          prehash: boolean
+          publicKey: PublicKey.PublicKey
+        }
+      ? 'p256'
+      : envelope extends {
+            signature: { r: bigint; s: bigint }
+            metadata: any
+            publicKey: PublicKey.PublicKey
+          }
+        ? 'webAuthn'
+        : envelope extends { r: bigint; s: bigint; yParity: number }
+          ? 'secp256k1'
+          : envelope extends {
+                signature: { r: bigint; s: bigint; yParity: number }
+              }
+            ? 'secp256k1'
+            : never
+
+/**
+ * Represents a signature envelope that can contain different signature types.
+ *
+ * Supports:
+ * - secp256k1: Standard ECDSA signature (65 bytes)
+ * - p256: P256 signature with embedded public key and prehash flag (130 bytes)
+ * - webAuthn: WebAuthn signature with variable-length authenticator data
+ */
+export type SignatureEnvelope<bigintType = bigint, numberType = number> = OneOf<
+  | Secp256k1<bigintType, numberType>
+  | P256<bigintType, numberType>
+  | WebAuthn<bigintType, numberType>
+>
+
+/**
+ * RPC-formatted signature envelope.
+ */
+export type SignatureEnvelopeRpc = OneOf<Secp256k1Rpc | P256Rpc | WebAuthnRpc>
+
+export type P256<bigintType = bigint, numberType = number> = {
+  prehash: boolean
+  publicKey: PublicKey.PublicKey
+  signature: Signature.Signature<false, bigintType, numberType>
+  type: 'p256'
+}
+
+export type P256Rpc = {
+  prehash: boolean
+  pubKeyX: Hex.Hex
+  pubKeyY: Hex.Hex
+  r: Hex.Hex
+  s: Hex.Hex
+  type: 'p256'
+}
+
+export type Secp256k1<bigintType = bigint, numberType = number> = {
+  signature: Signature.Signature<true, bigintType, numberType>
+  type: 'secp256k1'
+}
+
+export type Secp256k1Rpc = Compute<
+  Signature.Rpc<true> & {
+    v?: Hex.Hex | undefined
+    type: 'secp256k1'
+  }
+>
+
+export type Secp256k1Flat<
+  bigintType = bigint,
+  numberType = number,
+> = Signature.Signature<true, bigintType, numberType> & {
+  type?: 'secp256k1' | undefined
+}
+
+export type WebAuthn<bigintType = bigint, numberType = number> = {
+  metadata: Pick<
+    WebAuthnP256.SignMetadata,
+    'authenticatorData' | 'clientDataJSON'
+  >
+  signature: Signature.Signature<false, bigintType, numberType>
+  publicKey: PublicKey.PublicKey
+  type: 'webAuthn'
+}
+
+export type WebAuthnRpc = {
+  pubKeyX: Hex.Hex
+  pubKeyY: Hex.Hex
+  r: Hex.Hex
+  s: Hex.Hex
+  type: 'webAuthn'
+  webauthnData: Hex.Hex
+}
+
+/** Hex-encoded serialized signature envelope. */
+export type Serialized = Hex.Hex
+
+/** List of supported signature types. */
+export const types = ['secp256k1', 'p256', 'webAuthn'] as const
+
+/** Union type of supported signature types. */
+export type Type = (typeof types)[number]
+
+/**
+ * Asserts that a {@link SignatureEnvelope} is valid.
+ *
+ * @example
+ * ```ts twoslash
+ * import { SignatureEnvelope } from 'tempo.ts/ox'
+ *
+ * SignatureEnvelope.assert({
+ *   r: 0n,
+ *   s: 0n,
+ *   yParity: 0,
+ *   type: 'secp256k1',
+ * })
+ * ```
+ *
+ * @param envelope - The signature envelope to assert.
+ * @throws {CoercionError} If the envelope type cannot be determined.
+ */
+export function assert(envelope: PartialBy<SignatureEnvelope, 'type'>): void {
+  const type = getType(envelope)
+
+  if (type === 'secp256k1') {
+    Signature.assert(envelope.signature)
+    return
+  }
+
+  if (type === 'p256') {
+    const p256 = envelope as P256
+    const missing: string[] = []
+
+    if (typeof p256.signature?.r !== 'bigint') missing.push('signature.r')
+    if (typeof p256.signature?.s !== 'bigint') missing.push('signature.s')
+    if (typeof p256.prehash !== 'boolean') missing.push('prehash')
+    if (!p256.publicKey) missing.push('publicKey')
+    else {
+      if (typeof p256.publicKey.x !== 'bigint') missing.push('publicKey.x')
+      if (typeof p256.publicKey.y !== 'bigint') missing.push('publicKey.y')
+    }
+
+    if (missing.length > 0)
+      throw new MissingPropertiesError({ envelope, missing, type: 'p256' })
+    return
+  }
+
+  if (type === 'webAuthn') {
+    const webauthn = envelope as WebAuthn
+    const missing: string[] = []
+
+    if (typeof webauthn.signature?.r !== 'bigint') missing.push('signature.r')
+    if (typeof webauthn.signature?.s !== 'bigint') missing.push('signature.s')
+    if (!webauthn.metadata) missing.push('metadata')
+    else {
+      if (!webauthn.metadata.authenticatorData)
+        missing.push('metadata.authenticatorData')
+      if (!webauthn.metadata.clientDataJSON)
+        missing.push('metadata.clientDataJSON')
+    }
+    if (!webauthn.publicKey) missing.push('publicKey')
+    else {
+      if (typeof webauthn.publicKey.x !== 'bigint') missing.push('publicKey.x')
+      if (typeof webauthn.publicKey.y !== 'bigint') missing.push('publicKey.y')
+    }
+
+    if (missing.length > 0)
+      throw new MissingPropertiesError({ envelope, missing, type: 'webAuthn' })
+    return
+  }
+}
+
+export declare namespace assert {
+  type ErrorType =
+    | CoercionError
+    | MissingPropertiesError
+    | Signature.assert.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Deserializes a hex-encoded signature envelope into a typed signature object.
+ *
+ * For backward compatibility:
+ * - 65 bytes: secp256k1 signature (no type identifier)
+ * - 130 bytes: P256 signature (1 byte type + 129 bytes data)
+ * - 129+ bytes: WebAuthn signature (1 byte type + variable data)
+ *
+ * @param serialized - The hex-encoded signature envelope to deserialize.
+ * @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 {
+  const size = Hex.size(serialized)
+
+  // Backward compatibility: 65 bytes means secp256k1 without type identifier
+  if (size === 65) {
+    const signature = Signature.fromHex(serialized)
+    Signature.assert(signature)
+    return { signature, type: 'secp256k1' }
+  }
+
+  // For all other lengths, first byte is the type identifier
+  const typeId = Hex.slice(serialized, 0, 1)
+  const data = Hex.slice(serialized, 1)
+  const dataSize = Hex.size(data)
+
+  if (typeId === serializedP256Type) {
+    // P256: 32 (r) + 32 (s) + 32 (pubKeyX) + 32 (pubKeyY) + 1 (prehash) = 129 bytes
+    if (dataSize !== 129)
+      throw new InvalidSerializedError({
+        reason: `Invalid P256 signature envelope size: expected 129 bytes, got ${dataSize} bytes`,
+        serialized,
+      })
+
+    return {
+      publicKey: {
+        prefix: 4,
+        x: Hex.toBigInt(Hex.slice(data, 64, 96)),
+        y: Hex.toBigInt(Hex.slice(data, 96, 128)),
+      },
+      prehash: Hex.toNumber(Hex.slice(data, 128, 129)) !== 0,
+      signature: {
+        r: Hex.toBigInt(Hex.slice(data, 0, 32)),
+        s: Hex.toBigInt(Hex.slice(data, 32, 64)),
+      },
+      type: 'p256',
+    } as P256
+  }
+
+  if (typeId === serializedWebAuthnType) {
+    // WebAuthn: variable (webauthnData) + 32 (r) + 32 (s) + 32 (pubKeyX) + 32 (pubKeyY)
+    // Minimum: 128 bytes (at least some authenticator data + signature components)
+    if (dataSize < 128)
+      throw new InvalidSerializedError({
+        reason: `Invalid WebAuthn signature envelope size: expected at least 128 bytes, got ${dataSize} bytes`,
+        serialized,
+      })
+
+    const webauthnDataSize = dataSize - 128
+    const webauthnData = Hex.slice(data, 0, webauthnDataSize)
+
+    // Parse webauthnData into authenticatorData and clientDataJSON
+    // According to the Rust code, it's authenticatorData || clientDataJSON
+    // We need to find the split point (minimum authenticatorData is 37 bytes)
+    let authenticatorData: Hex.Hex | undefined
+    let clientDataJSON: string | undefined
+
+    // Try to find the JSON start (clientDataJSON should start with '{')
+    for (let split = 37; split < webauthnDataSize; split++) {
+      const potentialJson = Hex.toString(Hex.slice(webauthnData, split))
+      if (potentialJson.startsWith('{') && potentialJson.endsWith('}')) {
+        try {
+          JSON.parse(potentialJson)
+          authenticatorData = Hex.slice(webauthnData, 0, split)
+          clientDataJSON = potentialJson
+          break
+        } catch {}
+      }
+    }
+
+    if (!authenticatorData || !clientDataJSON)
+      throw new InvalidSerializedError({
+        reason:
+          'Unable to parse WebAuthn metadata: could not extract valid authenticatorData and clientDataJSON',
+        serialized,
+      })
+
+    return {
+      publicKey: {
+        prefix: 4,
+        x: Hex.toBigInt(
+          Hex.slice(data, webauthnDataSize + 64, webauthnDataSize + 96),
+        ),
+        y: Hex.toBigInt(
+          Hex.slice(data, webauthnDataSize + 96, webauthnDataSize + 128),
+        ),
+      },
+      metadata: {
+        authenticatorData,
+        clientDataJSON,
+      },
+      signature: {
+        r: Hex.toBigInt(
+          Hex.slice(data, webauthnDataSize, webauthnDataSize + 32),
+        ),
+        s: Hex.toBigInt(
+          Hex.slice(data, webauthnDataSize + 32, webauthnDataSize + 64),
+        ),
+      },
+      type: 'webAuthn',
+    } as WebAuthn
+  }
+
+  throw new InvalidSerializedError({
+    reason: `Unknown signature type identifier: ${typeId}. Expected ${serializedP256Type} (P256) or ${serializedWebAuthnType} (WebAuthn)`,
+    serialized,
+  })
+}
+
+/**
+ * Coerces a value to a signature envelope.
+ *
+ * Accepts either a serialized hex string or an existing signature envelope object.
+ *
+ * @param value - The value to coerce (either a hex string or signature envelope).
+ * @returns The signature envelope.
+ */
+export function from<const value extends from.Value>(
+  value: value | from.Value,
+): from.ReturnValue<value> {
+  if (typeof value === 'string') return deserialize(value) as never
+
+  if (
+    typeof value === 'object' &&
+    value !== null &&
+    'r' in value &&
+    's' in value &&
+    'yParity' in value
+  )
+    return { signature: value, type: 'secp256k1' } as never
+
+  const type = getType(value)
+  return { ...value, type } as never
+}
+
+export declare namespace from {
+  type Value = PartialBy<SignatureEnvelope, 'type'> | Secp256k1Flat | Serialized
+
+  type ReturnValue<value extends Value> = Compute<
+    OneOf<
+      value extends Serialized
+        ? SignatureEnvelope
+        : value extends Secp256k1Flat
+          ? Secp256k1
+          : IsNarrowable<value, SignatureEnvelope> extends true
+            ? SignatureEnvelope
+            : Assign<value, { readonly type: GetType<value> }>
+    >
+  >
+}
+
+/**
+ * Converts an {@link SignatureEnvelopeRpc} to a {@link SignatureEnvelope}.
+ *
+ * @param envelope - The RPC signature envelope to convert.
+ * @returns The signature envelope with bigint values.
+ */
+export function fromRpc(envelope: SignatureEnvelopeRpc): SignatureEnvelope {
+  if (envelope.type === 'secp256k1')
+    return {
+      signature: Signature.fromRpc(envelope),
+      type: 'secp256k1',
+    }
+
+  if (envelope.type === 'p256') {
+    return {
+      prehash: envelope.prehash,
+      publicKey: {
+        prefix: 4,
+        x: Hex.toBigInt(envelope.pubKeyX),
+        y: Hex.toBigInt(envelope.pubKeyY),
+      },
+      signature: {
+        r: Hex.toBigInt(envelope.r),
+        s: Hex.toBigInt(envelope.s),
+      },
+      type: 'p256',
+    }
+  }
+
+  if (envelope.type === 'webAuthn') {
+    const webauthnData = envelope.webauthnData
+    const webauthnDataSize = Hex.size(webauthnData)
+
+    // Parse webauthnData into authenticatorData and clientDataJSON
+    let authenticatorData: Hex.Hex | undefined
+    let clientDataJSON: string | undefined
+
+    // Try to find the JSON start (clientDataJSON should start with '{')
+    for (let split = 37; split < webauthnDataSize; split++) {
+      const potentialJson = Hex.toString(Hex.slice(webauthnData, split))
+      if (potentialJson.startsWith('{') && potentialJson.endsWith('}')) {
+        try {
+          JSON.parse(potentialJson)
+          authenticatorData = Hex.slice(webauthnData, 0, split)
+          clientDataJSON = potentialJson
+          break
+        } catch {}
+      }
+    }
+
+    if (!authenticatorData || !clientDataJSON)
+      throw new InvalidSerializedError({
+        reason:
+          'Unable to parse WebAuthn metadata: could not extract valid authenticatorData and clientDataJSON',
+        serialized: webauthnData,
+      })
+
+    return {
+      metadata: {
+        authenticatorData,
+        clientDataJSON,
+      },
+      publicKey: {
+        prefix: 4,
+        x: Hex.toBigInt(envelope.pubKeyX),
+        y: Hex.toBigInt(envelope.pubKeyY),
+      },
+      signature: {
+        r: Hex.toBigInt(envelope.r),
+        s: Hex.toBigInt(envelope.s),
+      },
+      type: 'webAuthn',
+    }
+  }
+
+  throw new CoercionError({ envelope })
+}
+
+export declare namespace fromRpc {
+  type ErrorType =
+    | CoercionError
+    | InvalidSerializedError
+    | Signature.fromRpc.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Determines the signature type of an envelope.
+ *
+ * @param envelope - The signature envelope to inspect.
+ * @returns The signature type ('secp256k1', 'p256', or 'webAuthn').
+ * @throws {CoercionError} If the envelope type cannot be determined.
+ */
+export function getType<
+  envelope extends
+    | PartialBy<SignatureEnvelope, 'type'>
+    | Secp256k1Flat
+    | unknown,
+>(envelope: envelope): GetType<envelope> {
+  if (typeof envelope !== 'object' || envelope === null)
+    throw new CoercionError({ envelope })
+
+  if ('type' in envelope && envelope.type) return envelope.type as never
+
+  // Detect secp256k1 signature (backwards compatibility: also support flat structure)
+  if (
+    'signature' in envelope &&
+    !('publicKey' in envelope) &&
+    typeof envelope.signature === 'object' &&
+    envelope.signature !== null &&
+    'r' in envelope.signature &&
+    's' in envelope.signature &&
+    'yParity' in envelope.signature
+  )
+    return 'secp256k1' as never
+
+  // Detect secp256k1 signature (flat structure)
+  if ('r' in envelope && 's' in envelope && 'yParity' in envelope)
+    return 'secp256k1' as never
+
+  // Detect P256 signature
+  if (
+    'signature' in envelope &&
+    'prehash' in envelope &&
+    'publicKey' in envelope &&
+    typeof envelope.prehash === 'boolean'
+  )
+    return 'p256' as never
+
+  // Detect WebAuthn signature
+  if (
+    'signature' in envelope &&
+    'metadata' in envelope &&
+    'publicKey' in envelope
+  )
+    return 'webAuthn' as never
+
+  throw new CoercionError({
+    envelope,
+  })
+}
+
+/**
+ * Serializes a signature envelope to a hex-encoded string.
+ *
+ * For backward compatibility:
+ * - secp256k1: encoded WITHOUT type identifier (65 bytes)
+ * - P256: encoded WITH type identifier prefix (130 bytes)
+ * - WebAuthn: encoded WITH type identifier prefix (variable length)
+ *
+ * @param envelope - The signature envelope to serialize.
+ * @returns The hex-encoded serialized signature.
+ * @throws {CoercionError} If the envelope cannot be serialized.
+ */
+export function serialize(envelope: SignatureEnvelope): Serialized {
+  const type = getType(envelope)
+
+  // Backward compatibility: no type identifier for secp256k1
+  if (type === 'secp256k1') return Signature.toHex(envelope.signature)
+
+  if (type === 'p256') {
+    const p256 = envelope as P256
+    // Format: 1 byte (type) + 32 (r) + 32 (s) + 32 (pubKeyX) + 32 (pubKeyY) + 1 (prehash)
+    return Hex.concat(
+      serializedP256Type,
+      Hex.fromNumber(p256.signature.r, { size: 32 }),
+      Hex.fromNumber(p256.signature.s, { size: 32 }),
+      Hex.fromNumber(p256.publicKey.x, { size: 32 }),
+      Hex.fromNumber(p256.publicKey.y, { size: 32 }),
+      Hex.fromNumber(p256.prehash ? 1 : 0, { size: 1 }),
+    )
+  }
+
+  if (type === 'webAuthn') {
+    const webauthn = envelope as WebAuthn
+    // Format: 1 byte (type) + variable (authenticatorData || clientDataJSON) + 32 (r) + 32 (s) + 32 (pubKeyX) + 32 (pubKeyY)
+    const webauthnData = Hex.concat(
+      webauthn.metadata.authenticatorData,
+      Hex.fromString(webauthn.metadata.clientDataJSON),
+    )
+
+    return Hex.concat(
+      serializedWebAuthnType,
+      webauthnData,
+      Hex.fromNumber(webauthn.signature.r, { size: 32 }),
+      Hex.fromNumber(webauthn.signature.s, { size: 32 }),
+      Hex.fromNumber(webauthn.publicKey.x, { size: 32 }),
+      Hex.fromNumber(webauthn.publicKey.y, { size: 32 }),
+    )
+  }
+
+  throw new CoercionError({ envelope })
+}
+
+/**
+ * Converts a {@link SignatureEnvelope} to an {@link SignatureEnvelopeRpc}.
+ *
+ * @param envelope - The signature envelope to convert.
+ * @returns The RPC signature envelope with hex values.
+ */
+export function toRpc(envelope: SignatureEnvelope): SignatureEnvelopeRpc {
+  const type = getType(envelope)
+
+  if (type === 'secp256k1') {
+    const secp256k1 = envelope as Secp256k1
+    return {
+      ...Signature.toRpc(secp256k1.signature),
+      type: 'secp256k1',
+    }
+  }
+
+  if (type === 'p256') {
+    const p256 = envelope as P256
+    return {
+      prehash: p256.prehash,
+      pubKeyX: Hex.fromNumber(p256.publicKey.x, { size: 32 }),
+      pubKeyY: Hex.fromNumber(p256.publicKey.y, { size: 32 }),
+      r: Hex.fromNumber(p256.signature.r, { size: 32 }),
+      s: Hex.fromNumber(p256.signature.s, { size: 32 }),
+      type: 'p256',
+    }
+  }
+
+  if (type === 'webAuthn') {
+    const webauthn = envelope as WebAuthn
+    const webauthnData = Hex.concat(
+      webauthn.metadata.authenticatorData,
+      Hex.fromString(webauthn.metadata.clientDataJSON),
+    )
+
+    return {
+      pubKeyX: Hex.fromNumber(webauthn.publicKey.x, { size: 32 }),
+      pubKeyY: Hex.fromNumber(webauthn.publicKey.y, { size: 32 }),
+      r: Hex.fromNumber(webauthn.signature.r, { size: 32 }),
+      s: Hex.fromNumber(webauthn.signature.s, { size: 32 }),
+      type: 'webAuthn',
+      webauthnData,
+    }
+  }
+
+  throw new CoercionError({ envelope })
+}
+
+export declare namespace toRpc {
+  type ErrorType =
+    | CoercionError
+    | Signature.toRpc.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Validates a {@link SignatureEnvelope}. Returns `true` if the envelope is valid, `false` otherwise.
+ *
+ * @example
+ * ```ts twoslash
+ * import { SignatureEnvelope } from 'tempo.ts/ox'
+ *
+ * const valid = SignatureEnvelope.validate({
+ *   signature: { r: 0n, s: 0n, yParity: 0 },
+ *   type: 'secp256k1',
+ * })
+ * // @log: true
+ * ```
+ *
+ * @param envelope - The signature envelope to validate.
+ * @returns `true` if valid, `false` otherwise.
+ */
+export function validate(
+  envelope: PartialBy<SignatureEnvelope, 'type'>,
+): boolean {
+  try {
+    assert(envelope)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export declare namespace validate {
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/**
+ * Error thrown when a signature envelope cannot be coerced to a valid type.
+ */
+export class CoercionError extends Errors.BaseError {
+  override readonly name = 'SignatureEnvelope.CoercionError'
+  constructor({ envelope }: { envelope: unknown }) {
+    super(
+      `Unable to coerce value (\`${Json.stringify(envelope)}\`) to a valid signature envelope.`,
+    )
+  }
+}
+
+/**
+ * Error thrown when a signature envelope is missing required properties.
+ */
+export class MissingPropertiesError extends Errors.BaseError {
+  override readonly name = 'SignatureEnvelope.MissingPropertiesError'
+  constructor({
+    envelope,
+    missing,
+    type,
+  }: {
+    envelope: unknown
+    missing: string[]
+    type: Type
+  }) {
+    super(
+      `Signature envelope of type "${type}" is missing required properties: ${missing.map((m) => `\`${m}\``).join(', ')}.\n\nProvided: ${Json.stringify(envelope)}`,
+    )
+  }
+}
+
+/**
+ * Error thrown when a serialized signature envelope cannot be deserialized.
+ */
+export class InvalidSerializedError extends Errors.BaseError {
+  override readonly name = 'SignatureEnvelope.InvalidSerializedError'
+  constructor({
+    reason,
+    serialized,
+  }: {
+    reason: string
+    serialized: Hex.Hex
+  }) {
+    super(`Unable to deserialize signature envelope: ${reason}`, {
+      metaMessages: [`Serialized: ${serialized}`],
+    })
+  }
+}