@zerodev/permissions 5.2.0

package/signers/toWebAuthnSigner.ts

@@ -0,0 +1,246 @@
+import type { PublicKeyCredentialRequestOptionsJSON } from "@simplewebauthn/typescript-types"
+import type { TypedData } from "abitype"
+import { SignTransactionNotSupportedBySmartAccount } from "permissionless/accounts"
+import {
+    type Chain,
+    type Client,
+    type Hex,
+    type LocalAccount,
+    type SignTypedDataParameters,
+    type Transport,
+    type TypedDataDefinition,
+    getTypesForEIP712Domain,
+    hashTypedData,
+    validateTypedData
+} from "viem"
+import { type SignableMessage, encodeAbiParameters } from "viem"
+import { toAccount } from "viem/accounts"
+import { getChainId } from "viem/actions"
+import { WEBAUTHN_SIGNER_CONTRACT } from "../constants.js"
+import type { ModularSigner, ModularSignerParams } from "../types.js"
+import { WebAuthnMode, toWebAuthnPubKey } from "./toWebAuthnPubKey.js"
+import {
+    b64ToBytes,
+    findQuoteIndices,
+    isRIP7212SupportedNetwork,
+    parseAndNormalizeSig,
+    uint8ArrayToHexString
+} from "./webAuthnUtils.js"
+
+export type WebAuthnKey = {
+    pubX: bigint
+    pubY: bigint
+    authenticatorIdHash: Hex
+}
+
+export type WebAuthnModularSignerParams = ModularSignerParams & {
+    passkeyName: string
+    passkeyServerUrl: string
+    pubKey?: WebAuthnKey
+    mode?: WebAuthnMode
+}
+
+export const toWebAuthnSigner = async <
+    TTransport extends Transport = Transport,
+    TChain extends Chain | undefined = Chain | undefined
+>(
+    client: Client<TTransport, TChain, undefined>,
+    {
+        signerContractAddress = WEBAUTHN_SIGNER_CONTRACT,
+        pubKey,
+        passkeyServerUrl,
+        passkeyName,
+        mode = WebAuthnMode.Register
+    }: WebAuthnModularSignerParams
+): Promise<ModularSigner> => {
+    pubKey =
+        pubKey ??
+        (await toWebAuthnPubKey({
+            passkeyName,
+            passkeyServerUrl,
+            mode
+        }))
+    if (!pubKey) {
+        throw new Error("WebAuthn public key not found")
+    }
+
+    const chainId = await getChainId(client)
+
+    const signMessageUsingWebAuthn = async (message: SignableMessage) => {
+        let messageContent: string
+        if (typeof message === "string") {
+            // message is a string
+            messageContent = message
+        } else if ("raw" in message && typeof message.raw === "string") {
+            // message.raw is a Hex string
+            messageContent = message.raw
+        } else if ("raw" in message && message.raw instanceof Uint8Array) {
+            // message.raw is a ByteArray
+            messageContent = message.raw.toString()
+        } else {
+            throw new Error("Unsupported message format")
+        }
+
+        // remove 0x prefix if present
+        const formattedMessage = messageContent.startsWith("0x")
+            ? messageContent.slice(2)
+            : messageContent
+
+        if (window.sessionStorage === undefined) {
+            throw new Error("sessionStorage is not available")
+        }
+        const userId = sessionStorage.getItem("userId")
+
+        // initiate signing
+        const signInitiateResponse = await fetch(
+            `${passkeyServerUrl}/sign-initiate`,
+            {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ data: formattedMessage, userId }),
+                credentials: "include"
+            }
+        )
+        const signInitiateResult = await signInitiateResponse.json()
+
+        // prepare assertion options
+        const assertionOptions: PublicKeyCredentialRequestOptionsJSON = {
+            challenge: signInitiateResult.challenge,
+            allowCredentials: signInitiateResult.allowCredentials,
+            userVerification: "required"
+        }
+
+        // start authentication (signing)
+
+        const { startAuthentication } = await import("@simplewebauthn/browser")
+        const cred = await startAuthentication(assertionOptions)
+
+        // verify signature from server
+        const verifyResponse = await fetch(`${passkeyServerUrl}/sign-verify`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ cred, userId }),
+            credentials: "include"
+        })
+
+        const verifyResult = await verifyResponse.json()
+
+        if (!verifyResult.success) {
+            throw new Error("Signature not verified")
+        }
+
+        // get authenticator data
+        const authenticatorData = verifyResult.authenticatorData
+        const authenticatorDataHex = uint8ArrayToHexString(
+            b64ToBytes(authenticatorData)
+        )
+
+        // get client data JSON
+        const clientDataJSON = atob(cred.response.clientDataJSON)
+
+        // get challenge and response type location
+        const { beforeType } = findQuoteIndices(clientDataJSON)
+
+        // get signature r,s
+        const signature = verifyResult.signature
+        const signatureHex = uint8ArrayToHexString(b64ToBytes(signature))
+        const { r, s } = parseAndNormalizeSig(signatureHex)
+
+        // encode signature
+        const encodedSignature = encodeAbiParameters(
+            [
+                { name: "authenticatorData", type: "bytes" },
+                { name: "clientDataJSON", type: "string" },
+                { name: "responseTypeLocation", type: "uint256" },
+                { name: "r", type: "uint256" },
+                { name: "s", type: "uint256" },
+                { name: "usePrecompiled", type: "bool" }
+            ],
+            [
+                authenticatorDataHex,
+                clientDataJSON,
+                beforeType,
+                BigInt(r),
+                BigInt(s),
+                isRIP7212SupportedNetwork(chainId)
+            ]
+        )
+        return encodedSignature
+    }
+    const account: LocalAccount = toAccount({
+        // note that this address will be overwritten by actual address
+        address: "0x0000000000000000000000000000000000000000",
+        async signMessage({ message }) {
+            return signMessageUsingWebAuthn(message)
+        },
+        async signTransaction(_, __) {
+            throw new SignTransactionNotSupportedBySmartAccount()
+        },
+        async signTypedData<
+            const TTypedData extends TypedData | Record<string, unknown>,
+            TPrimaryType extends
+                | keyof TTypedData
+                | "EIP712Domain" = keyof TTypedData
+        >(typedData: TypedDataDefinition<TTypedData, TPrimaryType>) {
+            const { domain, message, primaryType } =
+                typedData as unknown as SignTypedDataParameters
+
+            const types = {
+                EIP712Domain: getTypesForEIP712Domain({ domain }),
+                ...typedData.types
+            }
+
+            validateTypedData({ domain, message, primaryType, types })
+
+            const hash = hashTypedData(typedData)
+            return signMessageUsingWebAuthn(hash)
+        }
+    })
+
+    return {
+        account,
+        signerContractAddress,
+        getSignerData: () => {
+            if (!pubKey) {
+                throw new Error("WebAuthn public key not found")
+            }
+            return encodeAbiParameters(
+                [
+                    {
+                        components: [
+                            { name: "pubKeyX", type: "uint256" },
+                            { name: "pubKeyY", type: "uint256" }
+                        ],
+                        name: "WebAuthnSignerData",
+                        type: "tuple"
+                    },
+                    { name: "authenticatorIdHash", type: "bytes32" }
+                ],
+                [
+                    { pubKeyX: pubKey.pubX, pubKeyY: pubKey.pubY },
+                    pubKey.authenticatorIdHash
+                ]
+            )
+        },
+        getDummySignature: () => {
+            return encodeAbiParameters(
+                [
+                    { name: "authenticatorData", type: "bytes" },
+                    { name: "clientDataJSON", type: "string" },
+                    { name: "responseTypeLocation", type: "uint256" },
+                    { name: "r", type: "uint256" },
+                    { name: "s", type: "uint256" },
+                    { name: "usePrecompiled", type: "bool" }
+                ],
+                [
+                    "0x49960de5880e8c687434170f6476605b8fe4aeb9a28632c7995cf3ba831d97631d00000000",
+                    '{"type":"webauthn.get","challenge":"tbxXNFS9X_4Byr1cMwqKrIGB-_30a0QhZ6y7ucM0BOE","origin":"http://localhost:3000","crossOrigin":false}',
+                    1n,
+                    44941127272049826721201904734628716258498742255959991581049806490182030242267n,
+                    9910254599581058084911561569808925251374718953855182016200087235935345969636n,
+                    false
+                ]
+            )
+        }
+    }
+}

