@inco/shield-js 0.0.0-bootstrap.0

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * IncoShield SDK
+ *
+ * TypeScript SDK for interacting with IncoShield contracts.
+ * Works in both browser and Node.js environments.
+ */
+// Binary helpers
+export { bytesToHex, hexToBytes } from './binary.js';
+// On-chain contract interactions
+export * as contracts from './contracts/index.js';
+export { computeErc20AssetId } from './contracts/utils.js';
+// Tagged error types
+export * from './errors.js';
+// Shield covalidator client
+export * from './shield/index.js';
+// Generated EIP-712 ABI structs and digest helpers
+export * as abi from './shield/shield.eip712.gen.js';
+// The UniswapV4 adapter is exposed via the `@inco/shield-js/uniswap` subpath so
+// its ethers/@uniswap peer dependencies stay optional for core consumers.

package/dist/shield/client.d.ts

@@ -0,0 +1,72 @@
+import { type Hex, type TransactionReceipt } from 'viem';
+import { type BundlerClient, type UserOperation } from 'viem/account-abstraction';
+import type { PermissionAttestation, PermissionAttestationRequest, TransferIntentOp, WithdrawalIntentOp } from './shield.eip712.gen.js';
+import type { Balance, DepositAttestation, GetBalanceParams, GetPermissionDetailsParams, GetPermissionsByOwnerParams, GetPermissionsBySpenderParams, PermissionDetails, PermissionInfo, RequestDepositAttestationParams, ShieldConfig } from './types.js';
+import type { ENTRYPOINT_VERSION } from './userop/types.js';
+export declare function computeDomainSeparator(chainId: bigint, verifyingContract: Hex): Hex;
+/** Client interface for interacting with the shield conductor. */
+export interface ShieldClient {
+    issueTransfer(intentOp: TransferIntentOp): Promise<{
+        userOp: UserOperation<typeof ENTRYPOINT_VERSION>;
+    }>;
+    issueWithdraw(intentOp: WithdrawalIntentOp): Promise<{
+        userOp: UserOperation<typeof ENTRYPOINT_VERSION>;
+    }>;
+    /**
+     * Owner-side issuance: sign a `PermissionIntent` and exchange it for a
+     * TEE-signed `PermissionAttestation` the spender presents on every draft.
+     */
+    requestPermissionAttestation(req: PermissionAttestationRequest): Promise<PermissionAttestation>;
+    issueDelegatedTransfer(intentOp: TransferIntentOp, attestation: PermissionAttestation): Promise<{
+        userOp: UserOperation<typeof ENTRYPOINT_VERSION>;
+    }>;
+    /** Settles byte-identically to a direct withdraw on-chain. */
+    issueDelegatedWithdraw(intentOp: WithdrawalIntentOp, attestation: PermissionAttestation): Promise<{
+        userOp: UserOperation<typeof ENTRYPOINT_VERSION>;
+    }>;
+    getBalance(params: GetBalanceParams): Promise<Balance>;
+    revokeOne(params: {
+        permissionId: Hex;
+    }): Promise<{
+        userOp: UserOperation<typeof ENTRYPOINT_VERSION>;
+    }>;
+    revokeAll(): Promise<{
+        userOp: UserOperation<typeof ENTRYPOINT_VERSION>;
+    }>;
+    requestDepositAttestation(params: RequestDepositAttestationParams): Promise<DepositAttestation>;
+    getPermissionsByOwner(params: GetPermissionsByOwnerParams): Promise<PermissionInfo[]>;
+    getPermissionsBySpender(params: GetPermissionsBySpenderParams): Promise<PermissionInfo[]>;
+    getPermissionDetails(params: GetPermissionDetailsParams): Promise<PermissionDetails>;
+    getOwnerGeneration(): Promise<bigint>;
+    /** Submit a UserOp through a bundler */
+    submitUserOp(userOp: UserOperation<typeof ENTRYPOINT_VERSION>, params: SubmitUserOpParams): Promise<{
+        receipt: TransactionReceipt;
+    }>;
+}
+/**
+ * Create a client for the shield covalidator.
+ *
+ * @example
+ * ```ts
+ * import { createShieldClient } from "@inco/shield-js";
+ * import { createConnectTransport } from "@connectrpc/connect-web";
+ * import { privateKeyToAccount } from "viem/accounts";
+ *
+ * const transport = createConnectTransport({ baseUrl: "http://localhost:50051" });
+ * const signer = privateKeyToAccount("0x...");
+ *
+ * const client = createShieldClient({
+ *   transport,
+ *   chainId: BigInt("<your-chain-id>"),
+ *   shieldAddress: "0x...",
+ *   signer,
+ * });
+ *
+ * const balance = await client.getBalance({ address: signer.address, assetId: "0x..." });
+ * ```
+ */
+export declare function createShieldClient(config: ShieldConfig): Promise<ShieldClient>;
+type SubmitUserOpParams = {
+    bundlerClient: BundlerClient;
+};
+export {};

