ox 0.14.16 → 0.14.17

package/tempo/ZoneId.ts

@@ -0,0 +1,58 @@
+import type * as Errors from '../core/Errors.js'
+
+/**
+ * Base offset for deriving zone chain IDs.
+ *
+ * Zone chain IDs are computed as `chainIdBase + zoneId`.
+ */
+export const chainIdBase = 4_217_000_000 as const
+
+/**
+ * Derives a zone ID from a zone chain ID.
+ *
+ * Zone chain IDs follow the formula `4_217_000_000 + zoneId`, so a chain ID
+ * of `4217000006` corresponds to zone ID `6`.
+ *
+ * @example
+ * ```ts twoslash
+ * import { ZoneId } from 'ox/tempo'
+ *
+ * const zoneId = ZoneId.fromChainId(4_217_000_006)
+ * // @log: 6
+ * ```
+ *
+ * @param chainId - The zone chain ID.
+ * @returns The zone ID.
+ */
+export function fromChainId(chainId: number): number {
+  return chainId - chainIdBase
+}
+
+export declare namespace fromChainId {
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/**
+ * Derives a zone chain ID from a zone ID.
+ *
+ * Zone chain IDs follow the formula `4_217_000_000 + zoneId`, so zone ID
+ * `6` corresponds to chain ID `4217000006`.
+ *
+ * @example
+ * ```ts twoslash
+ * import { ZoneId } from 'ox/tempo'
+ *
+ * const chainId = ZoneId.toChainId(6)
+ * // @log: 4217000006
+ * ```
+ *
+ * @param zoneId - The zone ID.
+ * @returns The zone chain ID.
+ */
+export function toChainId(zoneId: number): number {
+  return chainIdBase + zoneId
+}
+
+export declare namespace toChainId {
+  type ErrorType = Errors.GlobalErrorType
+}

package/tempo/ZoneRpcAuthentication/package.json

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "types": "../../_types/tempo/ZoneRpcAuthentication.d.ts",
+  "main": "../../_cjs/tempo/ZoneRpcAuthentication.js",
+  "module": "../../_esm/tempo/ZoneRpcAuthentication.js"
+}

package/tempo/ZoneRpcAuthentication.test.ts