package/signers/utils/toSignerId.ts

@@ -0,0 +1,9 @@
+import { type Hex, concat, encodeAbiParameters } from "viem"
+import type { ModularSigner } from "../../types.js"
+
+export const toSignerId = (signer: ModularSigner): Hex => {
+    return encodeAbiParameters(
+        [{ name: "signerData", type: "bytes" }],
+        [concat([signer.signerContractAddress, signer.getSignerData()])]
+    )
+}

package/signers/webAuthnUtils.ts

@@ -0,0 +1,54 @@
+import { p256 } from "@noble/curves/p256"
+import { type Hex, bytesToBigInt, hexToBytes } from "viem"
+
+const RIP7212_SUPPORTED_NETWORKS = [80001]
+
+export const uint8ArrayToHexString = (array: Uint8Array): `0x${string}` => {
+    return `0x${Array.from(array, (byte) =>
+        byte.toString(16).padStart(2, "0")
+    ).join("")}` as `0x${string}`
+}
+
+export const b64ToBytes = (base64: string): Uint8Array => {
+    const paddedBase64 = base64
+        .replace(/-/g, "+")
+        .replace(/_/g, "/")
+        .padEnd(base64.length + ((4 - (base64.length % 4)) % 4), "=")
+    const binString = atob(paddedBase64)
+    return Uint8Array.from(binString, (m) => m.codePointAt(0) ?? 0)
+}
+
+export const findQuoteIndices = (
+    input: string
+): { beforeType: bigint; beforeChallenge: bigint } => {
+    const beforeTypeIndex = BigInt(input.lastIndexOf('"type":"webauthn.get"'))
+    const beforeChallengeIndex = BigInt(input.indexOf('"challenge'))
+    return {
+        beforeType: beforeTypeIndex,
+        beforeChallenge: beforeChallengeIndex
+    }
+}
+
+// Parse DER-encoded P256-SHA256 signature to contract-friendly signature
+// and normalize it so the signature is not malleable.
+export function parseAndNormalizeSig(derSig: Hex): { r: bigint; s: bigint } {
+    const parsedSignature = p256.Signature.fromDER(derSig.slice(2))
+    const bSig = hexToBytes(`0x${parsedSignature.toCompactHex()}`)
+    // assert(bSig.length === 64, "signature is not 64 bytes");
+    const bR = bSig.slice(0, 32)
+    const bS = bSig.slice(32)
+
+    // Avoid malleability. Ensure low S (<= N/2 where N is the curve order)
+    const r = bytesToBigInt(bR)
+    let s = bytesToBigInt(bS)
+    const n = BigInt(
+        "0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551"
+    )
+    if (s > n / 2n) {
+        s = n - s
+    }
+    return { r, s }
+}
+
+export const isRIP7212SupportedNetwork = (chainId: number): boolean =>
+    RIP7212_SUPPORTED_NETWORKS.includes(chainId)

