@cofhe/sdk 0.0.0-alpha-20260409113701

package/dist/permit-jRirYqFt.d.ts

@@ -0,0 +1,376 @@
+import { Hex, 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 {SealingKey} - A new SealingKey object containing the hexadecimal strings of the public and private keys.
+ */
+declare const GenerateSealingKey: () => 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: Hex;
+    version: string;
+};
+/**
+ * Sealing key type - using the actual SealingKey class
+ */
+type SealingKey = SealingKey$1;
+
+/**
+ * Core Permit interface - immutable design for React compatibility
+ */
+interface Permit {
+    /**
+     * Stable hash of relevant permit data, used as key in storage
+     */
+    hash: string;
+    /**
+     * 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: Hex;
+    /**
+     * (base) Expiration timestamp
+     */
+    expiration: number;
+    /**
+     * (sharing) The user that this permission will be shared with
+     * ** optional, use `address(0)` to disable **
+     */
+    recipient: Hex;
+    /**
+     * (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: Hex;
+    /**
+     * (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: Hex;
+    /**
+     * (sharing) `signTypedData` signature created by `recipient` with format:
+     * (sharing) < sealingKey, issuerSignature>
+     * ** required for shared permits **
+     */
+    recipientSignature: Hex;
+    /**
+     * EIP712 domain used to sign this permit.
+     * Should not be set manually, included in metadata as part of serialization flows.
+     */
+    _signedDomain?: EIP712Domain;
+}
+/**
+ * Permit discriminant helpers
+ */
+type PermitType = Permit['type'];
+/**
+ * Utility type to narrow a permit to a specific discriminant.
+ *
+ * Note: this only narrows the `type` field. Runtime/validation constraints
+ * (e.g. recipient == zeroAddress for self permits) are enforced elsewhere.
+ */
+type PermitOf<T extends PermitType> = Expand<Omit<Permit, 'type'> & {
+    type: T;
+}>;
+type SelfPermit = PermitOf<'self'>;
+type SharingPermit = PermitOf<'sharing'>;
+type RecipientPermit = PermitOf<'recipient'>;
+/**
+ * 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' | 'hash'> & {
+    sealingKey: Hex;
+}>;
+/**
+ * A type representing the permit fields that are used to generate the hash
+ */
+type PermitHashFields = Pick<Permit, 'type' | 'issuer' | 'expiration' | 'recipient' | 'validatorId' | 'validatorContract'>;
+/**
+ * Validation result type
+ */
+interface ValidationResult {
+    valid: boolean;
+    error: 'invalid-schema' | 'expired' | 'not-signed' | 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) => SelfPermit;
+    /**
+     * Create a sharing permit to be shared with another user
+     */
+    createSharing: (options: CreateSharingPermitOptions) => SharingPermit;
+    /**
+     * Import a shared permit from various input formats
+     */
+    importShared: (options: ImportSharedPermitOptions | string) => RecipientPermit;
+    /**
+     * Sign a permit with the provided wallet client
+     */
+    sign: <T extends Permit>(permit: T, publicClient: PublicClient, walletClient: WalletClient) => Promise<T>;
+    /**
+     * Create and sign a self permit in one operation
+     */
+    createSelfAndSign: (options: CreateSelfPermitOptions, publicClient: PublicClient, walletClient: WalletClient) => Promise<SelfPermit>;
+    /**
+     * Create and sign a sharing permit in one operation
+     */
+    createSharingAndSign: (options: CreateSharingPermitOptions, publicClient: PublicClient, walletClient: WalletClient) => Promise<SharingPermit>;
+    /**
+     * Import and sign a shared permit in one operation from various input formats
+     */
+    importSharedAndSign: (options: ImportSharedPermitOptions | string, publicClient: PublicClient, walletClient: WalletClient) => Promise<RecipientPermit>;
+    /**
+     * Deserialize a permit from serialized data
+     */
+    deserialize: (data: SerializedPermit) => Permit;
+    /**
+     * Serialize a permit for storage
+     */
+    serialize: (permit: Permit) => SerializedPermit;
+    /**
+     * Validate a permit (schema-level validation)
+     */
+    validateSchema: (permit: Permit) => {
+        name: string;
+        type: "self" | "sharing" | "recipient";
+        issuer: `0x${string}`;
+        expiration: number;
+        recipient: `0x${string}`;
+        validatorId: number;
+        validatorContract: `0x${string}`;
+        issuerSignature: `0x${string}`;
+        recipientSignature: `0x${string}`;
+        sealingPair?: {
+            privateKey: string;
+            publicKey: string;
+        } | undefined;
+    };
+    /**
+     * Validate a permit (holistic validation).
+     *
+     * This validates:
+     * - Permit schema (shape + invariants)
+     * - Permit is signed
+     * - Permit is not expired
+     *
+     * For schema-only validation, use `validateSchema(permit)`.
+     */
+    validate: (permit: Permit) => {
+        name: string;
+        type: "self" | "sharing" | "recipient";
+        issuer: `0x${string}`;
+        expiration: number;
+        recipient: `0x${string}`;
+        validatorId: number;
+        validatorContract: `0x${string}`;
+        issuerSignature: `0x${string}`;
+        recipientSignature: `0x${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: PermitHashFields) => 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 signed and not expired
+     */
+    isSignedAndNotExpired: (permit: Permit) => ValidationResult;
+    /**
+     * Assert that permit is signed and not expired
+     */
+    assertSignedAndNotExpired: (permit: Permit) => void;
+    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>;
+    /**
+     * Check if permit passes the on-chain validation
+     */
+    checkValidityOnChain: (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 RecipientPermit as R, 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 PermitType as k, type PermitOf as l, type SelfPermit as m, type SharingPermit as n, type PermitHashFields as o, type Expand as p };