@@ -0,0 +1,226 @@
+import { PublicKey, RpcTransport, Secp256k1, Signature, WebAuthnP256 } from 'ox'
+import { describe, expect, expectTypeOf, test } from 'vitest'
+import * as SignatureEnvelope from './SignatureEnvelope.js'
+import * as ZoneRpcAuthentication from './ZoneRpcAuthentication.js'
+
+const privateKey =
+  '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80' as const
+
+const publicKey = PublicKey.from({
+  prefix: 4,
+  x: 78495282704852028275327922540131762143565388050940484317945369745559774511861n,
+  y: 8109764566587999957624872393871720746996669263962991155166704261108473113504n,
+})
+
+const p256Signature = Signature.from({
+  r: 92602584010956101470289867944347135737570451066466093224269890121909314569518n,
+  s: 54171125190222965779385658110416711469231271457324878825831748147306957269813n,
+  yParity: 0,
+})
+
+const authentication = {
+  chainId: 4217000006,
+  expiresAt: 1711235160,
+  issuedAt: 1711234560,
+  zoneId: 6,
+} as const
+
+describe('from', () => {
+  test('default', () => {
+    const token = ZoneRpcAuthentication.from(authentication)
+
+    expectTypeOf(token).toExtend<
+      ZoneRpcAuthentication.ZoneRpcAuthentication<false>
+    >()
+
+    expect(token).toMatchInlineSnapshot(`
+      {
+        "chainId": 4217000006,
+        "expiresAt": 1711235160,
+        "issuedAt": 1711234560,
+        "version": 0,
+        "zoneId": 6,
+      }
+    `)
+  })
+
+  test('options: signature', () => {
+    const token = ZoneRpcAuthentication.from(authentication)
+    const signature = Secp256k1.sign({
+      payload: ZoneRpcAuthentication.getSignPayload(token),
+      privateKey,
+    })
+
+    const token_signed = ZoneRpcAuthentication.from(token, { signature })
+
+    expectTypeOf(token_signed).toExtend<
+      ZoneRpcAuthentication.ZoneRpcAuthentication<true>
+    >()
+    expect(token_signed).toMatchInlineSnapshot(`
+      {
+        "chainId": 4217000006,
+        "expiresAt": 1711235160,
+        "issuedAt": 1711234560,
+        "signature": {
+          "signature": {
+            "r": 97341227674200655943359900797834667459856344667825437562901364609374126504358n,
+            "s": 25574506064018953291781981030565094064718304178734850538810668278475710350395n,
+            "yParity": 0,
+          },
+          "type": "secp256k1",
+        },
+        "version": 0,
+        "zoneId": 6,
+      }
+    `)
+  })
+})
+
+describe('getFields', () => {
+  test('default', () => {
+    const token = ZoneRpcAuthentication.from(authentication)
+
+    const fields = ZoneRpcAuthentication.getFields(token)
+    // 29 bytes = 58 hex chars + 0x prefix
+    expect(fields).toMatch(/^0x[0-9a-f]{58}$/i)
+
+    const payload = ZoneRpcAuthentication.getSignPayload(token)
+    // keccak256 = 32 bytes
+    expect(payload).toMatch(/^0x[0-9a-f]{64}$/)
+
+    const keychainPayload = ZoneRpcAuthentication.getSignPayload(token, {
+      userAddress: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',
+    })
+    expect(keychainPayload).toMatch(/^0x[0-9a-f]{64}$/)
+    expect(keychainPayload).not.toBe(payload)
+  })
+})
+
+describe('serialize', () => {
+  test('roundtrip', () => {
+    const token = ZoneRpcAuthentication.from(authentication)
+    const signature = Secp256k1.sign({
+      payload: ZoneRpcAuthentication.getSignPayload(token),
+      privateKey,
+    })
+
+    const serialized = ZoneRpcAuthentication.serialize(token, {
+      signature,
+    })
+
+    const deserialized = ZoneRpcAuthentication.deserialize(serialized)
+    expect(deserialized.chainId).toBe(authentication.chainId)
+    expect(deserialized.zoneId).toBe(authentication.zoneId)
+    expect(deserialized.issuedAt).toBe(authentication.issuedAt)
+    expect(deserialized.expiresAt).toBe(authentication.expiresAt)
+    expect(deserialized.version).toBe(0)
+    expect(deserialized.signature).toBeDefined()
+  })
+
+  test('parses variable-length keychain signatures from the end', () => {
+    const token = ZoneRpcAuthentication.from(authentication)
+    const inner = SignatureEnvelope.from(
+      Secp256k1.sign({
+        payload: ZoneRpcAuthentication.getSignPayload(token, {
+          userAddress: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',
+        }),
+        privateKey,
+      }),
+    )
+
+    const serialized = ZoneRpcAuthentication.serialize(token, {
+      signature: SignatureEnvelope.from({
+        inner,
+        type: 'keychain',
+        userAddress: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c',
+        version: 'v2',
+      }),
+    })
+
+    const deserialized = ZoneRpcAuthentication.deserialize(serialized)
+    expect(deserialized.chainId).toBe(authentication.chainId)
+    expect(deserialized.zoneId).toBe(authentication.zoneId)
+    expect(deserialized.signature.type).toBe('keychain')
+  })
+
+  test('parses variable-length webAuthn signatures from the end', () => {
+    const token = ZoneRpcAuthentication.from(authentication)
+    const signature = SignatureEnvelope.from({
+      signature: p256Signature,
+      publicKey,
+      metadata: {
+        authenticatorData: WebAuthnP256.getAuthenticatorData({
+          rpId: 'localhost',
+        }),
+        clientDataJSON: WebAuthnP256.getClientDataJSON({
+          challenge: ZoneRpcAuthentication.getSignPayload(token),
+          origin: 'http://localhost',
+        }),
+      },
+    })
+
+    const serialized = ZoneRpcAuthentication.serialize(token, {
+      signature,
+    })
+
+    const deserialized = ZoneRpcAuthentication.deserialize(serialized)
+    expect(deserialized.chainId).toBe(authentication.chainId)
+    expect(deserialized.zoneId).toBe(authentication.zoneId)
+    expect(deserialized.signature.type).toBe('webAuthn')
+  })
+})
+
+const credentials = import.meta.env.VITE_TEMPO_CREDENTIALS
+const rpcUrl = 'https://rpc-zone-006-private.tempoxyz.dev'
+
+describe('e2e', () => {
+  test.skipIf(!credentials)('succeeds with auth token', async () => {
+    const privateKey = Secp256k1.randomPrivateKey()
+    const now = Math.floor(Date.now() / 1000)
+
+    const auth = ZoneRpcAuthentication.from({
+      chainId: 4217000007,
+      expiresAt: now + 600,
+      issuedAt: now,
+      zoneId: 7,
+    })
+
+    const serialized = ZoneRpcAuthentication.serialize(auth, {
+      signature: SignatureEnvelope.from(
+        Secp256k1.sign({
+          payload: ZoneRpcAuthentication.getSignPayload(auth),
+          privateKey,
+        }),
+      ),
+    })
+
+    const transport = RpcTransport.fromHttp(rpcUrl, {
+      fetchOptions: {
+        headers: {
+          Authorization: `Basic ${btoa(credentials!)}`,
+          [ZoneRpcAuthentication.headerName]: serialized,
+        },
+      },
+    })
+
+    const blockNumber = await transport.request({
+      method: 'eth_blockNumber',
+    })
+    expect(blockNumber).toBeDefined()
+    expect(typeof blockNumber).toBe('string')
+  })
+
+  test.skipIf(!credentials)('fails without auth token', async () => {
+    const transport = RpcTransport.fromHttp(rpcUrl, {
+      fetchOptions: {
+        headers: {
+          Authorization: `Basic ${btoa(credentials!)}`,
+        },
+      },
+    })
+
+    await expect(
+      transport.request({ method: 'eth_blockNumber' }),
+    ).rejects.toThrow()
+  })
+})

