@cofhe/sdk 0.6.1 → 0.7.0

package/core/test/decryptBuilders.test.ts

@@ -111,58 +111,58 @@ describe('DecryptForTxBuilder', () => {
     });
   });
 
-  // --- withPermit / withoutPermit selection ---
+  // --- withACP / withoutACP selection ---
 
-  describe('withPermit / withoutPermit selection', () => {
-    it('withPermit() should set permit selection', () => {
+  describe('withACP / withoutACP selection', () => {
+    it('withACP() should set acp selection', () => {
       const builder = createTxBuilder();
-      const selected = builder.withPermit();
+      const selected = builder.withACP();
       expect(selected).toBeDefined();
-      expect(selected.getPermit()).toBeUndefined();
-      expect(selected.getPermitHash()).toBeUndefined();
+      expect(selected.getACP()).toBeUndefined();
+      expect(selected.getACPHash()).toBeUndefined();
     });
 
-    it('withPermit(hash) should store the permit hash', () => {
+    it('withACP(hash) should store the acp hash', () => {
       const builder = createTxBuilder();
-      const selected = builder.withPermit('0xmypermithash');
-      expect(selected.getPermitHash()).toBe('0xmypermithash');
-      expect(selected.getPermit()).toBeUndefined();
+      const selected = builder.withACP('0xmyacphash');
+      expect(selected.getACPHash()).toBe('0xmyacphash');
+      expect(selected.getACP()).toBeUndefined();
     });
 
-    it('withoutPermit() should set permit selection', () => {
+    it('withoutACP() should set acp selection', () => {
       const builder = createTxBuilder();
-      const selected = builder.withoutPermit();
+      const selected = builder.withoutACP();
       expect(selected).toBeDefined();
-      expect(selected.getPermit()).toBeUndefined();
-      expect(selected.getPermitHash()).toBeUndefined();
+      expect(selected.getACP()).toBeUndefined();
+      expect(selected.getACPHash()).toBeUndefined();
     });
 
-    it('should throw when withPermit() is called twice', () => {
+    it('should throw when withACP() is called twice', () => {
       const builder = createTxBuilder();
-      builder.withPermit();
+      builder.withACP();
 
-      expect(() => (builder as any).withPermit()).toThrow('withPermit() can only be selected once');
+      expect(() => (builder as any).withACP()).toThrow('withACP() can only be selected once');
     });
 
-    it('should throw when withoutPermit() is called twice', () => {
+    it('should throw when withoutACP() is called twice', () => {
       const builder = createTxBuilder();
-      builder.withoutPermit();
+      builder.withoutACP();
 
-      expect(() => (builder as any).withoutPermit()).toThrow('withoutPermit() can only be selected once');
+      expect(() => (builder as any).withoutACP()).toThrow('withoutACP() can only be selected once');
     });
 
-    it('should throw when withPermit() is called after withoutPermit()', () => {
+    it('should throw when withACP() is called after withoutACP()', () => {
       const builder = createTxBuilder();
-      builder.withoutPermit();
+      builder.withoutACP();
 
-      expect(() => (builder as any).withPermit()).toThrow('cannot call withPermit() after withoutPermit()');
+      expect(() => (builder as any).withACP()).toThrow('cannot call withACP() after withoutACP()');
     });
 
-    it('should throw when withoutPermit() is called after withPermit()', () => {
+    it('should throw when withoutACP() is called after withACP()', () => {
       const builder = createTxBuilder();
-      builder.withPermit();
+      builder.withACP();
 
-      expect(() => (builder as any).withoutPermit()).toThrow('cannot call withoutPermit() after withPermit()');
+      expect(() => (builder as any).withoutACP()).toThrow('cannot call withoutACP() after withACP()');
     });
   });
 
@@ -171,16 +171,16 @@ describe('DecryptForTxBuilder', () => {
   describe('chaining', () => {
     it('should return the builder from each setter for fluent chaining', () => {
       const builder = createTxBuilder({ chainId: undefined, account: undefined });
-      const result = builder.setChainId(TEST_CHAIN_ID).setAccount(account.address).withPermit();
+      const result = builder.setChainId(TEST_CHAIN_ID).setAccount(account.address).withACP();
 
       expect(result).toBeDefined();
       expect(result.getChainId()).toBe(TEST_CHAIN_ID);
       expect(result.getAccount()).toBe(account.address);
     });
 
-    it('should allow setChainId and setAccount after withPermit', () => {
+    it('should allow setChainId and setAccount after withACP', () => {
       const builder = createTxBuilder({ chainId: undefined, account: undefined });
-      const selected = builder.withPermit();
+      const selected = builder.withACP();
       selected.setChainId(99);
       selected.setAccount('0xabc');
 
@@ -188,9 +188,9 @@ describe('DecryptForTxBuilder', () => {
       expect(selected.getAccount()).toBe('0xabc');
     });
 
-    it('should allow setChainId and setAccount after withoutPermit', () => {
+    it('should allow setChainId and setAccount after withoutACP', () => {
       const builder = createTxBuilder({ chainId: undefined, account: undefined });
-      const selected = builder.withoutPermit();
+      const selected = builder.withoutACP();
       selected.setChainId(99);
       selected.setAccount('0xabc');
 
@@ -216,7 +216,7 @@ describe('DecryptForTxBuilder', () => {
   // --- execute error paths ---
 
   describe('execute – error paths', () => {
-    it('should throw when execute() is called without permit selection', async () => {
+    it('should throw when execute() is called without acp selection', async () => {
       const builder = createTxBuilder();
 
       try {
@@ -224,31 +224,31 @@ describe('DecryptForTxBuilder', () => {
         expect.fail('Expected error');
       } catch (error) {
         expect((error as any).code).toBe(CofheErrorCode.InternalError);
-        expect((error as Error).message).toContain('missing permit selection');
+        expect((error as Error).message).toContain('missing acp selection');
       }
     });
 
-    it('should throw when withPermit() has no active permit', async () => {
+    it('should throw when withACP() has no active acp', async () => {
       const builder = createTxBuilder();
 
       try {
-        await builder.withPermit().execute();
-        expect.fail('Expected PermitNotFound error');
+        await builder.withACP().execute();
+        expect.fail('Expected ACPNotFound error');
       } catch (error) {
-        expect((error as any).code).toBe(CofheErrorCode.PermitNotFound);
-        expect((error as Error).message).toContain('Active permit not found');
+        expect((error as any).code).toBe(CofheErrorCode.ACPNotFound);
+        expect((error as Error).message).toContain('Active acp not found');
       }
     });
 
-    it('should throw when withPermit(hash) cannot find permit', async () => {
+    it('should throw when withACP(hash) cannot find acp', async () => {
       const builder = createTxBuilder();
 
       try {
-        await builder.withPermit('0xnonexistent').execute();
-        expect.fail('Expected PermitNotFound error');
+        await builder.withACP('0xnonexistent').execute();
+        expect.fail('Expected ACPNotFound error');
       } catch (error) {
-        expect((error as any).code).toBe(CofheErrorCode.PermitNotFound);
-        expect((error as Error).message).toContain('Permit with hash');
+        expect((error as any).code).toBe(CofheErrorCode.ACPNotFound);
+        expect((error as Error).message).toContain('ACP with hash');
       }
     });
   });
@@ -302,30 +302,30 @@ describe('DecryptForViewBuilder', () => {
     });
   });
 
-  // --- withPermit ---
+  // --- withACP ---
 
-  describe('withPermit', () => {
-    it('withPermit() should clear permit and hash', () => {
+  describe('withACP', () => {
+    it('withACP() should clear acp and hash', () => {
       const builder = createViewBuilder(FheTypes.Uint32);
-      builder.withPermit();
-      expect(builder.getPermit()).toBeUndefined();
-      expect(builder.getPermitHash()).toBeUndefined();
+      builder.withACP();
+      expect(builder.getACP()).toBeUndefined();
+      expect(builder.getACPHash()).toBeUndefined();
     });
 
-    it('withPermit(hash) should store the permit hash', () => {
+    it('withACP(hash) should store the acp hash', () => {
       const builder = createViewBuilder(FheTypes.Uint32);
-      builder.withPermit('0xmypermithash');
-      expect(builder.getPermitHash()).toBe('0xmypermithash');
-      expect(builder.getPermit()).toBeUndefined();
+      builder.withACP('0xmyacphash');
+      expect(builder.getACPHash()).toBe('0xmyacphash');
+      expect(builder.getACP()).toBeUndefined();
     });
 
-    it('should allow overriding permit selection', () => {
+    it('should allow overriding acp selection', () => {
       const builder = createViewBuilder(FheTypes.Uint32);
-      builder.withPermit('0xfirst');
-      expect(builder.getPermitHash()).toBe('0xfirst');
+      builder.withACP('0xfirst');
+      expect(builder.getACPHash()).toBe('0xfirst');
 
-      builder.withPermit('0xsecond');
-      expect(builder.getPermitHash()).toBe('0xsecond');
+      builder.withACP('0xsecond');
+      expect(builder.getACPHash()).toBe('0xsecond');
     });
   });
 
@@ -334,7 +334,7 @@ describe('DecryptForViewBuilder', () => {
   describe('chaining', () => {
     it('should return the builder from each setter for fluent chaining', () => {
       const builder = createViewBuilder(FheTypes.Uint32, { chainId: undefined, account: undefined });
-      const result = builder.setChainId(TEST_CHAIN_ID).setAccount(account.address).withPermit();
+      const result = builder.setChainId(TEST_CHAIN_ID).setAccount(account.address).withACP();
 
       expect(result).toBeDefined();
       expect(result.getChainId()).toBe(TEST_CHAIN_ID);
@@ -359,28 +359,28 @@ describe('DecryptForViewBuilder', () => {
   // --- execute error paths ---
 
   describe('execute – error paths', () => {
-    it('should throw when active permit is not found', async () => {
+    it('should throw when active acp is not found', async () => {
       const builder = createViewBuilder(FheTypes.Uint32);
 
       try {
         await builder.execute();
-        expect.fail('Expected PermitNotFound error');
+        expect.fail('Expected ACPNotFound error');
       } catch (error) {
-        expect((error as any).code).toBe(CofheErrorCode.PermitNotFound);
-        expect((error as Error).message).toContain('Active permit not found');
+        expect((error as any).code).toBe(CofheErrorCode.ACPNotFound);
+        expect((error as Error).message).toContain('Active acp not found');
       }
     });
 
-    it('should throw when withPermit(hash) cannot find permit', async () => {
+    it('should throw when withACP(hash) cannot find acp', async () => {
       const builder = createViewBuilder(FheTypes.Uint32);
-      builder.withPermit('0xnonexistent');
+      builder.withACP('0xnonexistent');
 
       try {
         await builder.execute();
-        expect.fail('Expected PermitNotFound error');
+        expect.fail('Expected ACPNotFound error');
       } catch (error) {
-        expect((error as any).code).toBe(CofheErrorCode.PermitNotFound);
-        expect((error as Error).message).toContain('Permit with hash');
+        expect((error as any).code).toBe(CofheErrorCode.ACPNotFound);
+        expect((error as Error).message).toContain('ACP with hash');
       }
     });
 

package/core/test/decryptErrorCodes.test.ts

@@ -0,0 +1,217 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { tnDecryptV2 } from '../decrypt/tnDecryptV2.js';
+import { tnSealOutputV2 } from '../decrypt/tnSealOutputV2.js';
+import { CofheErrorCode } from '../error.js';
+
+// Cross-reference: API-RESPONSES.md's "Shared errors" table (applies to all decrypt/sealoutput
+// submit and poll endpoints).
+const SHARED_ERROR_CASES: Array<{ status: number; error: string; cofheErrorCode: CofheErrorCode }> = [
+  { status: 400, error: 'bad_request', cofheErrorCode: CofheErrorCode.BadRequest },
+  { status: 400, error: 'unknown_chain', cofheErrorCode: CofheErrorCode.UnknownChain },
+  { status: 400, error: 'acp_malformed', cofheErrorCode: CofheErrorCode.ACPMalformed },
+  { status: 401, error: 'acp_denied', cofheErrorCode: CofheErrorCode.ACPDenied },
+  { status: 401, error: 'acp_expired', cofheErrorCode: CofheErrorCode.ACPExpired },
+  { status: 401, error: 'acp_invalid', cofheErrorCode: CofheErrorCode.ACPInvalid },
+  { status: 403, error: 'not_publicly_allowed', cofheErrorCode: CofheErrorCode.NotPubliclyAllowed },
+  { status: 422, error: 'unsupported_security_zone', cofheErrorCode: CofheErrorCode.UnsupportedSecurityZone },
+  { status: 422, error: 'unsupported_type', cofheErrorCode: CofheErrorCode.UnsupportedType },
+  { status: 500, error: 'internal_error', cofheErrorCode: CofheErrorCode.InternalError },
+  { status: 500, error: 'signing_failed', cofheErrorCode: CofheErrorCode.SigningFailed },
+  { status: 502, error: 'ct_source_error', cofheErrorCode: CofheErrorCode.CtSourceError },
+  { status: 502, error: 'acp_verifier_error', cofheErrorCode: CofheErrorCode.ACPVerifierError },
+  { status: 504, error: 'ct_source_timeout', cofheErrorCode: CofheErrorCode.CtSourceTimeout },
+  { status: 504, error: 'acp_verifier_timeout', cofheErrorCode: CofheErrorCode.ACPVerifierTimeout },
+];
+// ct_not_found (404) is deliberately excluded here: on the submit endpoints it's the
+// conditionally-retryable case (covered by pollCallbacks.test.ts / submitRetry.test.ts), and on
+// the poll endpoints it's documented bodyless (covered separately below).
+
+const makeMockResponse = (opts: { ok: boolean; status?: number; statusText?: string; json: () => Promise<any> }) => {
+  return {
+    ok: opts.ok,
+    status: opts.status ?? (opts.ok ? 200 : 500),
+    statusText: opts.statusText ?? '',
+    json: opts.json,
+  } as unknown as Response;
+};
+
+describe('decrypt/sealoutput API-RESPONSES.md error-code coverage', () => {
+  const thresholdNetworkUrl = 'http://threshold.local';
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  describe.each([
+    { operation: 'decrypt' as const, path: '/v2/decrypt', run: tnDecryptV2, fallback: CofheErrorCode.DecryptFailed },
+    {
+      operation: 'sealoutput' as const,
+      path: '/v2/sealoutput',
+      run: tnSealOutputV2,
+      fallback: CofheErrorCode.SealOutputFailed,
+    },
+  ])('$operation submit ($path)', ({ path, run, fallback }) => {
+    it.each(SHARED_ERROR_CASES)('maps $status $error to the dedicated CofheErrorCode', async ({ status, error }) => {
+      const fetchMock = vi.fn(async (url: string) => {
+        if (url === `${thresholdNetworkUrl}${path}`) {
+          return makeMockResponse({
+            ok: false,
+            status,
+            json: async () => ({ error, error_message: `backend said ${error}` }),
+          });
+        }
+        throw new Error(`Unexpected fetch: ${url}`);
+      });
+      global.fetch = fetchMock as any;
+
+      const expectedCode = SHARED_ERROR_CASES.find((c) => c.error === error)!.cofheErrorCode;
+
+      await expect(run({ ctHash: 1n, chainId: 1, acp: {} as any, thresholdNetworkUrl } as any)).rejects.toMatchObject({
+        code: expectedCode,
+        apiErrorCode: error,
+        message: expect.stringContaining(`backend said ${error}`),
+      });
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('falls back to the operation-level generic code for an unrecognized future error code', async () => {
+      const fetchMock = vi.fn(async () =>
+        makeMockResponse({
+          ok: false,
+          status: 400,
+          json: async () => ({ error: 'some_future_code', error_message: 'not yet known to the SDK' }),
+        })
+      );
+      global.fetch = fetchMock as any;
+
+      await expect(run({ ctHash: 1n, chainId: 1, acp: {} as any, thresholdNetworkUrl } as any)).rejects.toMatchObject({
+        code: fallback,
+        apiErrorCode: 'some_future_code',
+      });
+    });
+
+    it('degrades gracefully on a plain-text framework rejection (e.g. 415)', async () => {
+      const fetchMock = vi.fn(async () =>
+        makeMockResponse({
+          ok: false,
+          status: 415,
+          statusText: 'Unsupported Media Type',
+          json: async () => {
+            throw new Error('body is plain text, not JSON');
+          },
+        })
+      );
+      global.fetch = fetchMock as any;
+
+      await expect(run({ ctHash: 1n, chainId: 1, acp: {} as any, thresholdNetworkUrl } as any)).rejects.toMatchObject({
+        code: fallback,
+        apiErrorCode: undefined,
+        message: expect.stringContaining('Unsupported Media Type'),
+      });
+    });
+  });
+
+  it('sealoutput submit maps 400 acp_required (sealoutput-specific)', async () => {
+    global.fetch = vi.fn(async () =>
+      makeMockResponse({
+        ok: false,
+        status: 400,
+        json: async () => ({ error: 'acp_required', error_message: 'no acp in request' }),
+      })
+    ) as any;
+
+    await expect(tnSealOutputV2({ ctHash: 1n, chainId: 1, acp: {} as any, thresholdNetworkUrl })).rejects.toMatchObject(
+      {
+        code: CofheErrorCode.ACPRequired,
+        apiErrorCode: 'acp_required',
+      }
+    );
+  });
+
+  it('sealoutput submit maps 500 seal_failed (sealoutput-specific)', async () => {
+    global.fetch = vi.fn(async () =>
+      makeMockResponse({
+        ok: false,
+        status: 500,
+        json: async () => ({ error: 'seal_failed', error_message: 'sealing crypto failed' }),
+      })
+    ) as any;
+
+    await expect(tnSealOutputV2({ ctHash: 1n, chainId: 1, acp: {} as any, thresholdNetworkUrl })).rejects.toMatchObject(
+      {
+        code: CofheErrorCode.SealFailed,
+        apiErrorCode: 'seal_failed',
+      }
+    );
+  });
+
+  describe.each([
+    {
+      operation: 'decrypt' as const,
+      submitPath: '/v2/decrypt',
+      statusPath: (id: string) => `/v2/decrypt/${id}`,
+      run: tnDecryptV2,
+      fallback: CofheErrorCode.DecryptFailed,
+    },
+    {
+      operation: 'sealoutput' as const,
+      submitPath: '/v2/sealoutput',
+      statusPath: (id: string) => `/v2/sealoutput/${id}`,
+      run: tnSealOutputV2,
+      fallback: CofheErrorCode.SealOutputFailed,
+    },
+  ])('$operation poll (GET status endpoint)', ({ submitPath, statusPath, run, fallback }) => {
+    const requestId = 'req-poll-errors';
+
+    it('maps a non-404 non-ok status via the shared error table (e.g. 500 internal_error)', async () => {
+      const fetchMock = vi.fn(async (url: string) => {
+        if (url === `${thresholdNetworkUrl}${submitPath}`) {
+          return makeMockResponse({ ok: true, json: async () => ({ request_id: requestId }) });
+        }
+        if (url === `${thresholdNetworkUrl}${statusPath(requestId)}`) {
+          return makeMockResponse({
+            ok: false,
+            status: 500,
+            json: async () => ({ error: 'internal_error', error_message: 'decrypt task panicked' }),
+          });
+        }
+        throw new Error(`Unexpected fetch: ${url}`);
+      });
+      global.fetch = fetchMock as any;
+
+      const promise = run({ ctHash: 1n, chainId: 1, acp: {} as any, thresholdNetworkUrl } as any);
+
+      await expect(promise).rejects.toMatchObject({
+        code: CofheErrorCode.InternalError,
+        apiErrorCode: 'internal_error',
+        message: expect.stringContaining('decrypt task panicked'),
+      });
+    });
+
+    it('throws immediately on a bodyless 404 (unknown/evicted request_id) without calling response.json()', async () => {
+      const statusJson = vi.fn(async () => {
+        throw new Error('json() should not be called for a bodyless 404');
+      });
+      const fetchMock = vi.fn(async (url: string) => {
+        if (url === `${thresholdNetworkUrl}${submitPath}`) {
+          return makeMockResponse({ ok: true, json: async () => ({ request_id: requestId }) });
+        }
+        if (url === `${thresholdNetworkUrl}${statusPath(requestId)}`) {
+          return makeMockResponse({ ok: false, status: 404, json: statusJson });
+        }
+        throw new Error(`Unexpected fetch: ${url}`);
+      });
+      global.fetch = fetchMock as any;
+
+      const promise = run({ ctHash: 1n, chainId: 1, acp: {} as any, thresholdNetworkUrl } as any);
+
+      await expect(promise).rejects.toMatchObject({ code: fallback });
+      expect(statusJson).not.toHaveBeenCalled();
+    });
+  });
+});