package/toPermissionValidator.ts

@@ -0,0 +1,151 @@
+import { KernelV3AccountAbi } from "@zerodev/sdk"
+import {
+    getAction,
+    getEntryPointVersion,
+    getUserOperationHash
+} from "permissionless"
+import type { EntryPoint } from "permissionless/types/entrypoint"
+import {
+    type Address,
+    type Chain,
+    type Client,
+    type Hex,
+    type Transport,
+    concat,
+    encodeAbiParameters,
+    keccak256,
+    slice,
+    zeroAddress
+} from "viem"
+import { getChainId, readContract } from "viem/actions"
+import { PolicyFlags } from "./constants.js"
+import { toPolicyId } from "./policies/index.js"
+import { toSignerId } from "./signers/index.js"
+import type {
+    PermissionData,
+    PermissionPlugin,
+    PermissionPluginParams
+} from "./types.js"
+
+export async function toPermissionValidator<
+    entryPoint extends EntryPoint,
+    TTransport extends Transport = Transport,
+    TChain extends Chain | undefined = Chain | undefined
+>(
+    client: Client<TTransport, TChain, undefined>,
+    {
+        signer,
+        policies,
+        entryPoint: entryPointAddress,
+        flag = PolicyFlags.FOR_ALL_VALIDATION
+    }: PermissionPluginParams
+): Promise<PermissionPlugin<entryPoint>> {
+    const chainId = await getChainId(client)
+    const entryPointVersion = getEntryPointVersion(entryPointAddress)
+
+    if (entryPointVersion !== "v0.7") {
+        throw new Error("Only EntryPoint 0.7 is supported")
+    }
+
+    const getEnableData = async (
+        _kernelAccountAddress?: Address
+    ): Promise<Hex> => {
+        const enableData = encodeAbiParameters(
+            [{ name: "policyAndSignerData", type: "bytes[]" }],
+            [
+                [
+                    ...policies.map((policy) =>
+                        concat([
+                            policy.getPolicyInfoInBytes(),
+                            policy.getPolicyData()
+                        ])
+                    ),
+                    concat([
+                        flag,
+                        signer.signerContractAddress,
+                        signer.getSignerData()
+                    ])
+                ]
+            ]
+        )
+        return enableData
+    }
+
+    const getPermissionId = (): Hex => {
+        const pIdData = encodeAbiParameters(
+            [{ name: "policyAndSignerData", type: "bytes[]" }],
+            [[toPolicyId(policies), flag, toSignerId(signer)]]
+        )
+        return slice(keccak256(pIdData), 0, 4)
+    }
+
+    return {
+        ...signer.account,
+        validatorType: "PERMISSION",
+        address: zeroAddress,
+        source: "PermissionValidator",
+        getEnableData,
+        getIdentifier: getPermissionId,
+
+        signMessage: async ({ message }) => {
+            return concat([
+                "0xff",
+                await signer.account.signMessage({ message })
+            ])
+        },
+        signTypedData: async (typedData) => {
+            return concat([
+                "0xff",
+                await signer.account.signTypedData(typedData)
+            ])
+        },
+
+        signUserOperation: async (userOperation): Promise<Hex> => {
+            const userOpHash = getUserOperationHash({
+                userOperation: { ...userOperation, signature: "0x" },
+                entryPoint: entryPointAddress,
+                chainId
+            })
+
+            const signature = await signer.account.signMessage({
+                message: { raw: userOpHash }
+            })
+            return concat(["0xff", signature])
+        },
+
+        async getNonceKey(_accountAddress?: Address, customNonceKey?: bigint) {
+            if (customNonceKey) {
+                return customNonceKey
+            }
+            return 0n
+        },
+
+        async getDummySignature(_userOperation) {
+            return concat(["0xff", signer.getDummySignature()])
+        },
+        getPluginSerializationParams: (): PermissionData => {
+            return {
+                policies
+            }
+        },
+        isEnabled: async (
+            kernelAccountAddress: Address,
+            _selector: Hex
+        ): Promise<boolean> => {
+            try {
+                const permissionConfig = await getAction(
+                    client,
+                    readContract
+                )({
+                    abi: KernelV3AccountAbi,
+                    address: kernelAccountAddress,
+                    functionName: "permissionConfig",
+                    args: [getPermissionId()]
+                })
+                return permissionConfig.signer === signer.signerContractAddress
+            } catch (error) {
+                return false
+            }
+        }
+    }
+}

