@cofhe/sdk 0.0.0-beta-20251027110729

package/dist/permit-S9CnI6MF.d.ts

@@ -0,0 +1,333 @@
+import * as zod from 'zod';
+import { PublicClient, WalletClient } from 'viem';
+
+type EthEncryptedData = {
+    data: Uint8Array;
+    public_key: Uint8Array;
+    nonce: Uint8Array;
+};
+/**
+ * A class representing a SealingKey which provides cryptographic sealing (encryption)
+ * and unsealing (decryption) capabilities.
+ */
+declare class SealingKey$1 {
+    /**
+     * The private key used for decryption.
+     */
+    privateKey: string;
+    /**
+     * The public key used for encryption.
+     */
+    publicKey: string;
+    /**
+     * Constructs a SealingKey instance with the given private and public keys.
+     *
+     * @param {string} privateKey - The private key used for decryption.
+     * @param {string} publicKey - The public key used for encryption.
+     * @throws Will throw an error if the provided keys lengths do not match
+     *         the required lengths for private and public keys.
+     */
+    constructor(privateKey: string, publicKey: string);
+    unseal: (parsedData: EthEncryptedData) => bigint;
+    /**
+     * Serializes the SealingKey to a JSON object.
+     */
+    serialize: () => {
+        privateKey: string;
+        publicKey: string;
+    };
+    /**
+     * Deserializes the SealingKey from a JSON object.
+     */
+    static deserialize: (privateKey: string, publicKey: string) => SealingKey$1;
+    /**
+     * Seals (encrypts) the provided message for a receiver with the specified public key.
+     *
+     * @param {bigint | number} value - The message to be encrypted.
+     * @param {string} publicKey - The public key of the intended recipient.
+     * @returns string - The encrypted message in hexadecimal format.
+     * @static
+     * @throws Will throw if the provided publicKey or value do not meet defined preconditions.
+     */
+    static seal: (value: bigint | number, publicKey: string) => EthEncryptedData;
+}
+/**
+ * Asynchronously generates a new SealingKey.
+ * This function uses the 'nacl' library to create a new public/private key pair for sealing purposes.
+ * A sealing key is used to encrypt data such that it can only be unsealed (decrypted) by the owner of the corresponding private key.
+ * @returns {Promise<SealingKey>} - A promise that resolves to a new SealingKey object containing the hexadecimal strings of the public and private keys.
+ */
+declare const GenerateSealingKey: () => Promise<SealingKey$1>;
+
+/**
+ * EIP712 related types
+ */
+type EIP712Type = {
+    name: string;
+    type: string;
+};
+type EIP712Types = Record<string, EIP712Type[]>;
+type EIP712Message = Record<string, string>;
+type EIP712Domain = {
+    chainId: number;
+    name: string;
+    verifyingContract: `0x${string}`;
+    version: string;
+};
+/**
+ * Sealing key type - using the actual SealingKey class
+ */
+type SealingKey = SealingKey$1;
+
+/**
+ * Core Permit interface - immutable design for React compatibility
+ */
+interface Permit {
+    /**
+     * Name for this permit, for organization and UI usage, not included in signature.
+     */
+    name: string;
+    /**
+     * The type of the Permit (self / sharing)
+     * (self) Permit that will be signed and used by the issuer
+     * (sharing) Permit that is signed by the issuer, but intended to be shared with recipient
+     * (recipient) Permit that has been received, and signed by the recipient
+     */
+    type: 'self' | 'sharing' | 'recipient';
+    /**
+     * (base) User that initially created the permission, target of data fetching
+     */
+    issuer: `0x${string}`;
+    /**
+     * (base) Expiration timestamp
+     */
+    expiration: number;
+    /**
+     * (sharing) The user that this permission will be shared with
+     * ** optional, use `address(0)` to disable **
+     */
+    recipient: `0x${string}`;
+    /**
+     * (issuer defined validation) An id used to query a contract to check this permissions validity
+     * ** optional, use `0` to disable **
+     */
+    validatorId: number;
+    /**
+     * (issuer defined validation) The contract to query to determine permission validity
+     * ** optional, user `address(0)` to disable **
+     */
+    validatorContract: `0x${string}`;
+    /**
+     * (base) The publicKey of a sealingPair used to re-encrypt `issuer`s confidential data
+     *   (non-sharing) Populated by `issuer`
+     *   (sharing)     Populated by `recipient`
+     */
+    sealingPair: SealingKey;
+    /**
+     * (base) `signTypedData` signature created by `issuer`.
+     * (base) Shared- and Self- permissions differ in signature format: (`sealingKey` absent in shared signature)
+     *   (non-sharing) < issuer, expiration, recipient, validatorId, validatorContract, sealingKey >
+     *   (sharing)     < issuer, expiration, recipient, validatorId, validatorContract >
+     */
+    issuerSignature: `0x${string}`;
+    /**
+     * (sharing) `signTypedData` signature created by `recipient` with format:
+     * (sharing) < sealingKey, issuerSignature>
+     * ** required for shared permits **
+     */
+    recipientSignature: `0x${string}`;
+    /**
+     * EIP712 domain used to sign this permit.
+     * Should not be set manually, included in metadata as part of serialization flows.
+     */
+    _signedDomain?: EIP712Domain;
+}
+/**
+ * Optional additional metadata of a Permit
+ * Can be passed into the constructor, but not necessary
+ * Useful for deserialization
+ */
+interface PermitMetadata {
+    /**
+     * EIP712 domain used to sign this permit.
+     * Should not be set manually, included in metadata as part of serialization flows.
+     */
+    _signedDomain?: EIP712Domain;
+}
+/**
+ * Utility types for permit creation
+ */
+type CreateSelfPermitOptions = {
+    type?: 'self';
+    issuer: string;
+    name?: string;
+    expiration?: number;
+    validatorId?: number;
+    validatorContract?: string;
+};
+type CreateSharingPermitOptions = {
+    type?: 'sharing';
+    issuer: string;
+    recipient: string;
+    name?: string;
+    expiration?: number;
+    validatorId?: number;
+    validatorContract?: string;
+};
+type ImportSharedPermitOptions = {
+    type?: 'sharing';
+    issuer: string;
+    recipient: string;
+    issuerSignature: string;
+    name?: string;
+    expiration?: number;
+    validatorId?: number;
+    validatorContract?: string;
+};
+type SerializedPermit = Omit<Permit, 'sealingPair'> & {
+    _signedDomain?: EIP712Domain;
+    sealingPair: {
+        privateKey: string;
+        publicKey: string;
+    };
+};
+/**
+ * A type representing the Permission struct that is passed to Permissioned.sol to grant encrypted data access.
+ */
+type Permission = Expand<Omit<Permit, 'name' | 'type' | 'sealingPair'> & {
+    sealingKey: `0x${string}`;
+}>;
+/**
+ * Validation result type
+ */
+interface ValidationResult {
+    valid: boolean;
+    error: string | null;
+}
+/**
+ * Signature types for EIP712 signing
+ */
+type PermitSignaturePrimaryType = 'PermissionedV2IssuerSelf' | 'PermissionedV2IssuerShared' | 'PermissionedV2Recipient';
+type Expand<T> = T extends infer O ? {
+    [K in keyof O]: O[K];
+} : never;
+
+/**
+ * Main Permit utilities - functional approach for React compatibility
+ */
+declare const PermitUtils: {
+    /**
+     * Create a self permit for personal use
+     */
+    createSelf: (options: CreateSelfPermitOptions) => Promise<Permit>;
+    /**
+     * Create a sharing permit to be shared with another user
+     */
+    createSharing: (options: CreateSharingPermitOptions) => Promise<Permit>;
+    /**
+     * Import a shared permit from various input formats
+     */
+    importShared: (options: ImportSharedPermitOptions | any | string) => Promise<Permit>;
+    /**
+     * Sign a permit with the provided wallet client
+     */
+    sign: (permit: Permit, publicClient: PublicClient, walletClient: WalletClient) => Promise<Permit>;
+    /**
+     * Create and sign a self permit in one operation
+     */
+    createSelfAndSign: (options: CreateSelfPermitOptions, publicClient: PublicClient, walletClient: WalletClient) => Promise<Permit>;
+    /**
+     * Create and sign a sharing permit in one operation
+     */
+    createSharingAndSign: (options: CreateSharingPermitOptions, publicClient: PublicClient, walletClient: WalletClient) => Promise<Permit>;
+    /**
+     * Import and sign a shared permit in one operation from various input formats
+     */
+    importSharedAndSign: (options: ImportSharedPermitOptions | any | string, publicClient: PublicClient, walletClient: WalletClient) => Promise<Permit>;
+    /**
+     * Deserialize a permit from serialized data
+     */
+    deserialize: (data: SerializedPermit) => Permit;
+    /**
+     * Serialize a permit for storage
+     */
+    serialize: (permit: Permit) => SerializedPermit;
+    /**
+     * Validate a permit
+     */
+    validate: (permit: Permit) => zod.SafeParseReturnType<{
+        type: "self" | "sharing" | "recipient";
+        issuer: string;
+        recipient?: string | undefined;
+        sealingPair?: {
+            privateKey: string;
+            publicKey: string;
+        } | undefined;
+        name?: string | undefined;
+        expiration?: number | undefined;
+        validatorId?: number | undefined;
+        validatorContract?: string | undefined;
+        issuerSignature?: string | undefined;
+        recipientSignature?: string | undefined;
+    }, {
+        recipient: `0x${string}`;
+        name: string;
+        type: "self" | "sharing" | "recipient";
+        issuer: `0x${string}`;
+        expiration: number;
+        validatorId: number;
+        validatorContract: `0x${string}`;
+        issuerSignature: string;
+        recipientSignature: string;
+        sealingPair?: {
+            privateKey: string;
+            publicKey: string;
+        } | undefined;
+    }>;
+    /**
+     * Get the permission object from a permit (for use in contracts)
+     */
+    getPermission: (permit: Permit, skipValidation?: boolean) => Permission;
+    /**
+     * Get a stable hash for the permit (used as key in storage)
+     */
+    getHash: (permit: Permit) => string;
+    /**
+     * Export permit data for sharing (removes sensitive fields)
+     */
+    export: (permit: Permit) => string;
+    /**
+     * Unseal encrypted data using the permit's sealing key
+     */
+    unseal: (permit: Permit, ciphertext: EthEncryptedData) => bigint;
+    /**
+     * Check if permit is expired
+     */
+    isExpired: (permit: Permit) => boolean;
+    /**
+     * Check if permit is signed
+     */
+    isSigned: (permit: Permit) => boolean;
+    /**
+     * Check if permit is valid
+     */
+    isValid: (permit: Permit) => ValidationResult;
+    /**
+     * Update permit name (returns new permit instance)
+     */
+    updateName: (permit: Permit, name: string) => Permit;
+    /**
+     * Fetch EIP712 domain from the blockchain
+     */
+    fetchEIP712Domain: (publicClient: PublicClient) => Promise<EIP712Domain>;
+    /**
+     * Check if permit's signed domain matches the provided domain
+     */
+    matchesDomain: (permit: Permit, domain: EIP712Domain) => boolean;
+    /**
+     * Check if permit's signed domain is valid for the current chain
+     */
+    checkSignedDomainValid: (permit: Permit, publicClient: PublicClient) => Promise<boolean>;
+};
+
+export { type CreateSelfPermitOptions as C, type EIP712Types as E, GenerateSealingKey as G, type ImportSharedPermitOptions as I, type Permit as P, type SerializedPermit as S, type ValidationResult as V, type PermitSignaturePrimaryType as a, type Permission as b, type EIP712Message as c, type CreateSharingPermitOptions as d, type PermitMetadata as e, type EIP712Domain as f, PermitUtils as g, SealingKey$1 as h, type EthEncryptedData as i, type EIP712Type as j, type Expand as k };