@cofhe/sdk 0.6.1 → 0.7.1

package/dist/acp-Wi6isVQI.d.ts

@@ -0,0 +1,407 @@
+import { Hex, PublicClient, WalletClient } from 'viem';
+
+type EthEncryptedData = {
+    data: Uint8Array;
+    public_key: Uint8Array;
+    nonce: Uint8Array;
+};
+/**
+ * An X25519 sealing keypair, both halves 0x-prefixed 32-byte hex.
+ * The public key travels in the ACP (`sealingKey`); the private key never
+ * leaves the client (`sealingPrivateKey`).
+ */
+type SealingKeyPair = {
+    privateKey: Hex;
+    publicKey: Hex;
+};
+/**
+ * Generates a new sealing keypair. A sealing key is used to encrypt data such
+ * that it can only be unsealed (decrypted) by the owner of the corresponding
+ * private key.
+ */
+declare const GenerateSealingKey: () => SealingKeyPair;
+/**
+ * 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 (with or without 0x prefix).
+ * @returns {EthEncryptedData} - The encrypted message.
+ * @throws Will throw if the provided publicKey or value do not meet defined preconditions.
+ */
+declare const seal: (value: bigint | number, publicKey: string) => EthEncryptedData;
+/**
+ * Unseal (decrypt) data with a sealing private key (with or without 0x prefix).
+ * The ephemeral public key travels inside the payload, so the private key alone suffices.
+ */
+declare const unsealWithPrivateKey: (privateKey: string, parsedData: EthEncryptedData) => bigint;
+
+/**
+ * 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;
+};
+
+/**
+ * The client-side-only component of an ACP — never leaves the client.
+ */
+interface ACPPrivate {
+    /**
+     * Stable hash of relevant acp data, used as key in storage
+     */
+    hash: string;
+    /**
+     * Name for this acp, for organization and UI usage, not included in signature.
+     */
+    name: string;
+    /**
+     * The type of the ACP (self / sharing / recipient)
+     * (self) ACP that will be signed and used by the issuer
+     * (sharing) ACP that is signed by the issuer, but intended to be shared with recipient
+     * (recipient) ACP that has been received, and signed by the recipient
+     */
+    type: 'self' | 'sharing' | 'recipient';
+    /**
+     * The private half of the sealing keypair — used to unseal returned data.
+     * `sealingKey` (in the public component) is the corresponding public key.
+     * Never leaves the client.
+     */
+    sealingPrivateKey: Hex;
+    /**
+     * EIP712 domain used to sign this acp.
+     * Should not be set manually, included in metadata as part of serialization flows.
+     */
+    _signedDomain?: EIP712Domain;
+}
+/**
+ * The public component of an ACP — the signed struct passed on-chain / to the
+ * decryption backend to grant encrypted data access. Produced by `getPublic()`.
+ */
+interface ACPPublic {
+    /**
+     * (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;
+    /**
+     * (revocation) Opaque data interpreted by `revokerContract` — the default
+     * revoker interprets it as the acp's creation timestamp.
+     * ** optional, use `0` to disable **
+     */
+    revokerData: number;
+    /**
+     * (revocation) The contract to query to determine permission validity
+     * ** optional, use `address(0)` to disable **
+     */
+    revokerContract: Hex;
+    /**
+     * (scope) Scope discriminator — exactly one scope mode per ACP (see ACPScope).
+     * Global: all of `issuer`s values (arrays empty). Contract: values readable by
+     * `contracts`. Handles: the listed `handles` only.
+     */
+    scope: number;
+    /**
+     * (scope) Grants access to `issuer`s values readable by any of these contracts.
+     * Checked on-chain as an intersection with the ACL's persisted allowances.
+     */
+    contracts: Hex[];
+    /**
+     * (scope) Grants access to these specific ciphertext handles (bytes32 hex)
+     */
+    handles: Hex[];
+    /**
+     * (base) The public half of the sealing keypair — used to re-encrypt `issuer`s confidential data
+     *   (non-sharing) Populated by `issuer`
+     *   (sharing)     Populated by `recipient`
+     */
+    sealingKey: Hex;
+    /**
+     * (base) `signTypedData` signature created by `issuer`.
+     * (base) Shared- and Self- permissions differ in signature format: (`sealingKey` absent in shared signature)
+     */
+    issuerSignature: Hex;
+    /**
+     * (sharing) `signTypedData` signature created by `recipient`
+     * ** required for shared acps **
+     */
+    recipientSignature: Hex;
+}
+/**
+ * Core ACP (Access Control Permission) type — immutable design for React compatibility.
+ * The union of the private (client-only) and public (signed) components.
+ */
+type ACP = Expand<ACPPrivate & ACPPublic>;
+/**
+ * ACP discriminant helpers
+ */
+type ACPType = ACP['type'];
+/**
+ * Utility type to narrow an ACP to a specific discriminant.
+ *
+ * Note: this only narrows the `type` field. Runtime/validation constraints
+ * (e.g. recipient == zeroAddress for self acps) are enforced elsewhere.
+ */
+type ACPOf<T extends ACPType> = Expand<Omit<ACP, 'type'> & {
+    type: T;
+}>;
+type SelfACP = ACPOf<'self'>;
+type SharingACP = ACPOf<'sharing'>;
+type RecipientACP = ACPOf<'recipient'>;
+/**
+ * Optional additional metadata of an ACP
+ * Can be passed into the constructor, but not necessary
+ * Useful for deserialization
+ */
+interface ACPMetadata {
+    /**
+     * EIP712 domain used to sign this acp.
+     * Should not be set manually, included in metadata as part of serialization flows.
+     */
+    _signedDomain?: EIP712Domain;
+}
+/**
+ * Utility types for acp creation
+ */
+/**
+ * Scope fields shared by all acp creation options.
+ * When any scope array is populated and `global` is not explicitly set,
+ * `global` defaults to false (narrowest matching scope); with no scope
+ * arrays it defaults to true (V2 behavior).
+ */
+declare const ACPScope: {
+    readonly Global: 0;
+    readonly Contract: 1;
+    readonly Handles: 2;
+};
+type ACPScopeOptions = {
+    scope?: number;
+    contracts?: Hex[];
+    handles?: Hex[];
+};
+type CreateSelfACPOptions = ACPScopeOptions & {
+    type?: 'self';
+    issuer: string;
+    name?: string;
+    expiration?: number;
+    revokerData?: number;
+    revokerContract?: string;
+};
+type CreateSharingACPOptions = ACPScopeOptions & {
+    type?: 'sharing';
+    issuer: string;
+    recipient: string;
+    name?: string;
+    expiration?: number;
+    revokerData?: number;
+    revokerContract?: string;
+};
+type ImportSharedACPOptions = ACPScopeOptions & {
+    type?: 'sharing';
+    issuer: string;
+    recipient: string;
+    issuerSignature: string;
+    name?: string;
+    expiration: number;
+    revokerData?: number;
+    revokerContract?: string;
+};
+/** An ACP is plain JSON-serializable data — the serialized form is the ACP itself. */
+type SerializedACP = ACP;
+/**
+ * The share payload produced by `ACPUtils.export()` — the full public component
+ * with `sealingKey`/`recipientSignature` left for the recipient to fill, plus
+ * the display name and acp type. Fixed shape: every field is always present
+ * (zero-values instead of omissions), so importers can parse a single schema.
+ * Mirrors the on-chain sharing payload struct field-for-field.
+ */
+type SharedACP = Expand<Omit<ACPPublic, 'sealingKey' | 'recipientSignature'> & {
+    name: string;
+    type: 'sharing';
+}>;
+/**
+ * A share read back from the on-chain ACPShareRegistry: the posted payload
+ * (SharedACP minus the client-side name/type) plus its registry id.
+ */
+type IncomingShare = Expand<Omit<SharedACP, 'name' | 'type'> & {
+    shareId: Hex;
+}>;
+/**
+ * A type representing the acp fields that are used to generate the hash
+ */
+type ACPHashFields = Pick<ACP, 'type' | 'issuer' | 'expiration' | 'recipient' | 'revokerData' | 'revokerContract' | 'scope' | 'contracts' | 'handles'>;
+/**
+ * Validation result type
+ */
+interface ValidationResult {
+    valid: boolean;
+    error: 'invalid-schema' | 'expired' | 'not-signed' | null;
+}
+/**
+ * Signature types for EIP712 signing
+ */
+type ACPSignaturePrimaryType = 'ACPIssuerSelf' | 'ACPIssuerShared' | 'ACPRecipient';
+type Expand<T> = T extends infer O ? {
+    [K in keyof O]: O[K];
+} : never;
+
+/**
+ * Main ACP utilities - functional approach for React compatibility
+ */
+declare const ACPUtils: {
+    /**
+     * Create a self acp for personal use
+     */
+    createSelf: (options: CreateSelfACPOptions) => SelfACP;
+    /**
+     * Create a sharing acp to be shared with another user
+     */
+    createSharing: (options: CreateSharingACPOptions) => SharingACP;
+    /**
+     * Import a shared acp from various input formats
+     */
+    importShared: (options: ImportSharedACPOptions | string) => RecipientACP;
+    /**
+     * Sign an ACP with the provided wallet client
+     */
+    sign: <T extends ACP>(acp: T, publicClient: PublicClient, walletClient: WalletClient) => Promise<T>;
+    /**
+     * Create and sign a self acp in one operation
+     */
+    createSelfAndSign: (options: CreateSelfACPOptions, publicClient: PublicClient, walletClient: WalletClient) => Promise<SelfACP>;
+    /**
+     * Create and sign a sharing acp in one operation
+     */
+    createSharingAndSign: (options: CreateSharingACPOptions, publicClient: PublicClient, walletClient: WalletClient) => Promise<SharingACP>;
+    /**
+     * Import and sign a shared acp in one operation from various input formats
+     */
+    importSharedAndSign: (options: ImportSharedACPOptions | string, publicClient: PublicClient, walletClient: WalletClient) => Promise<RecipientACP>;
+    /**
+     * Deserialize an ACP from serialized data
+     */
+    deserialize: (data: SerializedACP) => ACP;
+    /**
+     * Serialize an ACP for storage
+     */
+    serialize: (acp: ACP) => SerializedACP;
+    /**
+     * Validate an ACP (schema-level validation)
+     */
+    validateSchema: (acp: ACP) => {
+        name: string;
+        type: "self" | "sharing" | "recipient";
+        issuer: `0x${string}`;
+        expiration: number;
+        recipient: `0x${string}`;
+        revokerData: number;
+        revokerContract: `0x${string}`;
+        scope: number;
+        contracts: `0x${string}`[];
+        handles: `0x${string}`[];
+        issuerSignature: `0x${string}`;
+        recipientSignature: `0x${string}`;
+        sealingPrivateKey?: string | undefined;
+        sealingKey?: string | undefined;
+    };
+    /**
+     * Validate an ACP (holistic validation).
+     *
+     * This validates:
+     * - ACP schema (shape + invariants)
+     * - ACP is signed
+     * - ACP is not expired
+     *
+     * For schema-only validation, use `validateSchema(acp)`.
+     */
+    validate: (acp: ACP) => {
+        name: string;
+        type: "self" | "sharing" | "recipient";
+        issuer: `0x${string}`;
+        expiration: number;
+        recipient: `0x${string}`;
+        revokerData: number;
+        revokerContract: `0x${string}`;
+        scope: number;
+        contracts: `0x${string}`[];
+        handles: `0x${string}`[];
+        issuerSignature: `0x${string}`;
+        recipientSignature: `0x${string}`;
+        sealingPrivateKey?: string | undefined;
+        sealingKey?: string | undefined;
+    };
+    /**
+     * Get the public component of an ACP — the signed struct sent on-chain / to the decryption backend.
+     * Strips the private component (hash, name, type, sealing pair).
+     */
+    getPublic: (acp: ACP, skipValidation?: boolean) => ACPPublic;
+    /**
+     * Get a stable hash for the acp (used as key in storage)
+     */
+    getHash: (acp: ACPHashFields) => string;
+    /**
+     * Export acp data for sharing (strips the private component).
+     * Fixed `SharedACP` shape — every field always present, aligned with
+     * `ACPPublic` and the on-chain sharing payload.
+     */
+    export: (acp: ACP) => string;
+    /**
+     * Unseal encrypted data using the acp's sealing key
+     */
+    unseal: (acp: ACP, ciphertext: EthEncryptedData) => bigint;
+    /**
+     * Check if acp is expired
+     */
+    isExpired: (acp: ACP) => boolean;
+    /**
+     * Check if acp is signed
+     */
+    isSigned: (acp: ACP) => boolean;
+    /**
+     * Check if acp is signed and not expired
+     */
+    isSignedAndNotExpired: (acp: ACP) => ValidationResult;
+    /**
+     * Assert that acp is signed and not expired
+     */
+    assertSignedAndNotExpired: (acp: ACP) => void;
+    isValid: (acp: ACP) => ValidationResult;
+    /**
+     * Update acp name (returns new acp instance)
+     */
+    updateName: (acp: ACP, name: string) => ACP;
+    /**
+     * Fetch EIP712 domain from the blockchain
+     */
+    fetchEIP712Domain: (publicClient: PublicClient) => Promise<EIP712Domain>;
+    /**
+     * Check if acp's signed domain matches the provided domain
+     */
+    matchesDomain: (acp: ACP, domain: EIP712Domain) => boolean;
+    /**
+     * Check if acp's signed domain is valid for the current chain
+     */
+    checkSignedDomainValid: (acp: ACP, publicClient: PublicClient) => Promise<boolean>;
+    /**
+     * Check if acp passes the on-chain validation
+     */
+    checkValidityOnChain: (acp: ACP, publicClient: PublicClient) => Promise<boolean>;
+};
+
+export { type ACP as A, type CreateSelfACPOptions as C, type EIP712Types as E, GenerateSealingKey as G, type ImportSharedACPOptions as I, type RecipientACP as R, type SerializedACP as S, type ValidationResult as V, type ACPPublic as a, type ACPSignaturePrimaryType as b, type EIP712Message as c, type CreateSharingACPOptions as d, type ACPMetadata as e, type SharedACP as f, type IncomingShare as g, type EIP712Domain as h, ACPUtils as i, type SealingKeyPair as j, type EthEncryptedData as k, type EIP712Type as l, type ACPPrivate as m, type ACPType as n, type ACPOf as o, type SelfACP as p, type SharingACP as q, ACPScope as r, seal as s, type ACPScopeOptions as t, unsealWithPrivateKey as u, type ACPHashFields as v, type Expand as w };