package/tempo/ZoneRpcAuthentication.ts

@@ -0,0 +1,423 @@
+import * as Errors from '../core/Errors.js'
+import * as Hash from '../core/Hash.js'
+import * as Hex from '../core/Hex.js'
+import type { Compute, PartialBy } from '../core/internal/types.js'
+import * as SignatureEnvelope from './SignatureEnvelope.js'
+import * as TempoAddress from './TempoAddress.js'
+
+/**
+ * Header name used to transport Zone RPC authentication tokens.
+ */
+export const headerName = 'X-Authorization-Token' as const
+
+/**
+ * 32-byte domain separator used when hashing Zone RPC authentication tokens.
+ */
+export const magicBytes =
+  '0x54656d706f5a6f6e655250430000000000000000000000000000000000000000' as const
+
+/**
+ * Size, in bytes, of the fixed Zone RPC authentication fields.
+ */
+export const fieldsSize = 29 as const
+
+/** Current Zone RPC authentication version. */
+export const version = 0 as const
+
+/** Current Zone RPC authentication version. */
+export type Version = typeof version
+
+/**
+ * Root type for a Tempo Zone RPC authentication token.
+ *
+ * Zone RPC authentication tokens are short-lived, read-only credentials used to
+ * authenticate requests to Tempo private zone RPC endpoints.
+ *
+ * [Zone RPC Specification](https://docs.tempo.xyz/protocol/privacy/rpc#authorization-tokens)
+ */
+export type ZoneRpcAuthentication<
+  signed extends boolean = boolean,
+  bigintType = bigint,
+  numberType = number,
+> = Compute<
+  {
+    /** Zone chain ID for replay protection. */
+    chainId: numberType
+    /** Unix timestamp when the token expires. */
+    expiresAt: numberType
+    /** Unix timestamp when the token was issued. */
+    issuedAt: numberType
+    /** Zone RPC authentication version. Always `0` for the current spec. */
+    version: Version
+    /** Numeric zone identifier. */
+    zoneId: numberType
+  } & (signed extends true
+    ? { signature: SignatureEnvelope.SignatureEnvelope<bigintType, numberType> }
+    : {
+        signature?:
+          | SignatureEnvelope.SignatureEnvelope<bigintType, numberType>
+          | undefined
+      })
+>
+
+/** Input type for a Zone RPC authentication token. */
+export type Input = PartialBy<ZoneRpcAuthentication<false>, 'version'>
+
+/** 29-byte fixed Zone RPC authentication field suffix. */
+export type Fields = Hex.Hex
+
+/** Hex-encoded serialized Zone RPC authentication token. */
+export type Serialized = Hex.Hex
+
+/** Signed Zone RPC authentication token. */
+export type Signed<
+  bigintType = bigint,
+  numberType = number,
+> = ZoneRpcAuthentication<true, bigintType, numberType>
+
+/**
+ * Instantiates a typed Zone RPC authentication token.
+ *
+ * @example
+ * ```ts twoslash
+ * import { ZoneRpcAuthentication } from 'ox/tempo'
+ *
+ * const authentication = ZoneRpcAuthentication.from({
+ *   chainId: 4217000026,
+ *   expiresAt: 1711235160,
+ *   issuedAt: 1711234560,
+ *   zoneId: 26,
+ * })
+ * ```
+ *
+ * @example
+ * ### Attaching Signatures
+ *
+ * ```ts twoslash
+ * import { Secp256k1 } from 'ox'
+ * import { ZoneRpcAuthentication } from 'ox/tempo'
+ *
+ * const authentication = ZoneRpcAuthentication.from({
+ *   chainId: 4217000026,
+ *   expiresAt: 1711235160,
+ *   issuedAt: 1711234560,
+ *   zoneId: 26,
+ * })
+ *
+ * const signature = Secp256k1.sign({
+ *   payload: ZoneRpcAuthentication.getSignPayload(authentication),
+ *   privateKey: '0x...',
+ * })
+ *
+ * const authentication_signed = ZoneRpcAuthentication.from(authentication, {
+ *   signature,
+ * })
+ * ```
+ *
+ * @param authentication - Zone RPC authentication token fields.
+ * @param options - Zone RPC authentication options.
+ * @returns The instantiated Zone RPC authentication token.
+ */
+export function from<
+  const authentication extends Input | ZoneRpcAuthentication,
+  const signature extends SignatureEnvelope.from.Value | undefined = undefined,
+>(
+  authentication: authentication | ZoneRpcAuthentication,
+  options: from.Options<signature> = {},
+): from.ReturnType<authentication, signature> {
+  const auth = authentication as ZoneRpcAuthentication
+  const resolved = {
+    ...auth,
+    version,
+  }
+  if (options.signature)
+    return {
+      ...resolved,
+      signature: SignatureEnvelope.from(options.signature),
+    } as never
+  return resolved as never
+}
+
+export declare namespace from {
+  type Options<
+    signature extends SignatureEnvelope.from.Value | undefined =
+      | SignatureEnvelope.from.Value
+      | undefined,
+  > = {
+    /** The signature to attach to the authentication token. */
+    signature?: signature | SignatureEnvelope.SignatureEnvelope | undefined
+  }
+
+  type ReturnType<
+    authentication extends
+      | ZoneRpcAuthentication
+      | Input = ZoneRpcAuthentication,
+    signature extends SignatureEnvelope.from.Value | undefined =
+      | SignatureEnvelope.from.Value
+      | undefined,
+  > = Compute<
+    authentication & {
+      readonly version: Version
+    } & (signature extends SignatureEnvelope.from.Value
+        ? { signature: SignatureEnvelope.from.ReturnValue<signature> }
+        : {})
+  >
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/**
+ * Parses a serialized Zone RPC authentication token.
+ *
+ * The serialized format is `<signature><29-byte fields>`. The signature is parsed
+ * from the prefix and the fixed-length fields are parsed from the suffix.
+ *
+ * @example
+ * ```ts twoslash
+ * import { ZoneRpcAuthentication } from 'ox/tempo'
+ *
+ * const authentication = ZoneRpcAuthentication.deserialize('0x...')
+ * ```
+ *
+ * @param serialized - The serialized Zone RPC authentication token.
+ * @returns The parsed Zone RPC authentication token.
+ */
+export function deserialize(serialized: Serialized): Signed {
+  const size = Hex.size(serialized)
+  if (size <= fieldsSize)
+    throw new InvalidSerializedError({
+      reason: `Serialized authentication must be longer than ${fieldsSize} bytes.`,
+      serialized,
+    })
+
+  const fieldsOffset = size - fieldsSize
+  const signature = Hex.slice(serialized, 0, fieldsOffset)
+  const fields = Hex.slice(serialized, fieldsOffset)
+
+  const parsedVersion = Hex.toNumber(Hex.slice(fields, 0, 1), { size: 1 })
+  if (parsedVersion !== version)
+    throw new InvalidSerializedError({
+      reason: `Unsupported authentication version "${parsedVersion}". Expected "${version}".`,
+      serialized,
+    })
+
+  return {
+    chainId: Hex.toNumber(Hex.slice(fields, 5, 13), { size: 8 }),
+    expiresAt: Hex.toNumber(Hex.slice(fields, 21, 29), { size: 8 }),
+    issuedAt: Hex.toNumber(Hex.slice(fields, 13, 21), { size: 8 }),
+    signature: SignatureEnvelope.deserialize(signature),
+    version,
+    zoneId: Hex.toNumber(Hex.slice(fields, 1, 5), { size: 4 }),
+  }
+}
+
+export declare namespace deserialize {
+  type ErrorType =
+    | InvalidSerializedError
+    | SignatureEnvelope.CoercionError
+    | SignatureEnvelope.InvalidSerializedError
+    | Hex.size.ErrorType
+    | Hex.slice.ErrorType
+    | Hex.toNumber.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Returns the 29-byte fixed field suffix for a Zone RPC authentication token.
+ *
+ * @example
+ * ```ts twoslash
+ * import { ZoneRpcAuthentication } from 'ox/tempo'
+ *
+ * const fields = ZoneRpcAuthentication.getFields({
+ *   chainId: 4217000026,
+ *   expiresAt: 1711235160,
+ *   issuedAt: 1711234560,
+ *   zoneId: 26,
+ * })
+ * ```
+ *
+ * @param authentication - The Zone RPC authentication token.
+ * @returns The fixed 29-byte field suffix.
+ */
+export function getFields(
+  authentication: PartialBy<ZoneRpcAuthentication, 'version'>,
+): Fields {
+  return Hex.concat(
+    Hex.fromNumber(version, { size: 1 }),
+    Hex.fromNumber(authentication.zoneId, { size: 4 }),
+    Hex.fromNumber(authentication.chainId, { size: 8 }),
+    Hex.fromNumber(authentication.issuedAt, { size: 8 }),
+    Hex.fromNumber(authentication.expiresAt, { size: 8 }),
+  )
+}
+
+export declare namespace getFields {
+  type ErrorType =
+    | Hex.concat.ErrorType
+    | Hex.fromNumber.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Computes the sign payload for a Zone RPC authentication token.
+ *
+ * When `userAddress` is provided, the payload is wrapped as
+ * `keccak256(0x04 || authHash || userAddress)` to match V2 keychain signing.
+ *
+ * @example
+ * ```ts twoslash
+ * import { ZoneRpcAuthentication } from 'ox/tempo'
+ *
+ * const authentication = ZoneRpcAuthentication.from({
+ *   chainId: 4217000026,
+ *   expiresAt: 1711235160,
+ *   issuedAt: 1711234560,
+ *   zoneId: 26,
+ * })
+ *
+ * const payload = ZoneRpcAuthentication.getSignPayload(authentication)
+ * ```
+ *
+ * @param authentication - The Zone RPC authentication token.
+ * @param options - Options.
+ * @returns The sign payload.
+ */
+export function getSignPayload(
+  authentication: PartialBy<ZoneRpcAuthentication, 'version'>,
+  options: getSignPayload.Options = {},
+): Hex.Hex {
+  const authHash = hash(authentication)
+  if (options.userAddress)
+    return Hash.keccak256(
+      Hex.concat('0x04', authHash, TempoAddress.resolve(options.userAddress)),
+    )
+  return authHash
+}
+
+export declare namespace getSignPayload {
+  type Options = {
+    /**
+     * Root account address for keychain access-key signing.
+     *
+     * When provided, computes `keccak256(0x04 || authHash || userAddress)`
+     * instead of the raw `authHash`.
+     */
+    userAddress?: TempoAddress.Address | undefined
+  }
+
+  type ErrorType = hash.ErrorType | Errors.GlobalErrorType
+}
+
+/**
+ * Computes the raw authorization hash for a Zone RPC authentication token.
+ *
+ * The hash is `keccak256(magicBytes || fields)`.
+ *
+ * @example
+ * ```ts twoslash
+ * import { ZoneRpcAuthentication } from 'ox/tempo'
+ *
+ * const authentication = ZoneRpcAuthentication.from({
+ *   chainId: 4217000026,
+ *   expiresAt: 1711235160,
+ *   issuedAt: 1711234560,
+ *   zoneId: 26,
+ * })
+ *
+ * const hash = ZoneRpcAuthentication.hash(authentication)
+ * ```
+ *
+ * @param authentication - The Zone RPC authentication token.
+ * @returns The authorization hash.
+ */
+export function hash(
+  authentication: PartialBy<ZoneRpcAuthentication, 'version'>,
+): Hex.Hex {
+  return Hash.keccak256(Hex.concat(magicBytes, getFields(authentication)))
+}
+
+export declare namespace hash {
+  type ErrorType =
+    | getFields.ErrorType
+    | Hash.keccak256.ErrorType
+    | Hex.concat.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Serializes a Zone RPC authentication token to hex.
+ *
+ * The serialized format is `<signature><29-byte fields>`.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Secp256k1 } from 'ox'
+ * import { ZoneRpcAuthentication } from 'ox/tempo'
+ *
+ * const authentication = ZoneRpcAuthentication.from({
+ *   chainId: 4217000026,
+ *   expiresAt: 1711235160,
+ *   issuedAt: 1711234560,
+ *   zoneId: 26,
+ * })
+ *
+ * const signature = Secp256k1.sign({
+ *   payload: ZoneRpcAuthentication.getSignPayload(authentication),
+ *   privateKey: '0x...',
+ * })
+ *
+ * const serialized = ZoneRpcAuthentication.serialize(authentication, {
+ *   signature,
+ * })
+ * ```
+ *
+ * @param authentication - The Zone RPC authentication token.
+ * @param options - Serialization options.
+ * @returns The serialized authentication token.
+ */
+export function serialize(
+  authentication: PartialBy<ZoneRpcAuthentication, 'version'>,
+  options: serialize.Options = {},
+): Serialized {
+  const signature = options.signature || authentication.signature
+  if (!signature) throw new MissingSignatureError()
+
+  return Hex.concat(
+    SignatureEnvelope.serialize(SignatureEnvelope.from(signature)),
+    getFields(authentication),
+  )
+}
+
+export declare namespace serialize {
+  type Options = {
+    /** Signature to attach to the serialized authentication token. */
+    signature?: SignatureEnvelope.from.Value | undefined
+  }
+
+  type ErrorType =
+    | getFields.ErrorType
+    | MissingSignatureError
+    | SignatureEnvelope.CoercionError
+    | Errors.GlobalErrorType
+}
+
+/** Error thrown when a serialized authentication token cannot be deserialized. */
+export class InvalidSerializedError extends Errors.BaseError {
+  override readonly name = 'ZoneRpcAuthentication.InvalidSerializedError'
+
+  constructor({ reason, serialized }: { reason: string; serialized: Hex.Hex }) {
+    super(`Unable to deserialize Zone RPC authentication: ${reason}`, {
+      metaMessages: [`Serialized: ${serialized}`],
+    })
+  }
+}
+
+/** Error thrown when serializing an authentication token without a signature. */
+export class MissingSignatureError extends Errors.BaseError {
+  override readonly name = 'ZoneRpcAuthentication.MissingSignatureError'
+
+  constructor() {
+    super('Zone RPC authentication is missing a signature.')
+  }
+}