package/types.ts

@@ -0,0 +1,75 @@
+import { type KernelValidator } from "@zerodev/sdk"
+import type { Action, PluginValidityData } from "@zerodev/sdk/types"
+import type { EntryPoint } from "permissionless/types/entrypoint"
+import type { Abi, Address, Hex, LocalAccount } from "viem"
+import { PolicyFlags } from "./constants.js"
+import type {
+    CallPolicyParams,
+    GasPolicyParams,
+    RateLimitPolicyParams,
+    SignatureCallerPolicyParams,
+    SudoPolicyParams,
+    TimestampPolicyParams
+} from "./policies/index.js"
+
+export type PermissionPlugin<entryPoint extends EntryPoint> = KernelValidator<
+    entryPoint,
+    "PermissionValidator"
+> & {
+    getPluginSerializationParams: () => PermissionData
+}
+
+export type ModularSignerParams = {
+    signerContractAddress?: Address
+}
+export type PolicyParams = {
+    policyAddress?: Address
+    policyFlag?: PolicyFlags
+}
+
+export type ModularSigner = {
+    account: LocalAccount
+    signerContractAddress: Address
+    getSignerData: () => Hex
+    getDummySignature: () => Hex
+}
+
+export type Policy = {
+    getPolicyData: () => Hex
+    getPolicyInfoInBytes: () => Hex
+    // return params directly to serialize/deserialize Policy
+    policyParams:
+        | (CallPolicyParams<Abi | readonly unknown[], string> & {
+              type: "call"
+          })
+        | (GasPolicyParams & { type: "gas" })
+        | (RateLimitPolicyParams & { type: "rate-limit" })
+        | (SignatureCallerPolicyParams & { type: "signature-caller" })
+        | (SudoPolicyParams & { type: "sudo" })
+        | (TimestampPolicyParams & { type: "timestamp" })
+}
+
+export type PermissionPluginParams = {
+    signer: ModularSigner
+    policies: Policy[]
+    entryPoint: EntryPoint
+    flag?: PolicyFlags
+}
+
+export interface PermissionData {
+    policies?: Policy[]
+}
+
+export type ExportPermissionAccountParams = {
+    initCode: Hex
+    accountAddress: Address
+}
+
+export type PermissionAccountParams = {
+    permissionParams: PermissionData
+    action: Action
+    validityData: PluginValidityData
+    accountParams: ExportPermissionAccountParams
+    enableSignature?: Hex
+    privateKey?: Hex
+}

