@cofhe/sdk 0.6.0 → 0.7.0

package/core/client.ts

@@ -1,16 +1,16 @@
-import type { CreateSelfPermitOptions, CreateSharingPermitOptions, ImportSharedPermitOptions } from '@/permits';
+import type { CreateSelfACPOptions, CreateSharingACPOptions, ImportSharedACPOptions } from '@/acps';
 
 import { createStore } from 'zustand/vanilla';
 import { type Hex, type PublicClient, type WalletClient } from 'viem';
 import { CofheError, CofheErrorCode } from './error.js';
-import { EncryptInputsBuilder } from './encrypt/encryptInputsBuilder.js';
+import { EncryptInputsBuilder, type EncryptInputsBuilderUnset } from './encrypt/encryptInputsBuilder.js';
 import { createKeysStore } from './keyStore.js';
-import { permits } from './permits.js';
+import { acps } from './acps.js';
 import { DecryptForViewBuilder } from './decrypt/decryptForViewBuilder.js';
 import { DecryptForTxBuilder, type DecryptForTxBuilderUnset } from './decrypt/decryptForTxBuilder.js';
 import { verifyDecryptResult as verifyDecryptResultStandalone } from './decrypt/verifyDecryptResult.js';
 import { getPublicClientChainID, getWalletClientAccount } from './utils.js';
-import type { CofheClientConnectionState, CofheClientParams, CofheClient, CofheClientPermits } from './clientTypes.js';
+import type { CofheClientConnectionState, CofheClientParams, CofheClient, CofheClientACPs } from './clientTypes.js';
 import type { EncryptableItem, FheTypes } from './types.js';
 import type { CofheConfig } from './config.js';
 
@@ -48,7 +48,23 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
     connectStore.setState((state) => ({ ...state, ...partial }));
   };
 