package/dist/shield/client.js

@@ -0,0 +1,136 @@
+import { createClient } from '@connectrpc/connect';
+import { createPublicClient, encodeAbiParameters, http, keccak256, toBytes, } from 'viem';
+import { createBundlerClient, } from 'viem/account-abstraction';
+import { MissingWalletAccount, ShieldError } from '../errors.js';
+import { ConductorService } from '../generated/inco/shield/v2/conductor_connect.js';
+import { deserializePublicKey } from './encryption.js';
+import { getBalance, getOwnerGeneration, getPermissionDetails, getPermissionsByOwner, getPermissionsBySpender, issueDelegatedTransfer, issueDelegatedWithdraw, issueTransfer, issueWithdraw, requestDepositAttestation, requestPermissionAttestation, revokeAll, revokeOne, } from './rpc.js';
+import { getChainFromId } from './utils/chain.js';
+/**
+ * Default bundler URL.
+ * From: https://docs.pimlico.io/references/bundler/public-endpoint#public-endpoint
+ */
+function defaultBundlerUrl(chainId) {
+    return `https://public.pimlico.io/v2/${chainId}/rpc`;
+}
+// ---------------------------------------------------------------------------
+// EIP-712 domain utilities
+// ---------------------------------------------------------------------------
+const EIP712_DOMAIN_TYPEHASH = keccak256(toBytes('EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)'));
+export function computeDomainSeparator(chainId, verifyingContract) {
+    return keccak256(encodeAbiParameters([
+        { type: 'bytes32' },
+        { type: 'bytes32' },
+        { type: 'bytes32' },
+        { type: 'uint256' },
+        { type: 'address' },
+    ], [
+        EIP712_DOMAIN_TYPEHASH,
+        keccak256(toBytes('IncoShield')),
+        keccak256(toBytes('1')),
+        chainId,
+        verifyingContract,
+    ]));
+}
+function isShieldSigner(signer) {
+    return ('address' in signer &&
+        typeof signer.address === 'string' &&
+        'sign' in signer &&
+        typeof signer.sign === 'function' &&
+        !('account' in signer));
+}
+function resolveShieldSigner(signer) {
+    if (isShieldSigner(signer))
+        return signer;
+    const account = signer.account;
+    if (!account)
+        throw new MissingWalletAccount({
+            message: 'WalletClient must have an account',
+        });
+    return {
+        address: account.address,
+        sign: async ({ hash }) => {
+            if ('sign' in account && typeof account.sign === 'function') {
+                return account.sign({ hash });
+            }
+            return signer.signMessage({
+                account,
+                message: { raw: hash },
+            });
+        },
+    };
+}
+/**
+ * Create a client for the shield covalidator.
+ *
+ * @example
+ * ```ts
+ * import { createShieldClient } from "@inco/shield-js";
+ * import { createConnectTransport } from "@connectrpc/connect-web";
+ * import { privateKeyToAccount } from "viem/accounts";
+ *
+ * const transport = createConnectTransport({ baseUrl: "http://localhost:50051" });
+ * const signer = privateKeyToAccount("0x...");
+ *
+ * const client = createShieldClient({
+ *   transport,
+ *   chainId: BigInt("<your-chain-id>"),
+ *   shieldAddress: "0x...",
+ *   signer,
+ * });
+ *
+ * const balance = await client.getBalance({ address: signer.address, assetId: "0x..." });
+ * ```
+ */
+export async function createShieldClient(config) {
+    const chain = getChainFromId(Number(config.chainId));
+    const conductorClient = createClient(ConductorService, config.grpcTransport);
+    const domainSeparator = computeDomainSeparator(config.chainId, config.shieldAddress);
+    let teePublicKey;
+    try {
+        teePublicKey = await deserializePublicKey(config.teePublicKey);
+    }
+    catch (err) {
+        throw new ShieldError({
+            message: `Failed to deserialize TEE public key: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+    const signer = resolveShieldSigner(config.signer);
+    const bundlerUrl = config.bundlerUrl ?? defaultBundlerUrl(Number(config.chainId));
+    const bundlerClient = createBundlerClient({
+        client: createPublicClient({
+            chain,
+            transport: config.viemTransport ?? http(chain.rpcUrls.default.http[0]),
+        }),
+        transport: http(bundlerUrl),
+    });
+    const ctx = { rpc: conductorClient, domainSeparator, signer, teePublicKey };
+    return {
+        issueTransfer: (intentOp) => issueTransfer(ctx, intentOp),
+        issueWithdraw: (intentOp) => issueWithdraw(ctx, intentOp),
+        requestPermissionAttestation: (params) => requestPermissionAttestation(ctx, params),
+        issueDelegatedTransfer: (intentOp, attestation) => issueDelegatedTransfer(ctx, intentOp, attestation),
+        issueDelegatedWithdraw: (intentOp, attestation) => issueDelegatedWithdraw(ctx, intentOp, attestation),
+        getBalance: (params) => getBalance(ctx, params),
+        revokeOne: (params) => revokeOne(ctx, params),
+        revokeAll: () => revokeAll(ctx),
+        requestDepositAttestation: (params) => requestDepositAttestation(ctx, params),
+        getPermissionsByOwner: (params) => getPermissionsByOwner(ctx, params),
+        getPermissionsBySpender: (params) => getPermissionsBySpender(ctx, params),
+        getPermissionDetails: (params) => getPermissionDetails(ctx, params),
+        getOwnerGeneration: () => getOwnerGeneration(ctx),
+        submitUserOp: async (userOp) => {
+            return submitUserOp(userOp, {
+                bundlerClient,
+            });
+        },
+    };
+}
+async function submitUserOp(userOp, params) {
+    const { bundlerClient } = params;
+    const userOpHash = await bundlerClient.sendUserOperation(userOp);
+    const { receipt } = await bundlerClient.waitForUserOperationReceipt({
+        hash: userOpHash,
+    });
+    return { receipt };
+}

package/dist/shield/convert.d.ts

@@ -0,0 +1,18 @@
+import type { UserOperation } from 'viem/account-abstraction';
+import type { UserOp07 as ProtoUserOp07 } from '../generated/inco/shield/v2/drafting_pb.js';
+import { type GetOwnerGenerationResponse, type GetPermissionDetailsResponse, type GetPermissionsResponse, type PermissionInfo as ProtoPermissionInfo } from '../generated/inco/shield/v2/permission_pb.js';
+import type { GetBalanceResponse } from '../generated/inco/shield/v2/query_pb.js';
+import { Uint256 as ProtoUint256 } from '../generated/inco/shield/v2/types_pb.js';
+import type { Balance, PermissionDetails, PermissionInfo } from './types.js';
+import type { ENTRYPOINT_VERSION } from './userop/types.js';
+export declare function bigintToProtoUint256(value: bigint): ProtoUint256;
+export declare function parseBalance(proto: GetBalanceResponse): Balance;
+export declare function parsePermissionInfo(proto: ProtoPermissionInfo): PermissionInfo;
+export declare function parsePermissions(proto: GetPermissionsResponse): PermissionInfo[];
+export declare function parsePermissionDetails(proto: GetPermissionDetailsResponse): PermissionDetails;
+export declare function parseOwnerGeneration(proto: GetOwnerGenerationResponse): bigint;
+/**
+ * Transfer a proto UserOp07 to a viem UserOperation<'0.7'>.
+ * This function throws if the proto UserOp07 is malformed.
+ */
+export declare function parseUserOp07(proto?: ProtoUserOp07): UserOperation<typeof ENTRYPOINT_VERSION>;

package/dist/shield/convert.js

@@ -0,0 +1,152 @@
+import { bytesToHex } from '../binary.js';
+import { MalformedProto } from '../errors.js';
+import { PermissionStatus as ProtoPermissionStatus, } from '../generated/inco/shield/v2/permission_pb.js';
+import { Uint256 as ProtoUint256 } from '../generated/inco/shield/v2/types_pb.js';
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+function requireField(value, name) {
+    if (value === undefined || value === null) {
+        throw new MalformedProto({
+            message: `Missing required proto field: ${name}`,
+            field: name,
+        });
+    }
+    return value;
+}
+function requireFixedBytes(bytes, name, expected) {
+    if (!bytes)
+        throw new Error(`Missing required proto field: ${name}`);
+    if (bytes.length !== expected) {
+        throw new Error(`Malformed proto field ${name}: expected ${expected} bytes, got ${bytes.length}`);
+    }
+    return bytes;
+}
+// ---------------------------------------------------------------------------
+// Uint256 codec — 32-byte big-endian unsigned. Wire shape is a `Uint256`
+// message wrapping exactly 32 bytes; matches Solidity's `uint256` ABI
+// encoding.
+// ---------------------------------------------------------------------------
+const UINT256_BYTES = 32;
+const UINT256_MAX = 1n << 256n;
+function bigintToUint256BEBytes(value) {
+    if (value < 0n || value >= UINT256_MAX) {
+        throw new Error(`Value out of uint256 range: ${value}`);
+    }
+    const buf = new Uint8Array(UINT256_BYTES);
+    let remaining = value;
+    for (let i = UINT256_BYTES - 1; i >= 0; i--) {
+        buf[i] = Number(remaining & 0xffn);
+        remaining >>= 8n;
+    }
+    return buf;
+}
+function uint256BEBytesToBigint(bytes) {
+    let result = 0n;
+    for (const byte of bytes) {
+        result = (result << 8n) | BigInt(byte);
+    }
+    return result;
+}
+export function bigintToProtoUint256(value) {
+    return new ProtoUint256({
+        value: new Uint8Array(bigintToUint256BEBytes(value)),
+    });
+}
+function requireUint256(proto, name) {
+    const bytes = requireFixedBytes(proto?.value, name, UINT256_BYTES);
+    return uint256BEBytesToBigint(bytes);
+}
+// ---------------------------------------------------------------------------
+// Parsers (proto → SDK types)
+// ---------------------------------------------------------------------------
+export function parseBalance(proto) {
+    return {
+        confirmed: requireUint256(proto.confirmedBalance, 'GetBalanceResponse.confirmed_balance'),
+        pending: requireUint256(proto.pendingBalance, 'GetBalanceResponse.pending_balance'),
+        available: requireUint256(proto.availableBalance, 'GetBalanceResponse.available_balance'),
+    };
+}
+function parseProtoPermissionStatus(proto) {
+    switch (proto) {
+        case ProtoPermissionStatus.ACTIVE:
+            return 'active';
+        case ProtoPermissionStatus.NOT_YET_ACTIVE:
+            return 'not_yet_active';
+        case ProtoPermissionStatus.EXPIRED:
+            return 'expired';
+        case ProtoPermissionStatus.REVOKED:
+            return 'revoked';
+        case ProtoPermissionStatus.GENERATION_REVOKED:
+            return 'generation_revoked';
+        default:
+            return 'unspecified';
+    }
+}
+export function parsePermissionInfo(proto) {
+    return {
+        permissionId: bytesToHex(requireFixedBytes(proto.permissionId?.value, 'permission.permission_id', 32)),
+        owner: bytesToHex(requireFixedBytes(proto.owner?.value, 'permission.owner', 20)),
+        spender: bytesToHex(requireFixedBytes(proto.spender?.value, 'permission.spender', 20)),
+        assetId: bytesToHex(requireFixedBytes(proto.assetId?.value, 'permission.asset_id', 32)),
+        allowance: requireUint256(proto.allowance, 'permission.allowance'),
+        start: BigInt(proto.start),
+        end: BigInt(proto.end),
+        period: BigInt(proto.period),
+        agreementHash: bytesToHex(requireFixedBytes(proto.agreementHash?.value, 'permission.agreement_hash', 32)),
+        spentInCurrentPeriod: requireUint256(proto.spentInCurrentPeriod, 'permission.spent_in_current_period'),
+        availableAllowance: requireUint256(proto.availableAllowance, 'permission.available_allowance'),
+        status: parseProtoPermissionStatus(proto.status),
+    };
+}
+export function parsePermissions(proto) {
+    return proto.permissions.map(parsePermissionInfo);
+}
+export function parsePermissionDetails(proto) {
+    return {
+        permission: parsePermissionInfo(requireField(proto.permission, 'GetPermissionDetailsResponse.permission')),
+        found: proto.found,
+    };
+}
+export function parseOwnerGeneration(proto) {
+    return BigInt(proto.generation);
+}
+/**
+ * Transfer a proto UserOp07 to a viem UserOperation<'0.7'>.
+ * This function throws if the proto UserOp07 is malformed.
+ */
+export function parseUserOp07(proto) {
+    if (!proto) {
+        throw new MalformedProto({
+            message: 'Missing required proto field: user_op',
+            field: 'user_op',
+        });
+    }
+    return {
+        sender: bytesToHex(requireFixedBytes(proto.sender?.value, 'user_op.sender', 20)),
+        nonce: requireUint256(proto.nonce, 'user_op.nonce'),
+        callData: bytesToHex(proto.callData),
+        callGasLimit: requireUint256(proto.callGasLimit, 'user_op.call_gas_limit'),
+        verificationGasLimit: requireUint256(proto.verificationGasLimit, 'user_op.verification_gas_limit'),
+        preVerificationGas: requireUint256(proto.preVerificationGas, 'user_op.pre_verification_gas'),
+        maxFeePerGas: requireUint256(proto.maxFeePerGas, 'user_op.max_fee_per_gas'),
+        maxPriorityFeePerGas: requireUint256(proto.maxPriorityFeePerGas, 'user_op.max_priority_fee_per_gas'),
+        signature: bytesToHex(proto.signature),
+        factory: proto.factory
+            ? bytesToHex(requireFixedBytes(proto.factory.value, 'user_op.factory', 20))
+            : undefined,
+        factoryData: proto.factoryData ? bytesToHex(proto.factoryData) : undefined,
+        paymaster: proto.paymaster
+            ? bytesToHex(requireFixedBytes(proto.paymaster.value, 'user_op.paymaster', 20))
+            : undefined,
+        paymasterData: proto.paymasterData
+            ? bytesToHex(proto.paymasterData)
+            : undefined,
+        paymasterVerificationGasLimit: proto.paymasterVerificationGasLimit
+            ? requireUint256(proto.paymasterVerificationGasLimit, 'user_op.paymaster_verification_gas_limit')
+            : undefined,
+        paymasterPostOpGasLimit: proto.paymasterPostOpGasLimit
+            ? requireUint256(proto.paymasterPostOpGasLimit, 'user_op.paymaster_post_op_gas_limit')
+            : undefined,
+    };
+}

package/dist/shield/encryption.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Encryption primitives for the Shield SDK:
+ *  - HPKE envelope sealing/opening (X-Wing KEM + ChaCha20Poly1305) for messages to the TEE.
+ *  - Standalone symmetric AEAD (AES-GCM-SIV) seal/open for keys negotiated
+ *    out-of-band (e.g. `response_key` from authenticated queries) or for
+ *    deterministic, quorum-shared encryption derived from a trace hash.
+ *
+ * HPKE wire format: [encappedKey || ciphertext (ChaCha20Poly1305)]
+ */
+/** AEAD key size in bytes, sourced from the cipher suite. */
+export declare const AEAD_KEY_SIZE: number;
+/** AEAD nonce size in bytes, sourced from the cipher suite. */
+export declare const AEAD_NONCE_SIZE: number;
+/** AEAD authentication tag size in bytes (appended to ciphertext). */
+export declare const AEAD_TAG_SIZE: number;
+/**
+ * Wire size of an `encryptCheque` blob: `[nonce || aead(plaintext)]`,
+ * where `aead` appends an authentication tag.
+ */
+export declare function chequeBlobSize(plaintextByteLength: number): number;
+/** Raw byte representation of a keypair for persistence or transport. */
+export interface SerializedKeyPair {
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+}
+/** Generate a fresh X-Wing keypair. */
+export declare function generateKeyPair(): Promise<CryptoKeyPair>;
+/** X-Wing IKM size in bytes — required input length for {@link deriveKeyPair}. */
+export declare const HPKE_IKM_SIZE = 32;
+/**
+ * Derive an X-Wing keypair deterministically from a 32-byte IKM. Used by
+ * the enclave to derive its long-lived HPKE keypair from
+ * `sharedEnclaveSecretSeed` so all quorum members agree on the recipient
+ * public key.
+ *
+ * Throws {@link HpkeKeyPairDerivationFailure} on wrong-length IKM or
+ * underlying KEM failure. IKM length is validated up front (matching the
+ * length guards in {@link sealAead} / {@link openAead}) so the diagnostic
+ * doesn't depend on the upstream library's exception shape.
+ */
+export declare function deriveKeyPair(ikm: Uint8Array): Promise<CryptoKeyPair>;
+/** Serialize a {@link CryptoKeyPair} to raw bytes. */
+export declare function serializeKeyPair(kp: CryptoKeyPair): Promise<SerializedKeyPair>;
+/** Deserialize raw bytes back into a {@link CryptoKeyPair}. */
+export declare function deserializeKeyPair(serialized: SerializedKeyPair): Promise<CryptoKeyPair>;
+/** Serialize a public key to raw bytes. */
+export declare function serializePublicKey(key: CryptoKey): Promise<Uint8Array>;
+/** Deserialize a public key from raw bytes. */
+export declare function deserializePublicKey(bytes: Uint8Array): Promise<CryptoKey>;
+/**
+ * Encrypt plaintext to the recipient's public key using HPKE.
+ *
+ * @returns A single buffer in wire format: `[encappedKey || ciphertext]`.
+ */
+export declare function sealEnvelope(recipientPublicKey: CryptoKey, plaintext: Uint8Array): Promise<Uint8Array>;
+/**
+ * Decrypt an envelope using the recipient's private key.
+ *
+ * @param envelope - Wire format `[encappedKey || ciphertext]` as returned by {@link sealEnvelope}.
+ * @throws If the envelope is too short or decryption fails.
+ */
+export declare function openEnvelope(recipientPrivateKey: CryptoKey, envelope: Uint8Array): Promise<Uint8Array>;
+/**
+ * Encrypt plaintext with a 32-byte symmetric key using AES-GCM-SIV.
+ *
+ * The nonce is caller-provided and required. Callers that need
+ * deterministic ciphertext (e.g. cheque-internal encryption that must match
+ * across TEEs in a quorum) derive the nonce deterministically from the
+ * relevant context (trace hash + slot label). Callers that don't (e.g. the
+ * TEE→client response path) generate a fresh random nonce.
+ *
+ * AES-GCM-SIV is misuse-resistant: nonce reuse with the same plaintext
+ * leaks plaintext equality but does not catastrophically break the cipher.
+ *
+ * @param key - 32-byte symmetric key.
+ * @param nonce - 12-byte nonce.
+ * @param plaintext - Bytes to encrypt.
+ * @returns ciphertext (with appended GCM authentication tag).
+ */
+export declare function sealAead(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;
+/**
+ * Decrypt ciphertext with a 32-byte symmetric key using AES-GCM-SIV.
+ *
+ * @throws If authentication fails or key/nonce sizes are wrong.
+ */
+export declare function openAead(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array): Promise<Uint8Array>;

package/dist/shield/encryption.js

@@ -0,0 +1,180 @@
+/**
+ * Encryption primitives for the Shield SDK:
+ *  - HPKE envelope sealing/opening (X-Wing KEM + ChaCha20Poly1305) for messages to the TEE.
+ *  - Standalone symmetric AEAD (AES-GCM-SIV) seal/open for keys negotiated
+ *    out-of-band (e.g. `response_key` from authenticated queries) or for
+ *    deterministic, quorum-shared encryption derived from a trace hash.
+ *
+ * HPKE wire format: [encappedKey || ciphertext (ChaCha20Poly1305)]
+ */
+import { Chacha20Poly1305 } from '@hpke/chacha20poly1305';
+import { CipherSuite, HkdfSha256 } from '@hpke/core';
+import { XWing } from '@hpke/hybridkem-x-wing';
+import { gcmsiv } from '@noble/ciphers/aes';
+import { EncryptionError, HpkeKeyPairDerivationFailure } from '../errors.js';
+const kem = new XWing();
+const chachaPoly = new Chacha20Poly1305();
+const suite = new CipherSuite({
+    kem,
+    kdf: new HkdfSha256(),
+    aead: chachaPoly,
+});
+/** X-Wing KEM encapsulated key size in bytes. */
+const ENCAPPED_KEY_SIZE = kem.encSize;
+/** AEAD key size in bytes, sourced from the cipher suite. */
+export const AEAD_KEY_SIZE = chachaPoly.keySize;
+/** AEAD nonce size in bytes, sourced from the cipher suite. */
+export const AEAD_NONCE_SIZE = chachaPoly.nonceSize;
+/** AEAD authentication tag size in bytes (appended to ciphertext). */
+export const AEAD_TAG_SIZE = chachaPoly.tagSize;
+/**
+ * Wire size of an `encryptCheque` blob: `[nonce || aead(plaintext)]`,
+ * where `aead` appends an authentication tag.
+ */
+export function chequeBlobSize(plaintextByteLength) {
+    return AEAD_NONCE_SIZE + plaintextByteLength + AEAD_TAG_SIZE;
+}
+/** Generate a fresh X-Wing keypair. */
+export async function generateKeyPair() {
+    return suite.kem.generateKeyPair();
+}
+/** X-Wing IKM size in bytes — required input length for {@link deriveKeyPair}. */
+export const HPKE_IKM_SIZE = 32;
+/**
+ * Derive an X-Wing keypair deterministically from a 32-byte IKM. Used by
+ * the enclave to derive its long-lived HPKE keypair from
+ * `sharedEnclaveSecretSeed` so all quorum members agree on the recipient
+ * public key.
+ *
+ * Throws {@link HpkeKeyPairDerivationFailure} on wrong-length IKM or
+ * underlying KEM failure. IKM length is validated up front (matching the
+ * length guards in {@link sealAead} / {@link openAead}) so the diagnostic
+ * doesn't depend on the upstream library's exception shape.
+ */
+export async function deriveKeyPair(ikm) {
+    if (ikm.byteLength !== HPKE_IKM_SIZE) {
+        throw new HpkeKeyPairDerivationFailure({
+            message: `deriveKeyPair: ikm must be ${HPKE_IKM_SIZE} bytes, got ${ikm.byteLength}`,
+        });
+    }
+    try {
+        return await suite.kem.deriveKeyPair(ikm);
+    }
+    catch (err) {
+        throw new HpkeKeyPairDerivationFailure({
+            message: `X-Wing keypair derivation failed: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+}
+/** Serialize a {@link CryptoKeyPair} to raw bytes. */
+export async function serializeKeyPair(kp) {
+    const [pub, priv] = await Promise.all([
+        suite.kem.serializePublicKey(kp.publicKey),
+        suite.kem.serializePrivateKey(kp.privateKey),
+    ]);
+    return {
+        publicKey: new Uint8Array(pub),
+        privateKey: new Uint8Array(priv),
+    };
+}
+/** Deserialize raw bytes back into a {@link CryptoKeyPair}. */
+export async function deserializeKeyPair(serialized) {
+    const [publicKey, privateKey] = await Promise.all([
+        suite.kem.deserializePublicKey(serialized.publicKey),
+        suite.kem.deserializePrivateKey(serialized.privateKey),
+    ]);
+    return { publicKey, privateKey };
+}
+/** Serialize a public key to raw bytes. */
+export async function serializePublicKey(key) {
+    return new Uint8Array(await suite.kem.serializePublicKey(key));
+}
+/** Deserialize a public key from raw bytes. */
+export async function deserializePublicKey(bytes) {
+    return suite.kem.deserializePublicKey(bytes);
+}
+/**
+ * Encrypt plaintext to the recipient's public key using HPKE.
+ *
+ * @returns A single buffer in wire format: `[encappedKey || ciphertext]`.
+ */
+export async function sealEnvelope(recipientPublicKey, plaintext) {
+    const sender = await suite.createSenderContext({ recipientPublicKey });
+    const ciphertext = await sender.seal(plaintext);
+    const ct = new Uint8Array(ciphertext);
+    const result = new Uint8Array(sender.enc.byteLength + ct.byteLength);
+    result.set(new Uint8Array(sender.enc), 0);
+    result.set(ct, sender.enc.byteLength);
+    return result;
+}
+/**
+ * Decrypt an envelope using the recipient's private key.
+ *
+ * @param envelope - Wire format `[encappedKey || ciphertext]` as returned by {@link sealEnvelope}.
+ * @throws If the envelope is too short or decryption fails.
+ */
+export async function openEnvelope(recipientPrivateKey, envelope) {
+    if (envelope.byteLength <= ENCAPPED_KEY_SIZE) {
+        throw new EncryptionError({
+            message: `Envelope too short: expected > ${ENCAPPED_KEY_SIZE} bytes, got ${envelope.byteLength}`,
+        });
+    }
+    const encappedKey = envelope.slice(0, ENCAPPED_KEY_SIZE);
+    const ciphertext = envelope.slice(ENCAPPED_KEY_SIZE);
+    const recipient = await suite.createRecipientContext({
+        recipientKey: recipientPrivateKey,
+        enc: encappedKey,
+    });
+    const plaintext = await recipient.open(ciphertext);
+    return new Uint8Array(plaintext);
+}
+/**
+ * Encrypt plaintext with a 32-byte symmetric key using AES-GCM-SIV.
+ *
+ * The nonce is caller-provided and required. Callers that need
+ * deterministic ciphertext (e.g. cheque-internal encryption that must match
+ * across TEEs in a quorum) derive the nonce deterministically from the
+ * relevant context (trace hash + slot label). Callers that don't (e.g. the
+ * TEE→client response path) generate a fresh random nonce.
+ *
+ * AES-GCM-SIV is misuse-resistant: nonce reuse with the same plaintext
+ * leaks plaintext equality but does not catastrophically break the cipher.
+ *
+ * @param key - 32-byte symmetric key.
+ * @param nonce - 12-byte nonce.
+ * @param plaintext - Bytes to encrypt.
+ * @returns ciphertext (with appended GCM authentication tag).
+ */
+export async function sealAead(key, nonce, plaintext) {
+    if (key.byteLength !== AEAD_KEY_SIZE) {
+        throw new EncryptionError({
+            message: `sealAead: key must be ${AEAD_KEY_SIZE} bytes, got ${key.byteLength}`,
+        });
+    }
+    if (nonce.byteLength !== AEAD_NONCE_SIZE) {
+        throw new EncryptionError({
+            message: `sealAead: nonce must be ${AEAD_NONCE_SIZE} bytes, got ${nonce.byteLength}`,
+        });
+    }
+    const cipher = gcmsiv(key, nonce);
+    return cipher.encrypt(plaintext);
+}
+/**
+ * Decrypt ciphertext with a 32-byte symmetric key using AES-GCM-SIV.
+ *
+ * @throws If authentication fails or key/nonce sizes are wrong.
+ */
+export async function openAead(key, nonce, ciphertext) {
+    if (key.byteLength !== AEAD_KEY_SIZE) {
+        throw new EncryptionError({
+            message: `openAead: key must be ${AEAD_KEY_SIZE} bytes, got ${key.byteLength}`,
+        });
+    }
+    if (nonce.byteLength !== AEAD_NONCE_SIZE) {
+        throw new EncryptionError({
+            message: `openAead: nonce must be ${AEAD_NONCE_SIZE} bytes, got ${nonce.byteLength}`,
+        });
+    }
+    const cipher = gcmsiv(key, nonce);
+    return cipher.decrypt(ciphertext);
+}