package/utils.ts

@@ -0,0 +1,42 @@
+import type { EntryPoint } from "permissionless/types"
+import type { PermissionAccountParams, PermissionPlugin } from "./types.js"
+
+export function base64ToBytes(base64: string) {
+    const binString = atob(base64)
+    return Uint8Array.from(binString, (m) => m.codePointAt(0) as number)
+}
+
+export function bytesToBase64(bytes: Uint8Array) {
+    const binString = Array.from(bytes, (x) => String.fromCodePoint(x)).join("")
+    return btoa(binString)
+}
+
+export function isPermissionValidatorPlugin<entryPoint extends EntryPoint>(
+    // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+    plugin: any
+): plugin is PermissionPlugin<entryPoint> {
+    return plugin?.getPluginSerializationParams !== undefined
+}
+
+export const serializePermissionAccountParams = (
+    params: PermissionAccountParams
+) => {
+    // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+    const replacer = (_: string, value: any) => {
+        if (typeof value === "bigint") {
+            return value.toString()
+        }
+        return value
+    }
+
+    const jsonString = JSON.stringify(params, replacer)
+    const uint8Array = new TextEncoder().encode(jsonString)
+    const base64String = bytesToBase64(uint8Array)
+    return base64String
+}
+
+export const deserializePermissionAccountParams = (params: string) => {
+    const uint8Array = base64ToBytes(params)
+    const jsonString = new TextDecoder().decode(uint8Array)
+    return JSON.parse(jsonString) as PermissionAccountParams
+}