-  // Called before any operation, throws of connection not yet established
+  // Share registry resolution: explicit `acp.sharingRegistry` config wins,
+  // otherwise the address the chain's ACL serves.
+  const _resolveSharingRegistry = async (publicClient: PublicClient, chainId: number): Promise<`0x${string}`> => {
+    const configured = opts.config.acp?.sharingRegistry?.[chainId];
+    if (configured != null) return configured;
+    const registry = (await acps.getAclServedAddresses(publicClient, chainId)).shareRegistry;
+    if (registry == null) {
+      throw new CofheError({
+        code: CofheErrorCode.MissingConfig,
+        message: `No ACP share registry available for chainId <${chainId}>`,
+        hint: 'The ACL on this chain does not serve a share registry address. Set `acp.sharingRegistry` in the cofhe config to use on-chain sharing.',
+        context: { chainId },
+      });
+    }
+    return registry;
+  };
+
   const _requireConnected = () => {
     const state = connectStore.getState();
     const notConnected =
@@ -122,7 +138,7 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
 
   // CLIENT OPERATIONS
 
-  function encryptInputs<T extends EncryptableItem[]>(inputs: [...T]): EncryptInputsBuilder<[...T]> {
+  function encryptInputs<T extends EncryptableItem[]>(inputs: [...T]): EncryptInputsBuilderUnset<[...T]> {
     const state = connectStore.getState();
 
     return new EncryptInputsBuilder({
@@ -187,7 +203,7 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
     return verifyDecryptResultStandalone(handle, cleartext, signature, publicClient!);
   }
 
-  // PERMITS - Context-aware wrapper
+  // ACPS - Context-aware wrapper
 
   const _getChainIdAndAccount = (chainId?: number, account?: string) => {
     const state = connectStore.getState();
@@ -209,96 +225,177 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
     return { chainId: _chainId, account: _account };
   };
 
-  const clientPermits: CofheClientPermits = {
+  const clientACPs: CofheClientACPs = {
     // Pass through store access
-    getSnapshot: permits.getSnapshot,
-    subscribe: permits.subscribe,
+    getSnapshot: acps.getSnapshot,
+    subscribe: acps.subscribe,
 
     // Creation methods (require connection)
     createSelf: async (
-      options: CreateSelfPermitOptions,
+      options: CreateSelfACPOptions,
       clients?: { publicClient: PublicClient; walletClient: WalletClient }
     ) => {
       _requireConnected();
       const { publicClient, walletClient } = clients ?? connectStore.getState();
-      return permits.createSelf(options, publicClient!, walletClient!);
+      const chainId = await publicClient!.getChainId();
+      return acps.createSelf(
+        await acps.applyACPDefaultsFromChain(options, opts.config.acp, publicClient!, chainId),
+        publicClient!,
+        walletClient!
+      );
     },
 
     createSharing: async (
-      options: CreateSharingPermitOptions,
+      options: CreateSharingACPOptions,
       clients?: { publicClient: PublicClient; walletClient: WalletClient }
     ) => {
       _requireConnected();
       const { publicClient, walletClient } = clients ?? connectStore.getState();
-      return permits.createSharing(options, publicClient!, walletClient!);
+      const chainId = await publicClient!.getChainId();
+      return acps.createSharing(
+        await acps.applyACPDefaultsFromChain(options, opts.config.acp, publicClient!, chainId),
+        publicClient!,
+        walletClient!
+      );
     },
 
     importShared: async (
-      options: ImportSharedPermitOptions | string,
+      options: ImportSharedACPOptions | string,
       clients?: { publicClient: PublicClient; walletClient: WalletClient }
     ) => {
       _requireConnected();
       const { publicClient, walletClient } = clients ?? connectStore.getState();
-      return permits.importShared(options, publicClient!, walletClient!);
+      return acps.importShared(options, publicClient!, walletClient!);
     },
 
     // Get or create methods (require connection)
-    getOrCreateSelfPermit: async (chainId?: number, account?: string, options?: CreateSelfPermitOptions) => {
+    getOrCreateSelfACP: async (chainId?: number, account?: string, options?: CreateSelfACPOptions) => {
       _requireConnected();
       const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
       const { publicClient, walletClient } = connectStore.getState();
-      return permits.getOrCreateSelfPermit(publicClient!, walletClient!, _chainId, _account, options);
+      const optionsWithDefaults = await acps.applyACPDefaultsFromChain(
+        options ?? { issuer: _account, name: 'Autogenerated Self ACP' },
+        opts.config.acp,
+        publicClient!,
+        _chainId
+      );
+      return acps.getOrCreateSelfACP(publicClient!, walletClient!, _chainId, _account, optionsWithDefaults);
     },
 
-    getOrCreateSharingPermit: async (options: CreateSharingPermitOptions, chainId?: number, account?: string) => {
+    getOrCreateSharingACP: async (options: CreateSharingACPOptions, chainId?: number, account?: string) => {
       _requireConnected();
       const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
       const { publicClient, walletClient } = connectStore.getState();
-      return permits.getOrCreateSharingPermit(publicClient!, walletClient!, options, _chainId, _account);
+      return acps.getOrCreateSharingACP(
+        publicClient!,
+        walletClient!,
+        await acps.applyACPDefaultsFromChain(options, opts.config.acp, publicClient!, _chainId),
+        _chainId,
+        _account
+      );
+    },
+
+    // Revocation (require connection)
+    revokeACP: async (acp) => {
+      _requireConnected();
+      const { walletClient } = connectStore.getState();
+      return acps.revokeACP(acp, walletClient!);
+    },
+
+    revokeAllACPs: async (revokerContract?: `0x${string}`) => {
+      _requireConnected();
+      const { publicClient, walletClient } = connectStore.getState();
+      return acps.revokeAllACPs(walletClient!, publicClient!, revokerContract);
+    },
+
+    isACPRevoked: async (acp) => {
+      _requireConnected();
+      const { publicClient } = connectStore.getState();
+      return acps.isACPRevoked(acp, publicClient!);
+    },
+
+    // On-chain sharing (require connection + config.acp.sharingRegistry)
+    shareOnChain: async (acp) => {
+      _requireConnected();
+      const { publicClient, walletClient } = connectStore.getState();
+      const chainId = await publicClient!.getChainId();
+      const sharingRegistry = await _resolveSharingRegistry(publicClient!, chainId);
+      return acps.shareOnChain(acp, walletClient!, sharingRegistry);
+    },
+
+    getIncomingShares: async () => {
+      _requireConnected();
+      const { publicClient, walletClient } = connectStore.getState();
+      const chainId = await publicClient!.getChainId();
+      const account = walletClient!.account!.address;
+      const sharingRegistry = await _resolveSharingRegistry(publicClient!, chainId);
+      return acps.getIncomingShares(publicClient!, sharingRegistry, account);
+    },
+
+    importFromChain: async (share) => {
+      _requireConnected();
+      const { publicClient, walletClient } = connectStore.getState();
+      return acps.importFromChain(share, publicClient!, walletClient!);
+    },
+
+    dismissShare: async (shareId) => {
+      _requireConnected();
+      const { publicClient, walletClient } = connectStore.getState();
+      const chainId = await publicClient!.getChainId();
+      const sharingRegistry = await _resolveSharingRegistry(publicClient!, chainId);
+      return acps.removeShareOnChain(shareId, walletClient!, sharingRegistry);
+    },
+
+    cancelShare: async (shareId) => {
+      _requireConnected();
+      const { publicClient, walletClient } = connectStore.getState();
+      const chainId = await publicClient!.getChainId();
+      const sharingRegistry = await _resolveSharingRegistry(publicClient!, chainId);
+      return acps.removeShareOnChain(shareId, walletClient!, sharingRegistry);
     },
 
     // Retrieval methods (auto-fill chainId/account)
-    getPermit: (hash: string, chainId?: number, account?: string) => {
+    getACP: (hash: string, chainId?: number, account?: string) => {
       const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
-      return permits.getPermit(_chainId, _account, hash);
+      return acps.getACP(_chainId, _account, hash);
     },
 
-    getPermits: (chainId?: number, account?: string) => {
+    getACPs: (chainId?: number, account?: string) => {
       const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
-      return permits.getPermits(_chainId, _account);
+      return acps.getACPs(_chainId, _account);
     },
 
-    getActivePermit: (chainId?: number, account?: string) => {
+    getActiveACP: (chainId?: number, account?: string) => {
       const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
-      return permits.getActivePermit(_chainId, _account);
+      return acps.getActiveACP(_chainId, _account);
     },
 
-    getActivePermitHash: (chainId?: number, account?: string) => {
+    getActiveACPHash: (chainId?: number, account?: string) => {
       const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
-      return permits.getActivePermitHash(_chainId, _account);
+      return acps.getActiveACPHash(_chainId, _account);
     },
 
     // Mutation methods (auto-fill chainId/account)
-    selectActivePermit: (hash: string, chainId?: number, account?: string) => {
+    selectActiveACP: (hash: string, chainId?: number, account?: string) => {
       const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
-      return permits.selectActivePermit(_chainId, _account, hash);
+      return acps.selectActiveACP(_chainId, _account, hash);
     },
 
-    removePermit: async (hash: string, chainId?: number, account?: string) => {
+    removeACP: async (hash: string, chainId?: number, account?: string) => {
       const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
-      return permits.removePermit(_chainId, _account, hash);
+      return acps.removeACP(_chainId, _account, hash);
     },
 
-    removeActivePermit: async (chainId?: number, account?: string) => {
+    removeActiveACP: async (chainId?: number, account?: string) => {
       const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
-      return permits.removeActivePermit(_chainId, _account);
+      return acps.removeActiveACP(_chainId, _account);
     },
 
     // Utils (no context needed)
-    getHash: permits.getHash,
-    export: permits.export,
-    serialize: permits.serialize,
-    deserialize: permits.deserialize,
+    getHash: acps.getHash,
+    export: acps.export,
+    serialize: acps.serialize,
+    deserialize: acps.deserialize,
   };
 
   return {
@@ -330,7 +427,7 @@ export function createCofheClientBase<TConfig extends CofheConfig>(
     decryptHandle: decryptForView,
     decryptForTx,
     verifyDecryptResult,
-    permits: clientPermits,
+    acp: clientACPs,
 
     // Add SDK-specific methods below that require connection
     // Example:

package/core/clientTypes.ts

@@ -3,21 +3,22 @@ import { type Hex, type PublicClient, type WalletClient } from 'viem';
 import { type CofheConfig } from './config.js';
 import { type DecryptForViewBuilder } from './decrypt/decryptForViewBuilder.js';
 import { type DecryptForTxBuilderUnset } from './decrypt/decryptForTxBuilder.js';
-import { type EncryptInputsBuilder } from './encrypt/encryptInputsBuilder.js';
+import { type EncryptInputsBuilderUnset } from './encrypt/encryptInputsBuilder.js';
 import { type ZkBuilderAndCrsGenerator, type ZkProveWorkerFunction } from './encrypt/zkPackProveVerify.js';
 import { type FheKeyDeserializer } from './fetchKeys.js';
-import { permits } from './permits.js';
+import { acps } from './acps.js';
 import type { EncryptableItem, FheTypes, TfheInitializer } from './types.js';
-import type { PermitUtils } from 'permits/permit.js';
+import type { ACPUtils } from 'acps/acp.js';
 import type {
-  CreateSelfPermitOptions,
-  Permit,
-  CreateSharingPermitOptions,
-  ImportSharedPermitOptions,
-  SharingPermit,
-  RecipientPermit,
-  SelfPermit,
-} from 'permits/types.js';
+  CreateSelfACPOptions,
+  ACP,
+  CreateSharingACPOptions,
+  ImportSharedACPOptions,
+  SharingACP,
+  RecipientACP,
+  SelfACP,
+  IncomingShare,
+} from 'acps/types.js';
 
 // CLIENT
 
@@ -38,13 +39,13 @@ export type CofheClient<TConfig extends CofheConfig = CofheConfig> = {
   /**
    * Clears the current connection state (account/chainId/clients) and marks the client as disconnected.
    *
-   * This does not delete persisted permits or stored FHE keys; it only resets the in-memory connection.
+   * This does not delete persisted acps or stored FHE keys; it only resets the in-memory connection.
    */
   disconnect(): void;
   /**
    * Types docstring
    */
-  encryptInputs<T extends EncryptableItem[]>(inputs: [...T]): EncryptInputsBuilder<[...T]>;
+  encryptInputs<T extends EncryptableItem[]>(inputs: [...T]): EncryptInputsBuilderUnset<[...T]>;
   /**
    * @deprecated Use `decryptForView` instead. Kept for backward compatibility.
    */
@@ -52,7 +53,8 @@ export type CofheClient<TConfig extends CofheConfig = CofheConfig> = {
   decryptForView<U extends FheTypes>(ctHash: bigint | string, utype: U): DecryptForViewBuilder<U>;
   decryptForTx(ctHash: bigint | string): DecryptForTxBuilderUnset;
   verifyDecryptResult(handle: bigint | string, cleartext: bigint, signature: Hex): Promise<boolean>;
-  permits: CofheClientPermits;
+  /** ACP (Access Control Permission) management — create, share, revoke, select. */
+  acp: CofheClientACPs;
 };
 
 export type CofheClientConnectionState = {
@@ -67,47 +69,56 @@ export type CofheClientConnectionState = {
 
 type Listener = (snapshot: CofheClientConnectionState) => void;
 
-export type CofheClientPermitsClients = {
+export type CofheClientACPsClients = {
   publicClient: PublicClient;
   walletClient: WalletClient;
 };
 
-export type CofheClientPermits = {
-  getSnapshot: typeof permits.getSnapshot;
-  subscribe: typeof permits.subscribe;
+export type CofheClientACPs = {
+  getSnapshot: typeof acps.getSnapshot;
+  subscribe: typeof acps.subscribe;
 
   // Creation methods (require connection, no params)
-  createSelf: (options: CreateSelfPermitOptions, clients?: CofheClientPermitsClients) => Promise<SelfPermit>;
-  createSharing: (options: CreateSharingPermitOptions, clients?: CofheClientPermitsClients) => Promise<SharingPermit>;
-  importShared: (
-    options: ImportSharedPermitOptions | string,
-    clients?: CofheClientPermitsClients
-  ) => Promise<RecipientPermit>;
+  createSelf: (options: CreateSelfACPOptions, clients?: CofheClientACPsClients) => Promise<SelfACP>;
+  createSharing: (options: CreateSharingACPOptions, clients?: CofheClientACPsClients) => Promise<SharingACP>;
+  importShared: (options: ImportSharedACPOptions | string, clients?: CofheClientACPsClients) => Promise<RecipientACP>;
 
   // Retrieval methods (chainId/account optional)
-  getPermit: (hash: string, chainId?: number, account?: string) => Permit | undefined;
-  getPermits: (chainId?: number, account?: string) => Record<string, Permit>;
-  getActivePermit: (chainId?: number, account?: string) => Permit | undefined;
-  getActivePermitHash: (chainId?: number, account?: string) => string | undefined;
+  getACP: (hash: string, chainId?: number, account?: string) => ACP | undefined;
+  getACPs: (chainId?: number, account?: string) => Record<string, ACP>;
+  getActiveACP: (chainId?: number, account?: string) => ACP | undefined;
+  getActiveACPHash: (chainId?: number, account?: string) => string | undefined;
 
   // Get or create methods (get active or create new, chainId/account optional)
-  getOrCreateSelfPermit: (chainId?: number, account?: string, options?: CreateSelfPermitOptions) => Promise<Permit>;
-  getOrCreateSharingPermit: (
-    options: CreateSharingPermitOptions,
-    chainId?: number,
-    account?: string
-  ) => Promise<Permit>;
+  getOrCreateSelfACP: (chainId?: number, account?: string, options?: CreateSelfACPOptions) => Promise<ACP>;
+  getOrCreateSharingACP: (options: CreateSharingACPOptions, chainId?: number, account?: string) => Promise<ACP>;
 
   // Mutation methods (chainId/account optional)
-  selectActivePermit: (hash: string, chainId?: number, account?: string) => void;
-  removePermit: (hash: string, chainId?: number, account?: string) => void;
-  removeActivePermit: (chainId?: number, account?: string) => void;
+  selectActiveACP: (hash: string, chainId?: number, account?: string) => void;
+  removeACP: (hash: string, chainId?: number, account?: string) => void;
+  removeActiveACP: (chainId?: number, account?: string) => void;
+
+  // Revocation (on-chain, require connection)
+  revokeACP: (acp: ACP) => Promise<`0x${string}`>;
+  revokeAllACPs: (revokerContract?: `0x${string}`) => Promise<`0x${string}`>;
+  isACPRevoked: (acp: ACP) => Promise<boolean>;
+
+  /** Post a signed sharing ACP to the on-chain share registry (ACL-served, or config `acp.sharingRegistry`). */
+  shareOnChain: (acp: ACP) => Promise<{ txHash: `0x${string}`; shareId: `0x${string}` }>;
+  /** Importable shares addressed to the connected account (unexpired, not revoked). */
+  getIncomingShares: () => Promise<IncomingShare[]>;
+  /** Import a share read from the registry: sign as recipient, store and activate. */
+  importFromChain: (share: IncomingShare) => Promise<RecipientACP>;
+  /** Recipient-side: remove a share from the registry (after import, or to decline). */
+  dismissShare: (shareId: `0x${string}`) => Promise<`0x${string}`>;
+  /** Issuer-side: retract a pending share from the registry. */
+  cancelShare: (shareId: `0x${string}`) => Promise<`0x${string}`>;
 
   // Utils
-  getHash: typeof PermitUtils.getHash;
-  export: typeof PermitUtils.export;
-  serialize: typeof PermitUtils.serialize;
-  deserialize: typeof PermitUtils.deserialize;
+  getHash: typeof ACPUtils.getHash;
+  export: typeof ACPUtils.export;
+  serialize: typeof ACPUtils.serialize;
+  deserialize: typeof ACPUtils.deserialize;
 };
 
 export type CofheClientParams<TConfig extends CofheConfig> = {

package/core/config.ts

@@ -15,8 +15,8 @@ export type CofheConfig = {
   environment: 'node' | 'hardhat' | 'web' | 'react';
   /** List of supported chains */
   supportedChains: CofheChain[];
-  /** Default permit expiration in seconds, default is 30 days */
-  defaultPermitExpiration: number;
+  /** Default acp expiration in seconds, default is 30 days */
+  defaultACPExpiration: number;
   /**
    * Storage scheme for the fetched fhe keys
    * FHE keys are large, and caching prevents re-fetching them on each encryptInputs call
@@ -29,6 +29,32 @@ export type CofheConfig = {
    * Default: true
    */
   useWorkers: boolean;
+  /** ACP acp defaults, applied when creating acps (user options always win) */
+  acp: {
+    /**
+     * Default revoker contract per chainId — an explicit override; when unset,
+     * the address served by the chain's ACL (`defaultRevokerContract()`) is
+     * used. When available, created acps are revocable by default:
+     * revokerContract = this address and revokerData = acp creation
+     * timestamp (interpreted by the default timestamp revoker; enables
+     * revokeSingle + O(1) revokeAll).
+     */
+    defaultRevoker?: Record<number, `0x${string}`>;
+    /**
+     * Default contract scopes per chainId, injected into created acps'
+     * `contracts` when the caller doesn't provide scope options.
+     * Note: injecting scopes makes created acps non-global by default.
+     */
+    defaultContractScopes?: Record<number, `0x${string}`[]>;
+    /**
+     * ACPShareRegistry address per chainId — the on-chain hand-off for sharing
+     * ACPs. An explicit override; when unset, the address served by the
+     * chain's ACL (`shareRegistry()`) is used. client.acp.shareOnChain /
+     * getIncomingShares / importFromChain throw MissingConfig when neither
+     * names a registry.
+     */
+    sharingRegistry?: Record<number, `0x${string}`>;
+  };
   /** Mocks configs */
   mocks: {
     /**
@@ -60,8 +86,8 @@ export const CofheConfigSchema = z.object({
   environment: z.enum(['node', 'hardhat', 'web', 'react']).optional().default('node'),
   /** List of supported chain configurations */
   supportedChains: z.array(z.custom<CofheChain>()),
-  /** Default permit expiration in seconds, default is 30 days */
-  defaultPermitExpiration: z
+  /** Default acp expiration in seconds, default is 30 days */
+  defaultACPExpiration: z
     .number()
     .optional()
     .default(60 * 60 * 24 * 30),
@@ -82,6 +108,15 @@ export const CofheConfigSchema = z.object({
     .default(null),
   /** Whether to use Web Workers for ZK proof generation (web platform only) */
   useWorkers: z.boolean().optional().default(true),
+  /** ACP acp defaults */
+  acp: z
+    .object({
+      defaultRevoker: z.custom<Record<number, `0x${string}`>>().optional(),
+      defaultContractScopes: z.custom<Record<number, `0x${string}`[]>>().optional(),
+      sharingRegistry: z.custom<Record<number, `0x${string}`>>().optional(),
+    })
+    .optional()
+    .default({}),
   /** Mocks configs */
   mocks: z
     .object({
@@ -106,6 +141,28 @@ export const CofheConfigSchema = z.object({
  */
 export type CofheInputConfig = z.input<typeof CofheConfigSchema>;
 
+/**
+ * Config keys renamed in the ACP migration, mapped to their replacements.
+ *
+ * Unknown keys are rejected rather than stripped: silently dropping `defaultPermitExpiration` would
+ * leave the caller on the default expiration with no error, no warning, and no compiler complaint.
+ */
+export const RENAMED_COFHE_CONFIG_KEYS: Record<string, string> = {
+  defaultPermitExpiration: 'defaultACPExpiration',
+};
+
+/**
+ * Throws a migration-shaped error if any pre-ACP config key is present.
+ * @throws {Error} Naming each stale key and its replacement.
+ */
+export function assertNoRenamedConfigKeys(config: object, renamedKeys: Record<string, string>, label: string): void {
+  const stale = Object.keys(config).filter((key) => key in renamedKeys);
+  if (stale.length === 0) return;
+
+  const renames = stale.map((key) => `\`${key}\` is now \`${renamedKeys[key]}\``).join('; ');
+  throw new Error(`Invalid ${label}: ${renames}. See the v0.7.0 migration guide.`);
+}
+
 /**
  * Creates and validates a cofhe configuration (base implementation)
  * @param config - The configuration object to validate
@@ -113,7 +170,11 @@ export type CofheInputConfig = z.input<typeof CofheConfigSchema>;
  * @throws {Error} If the configuration is invalid
  */
 export function createCofheConfigBase(config: CofheInputConfig): CofheConfig {
-  const result = CofheConfigSchema.safeParse(config);
+  assertNoRenamedConfigKeys(config, RENAMED_COFHE_CONFIG_KEYS, 'cofhe configuration');
+
+  // .strict(): reject unknown keys instead of stripping them - a stale or typo'd key is an error,
+  // not a silent no-op that leaves the caller on a default they didn't ask for.
+  const result = CofheConfigSchema.strict().safeParse(config);
 
   if (!result.success) {
     throw new Error(`Invalid cofhe configuration: ${z.prettifyError(result.error)}`, { cause: result.error });

package/core/debug.ts

@@ -0,0 +1,72 @@
+// Neutral, opt-in debug interceptors around every low-level SDK network request.
+// Purpose-agnostic: a registered handler can observe, rewrite the URL, mutate the
+// request body/init, replace the response, or throw — enabling fault-injection,
+// logging, latency simulation, endpoint redirection, etc. without any
+// scenario-specific code in the SDK.
+//
+// Nothing is active unless an interceptor is registered (setCofheDebugInterceptors),
+// so this is a no-op in production by default.
+
+export interface CofheRequestContext {
+  /** Coarse label for the call site, e.g. 'decrypt' | 'sealoutput' | 'fetchKeys'. */
+  op: string;
+}
+
+export interface CofheRequestOverride {
+  url?: string;
+  init?: RequestInit;
+}
+
+export type CofheOnRequest = (
+  url: string,
+  init: RequestInit | undefined,
+  ctx: CofheRequestContext
+) => CofheRequestOverride | void | Promise<CofheRequestOverride | void>;
+
+export type CofheOnResponse = (
+  response: Response,
+  ctx: CofheRequestContext
+) => Response | void | Promise<Response | void>;
+
+export interface CofheDebugInterceptors {
+  onRequest?: CofheOnRequest;
+  onResponse?: CofheOnResponse;
+}
+
+const interceptors: CofheDebugInterceptors = {};
+
+/** Register (or clear, with null) the debug interceptors. */
+export function setCofheDebugInterceptors(next: CofheDebugInterceptors | null): void {
+  interceptors.onRequest = next?.onRequest;
+  interceptors.onResponse = next?.onResponse;
+}
+
+export function getCofheDebugInterceptors(): CofheDebugInterceptors {
+  return interceptors;
+}
+
+/**
+ * fetch() wrapper used by all low-level SDK network ops. Applies the registered
+ * debug interceptors when present; otherwise behaves exactly like fetch().
+ */
+export async function cofheFetch(
+  url: string,
+  init?: RequestInit,
+  ctx: CofheRequestContext = { op: 'request' }
+): Promise<Response> {
+  let finalUrl = url;
+  let finalInit = init;
+  if (interceptors.onRequest) {
+    const override = await interceptors.onRequest(finalUrl, finalInit, ctx);
+    if (override) {
+      if (override.url !== undefined) finalUrl = override.url;
+      if (override.init !== undefined) finalInit = override.init;
+    }
+  }
+  let response = await fetch(finalUrl, finalInit);
+  if (interceptors.onResponse) {
+    const replaced = await interceptors.onResponse(response, ctx);
+    if (replaced) response = replaced;
+  }
+  return response;
+}