fix(remote): validate credential fields before use

.github/workflows/ci.yml

@@ -150,6 +150,9 @@ jobs:
       - name: Build
         run: ${{ matrix.settings.build }}
         shell: bash
+      - name: Run Rust unit tests
+        if: ${{ matrix.settings.target == 'aarch64-apple-darwin' }}
+        run: cargo test --no-fail-fast
       - name: Check generated bindings are up to date
         if: ${{ matrix.settings.target == 'aarch64-apple-darwin' }}
         run: |

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## Unreleased
+
+- fix(remote): reject credentials with missing required fields before connecting (#223). `SSHKeyFromPath` requires `privateKeyPath`, `SSHKey` requires `privateKey`, and `Plain` requires `password`. These inputs now fail with `InvalidArg` even for public or local remotes that previously ignored unused credentials. Omit `credential` when authentication is not needed, or provide the required field. Empty passwords and SSH keys without a passphrase remain supported.
+
 ## Version v0.7.0
 
 Released on May 17th, 2026.

docs/ko/reference/Remote/Methods/fetch.md

@@ -79,7 +79,7 @@ class Remote {
           <li class="param-li">
             <span class="param-name">credential</span><span class="param-type">Credential</span>
             <br>
-            <p class="param-description">Git 인증 정보를 나타내는 인터페이스예요.</p>
+            <p class="param-description">libgit2에서 Git 인증 정보를 나타내는 인터페이스예요.<br><br><code>SSHKeyFromPath</code>에는 <code>privateKeyPath</code>, <code>SSHKey</code>에는 <code>privateKey</code>, <code>Plain</code>에는 <code>password</code>가 필요해요. 빈 비밀번호도 허용하며, 사용자 이름의 기본값은 <code>&quot;git&quot;</code>이에요. 공개 키와 패스프레이즈는 선택 사항이에요.<br><br>인증 정보는 연결 전에 검증하며, 인증이 필요 없는 공개 또는 로컬 리모트에도 적용돼요. 인증이 필요하지 않으면 <code>credential</code>을 생략하세요.</p>
           </li>
           <li class="param-li">
             <span class="param-name">customHeaders</span><span class="param-type">string[]</span>
@@ -164,6 +164,16 @@ class Remote {
   </li>
 </ul>
 
+### 에러
+
+<ul class="param-ul">
+  <li class="param-li param-li-root">
+    <span class="param-type">Error</span>
+    <br>
+    <p class="param-description"><code>options.fetch.credential</code>에 <code>type</code>별 필수 필드(<code>SSHKeyFromPath</code>의 <code>privateKeyPath</code>, <code>SSHKey</code>의 <code>privateKey</code>, <code>Plain</code>의 <code>password</code>)가 없으면 <code>InvalidArg</code> 오류가 발생해요. 인증이 필요 없는 리모트에도 적용돼요. fetch 작업이 실패해도 오류가 발생해요.</p>
+  </li>
+</ul>
+
 ## 예제
 
 ```ts

docs/ko/reference/Remote/Methods/prune.md

@@ -21,7 +21,7 @@ class Remote {
       <li class="param-li">
         <span class="param-name">credential</span><span class="param-type">Credential</span>
         <br>
-        <p class="param-description">Git 인증 정보를 나타내는 인터페이스예요.</p>
+        <p class="param-description">libgit2에서 Git 인증 정보를 나타내는 인터페이스예요.<br><br><code>SSHKeyFromPath</code>에는 <code>privateKeyPath</code>, <code>SSHKey</code>에는 <code>privateKey</code>, <code>Plain</code>에는 <code>password</code>가 필요해요. 빈 비밀번호도 허용하며, 사용자 이름의 기본값은 <code>&quot;git&quot;</code>이에요. 공개 키와 패스프레이즈는 선택 사항이에요.<br><br>인증 정보는 연결 전에 검증하며, 인증이 필요 없는 공개 또는 로컬 리모트에도 적용돼요. 인증이 필요하지 않으면 <code>credential</code>을 생략하세요.</p>
       </li>
     </ul>
   </li>
@@ -31,3 +31,13 @@ class Remote {
     <p class="param-description">요청을 중단할 때 사용할 <code>AbortSignal</code> 객체예요.</p>
   </li>
 </ul>
+
+### 에러
+
+<ul class="param-ul">
+  <li class="param-li param-li-root">
+    <span class="param-type">Error</span>
+    <br>
+    <p class="param-description"><code>options.credential</code>에 <code>type</code>별 필수 필드(<code>SSHKeyFromPath</code>의 <code>privateKeyPath</code>, <code>SSHKey</code>의 <code>privateKey</code>, <code>Plain</code>의 <code>password</code>)가 없으면 <code>InvalidArg</code> 오류가 발생해요. 인증이 필요 없는 리모트에도 적용돼요. prune 작업이 실패해도 오류가 발생해요.</p>
+  </li>
+</ul>

docs/ko/reference/Remote/Methods/push.md

@@ -74,7 +74,7 @@ class Remote {
       <li class="param-li">
         <span class="param-name">credential</span><span class="param-type">Credential</span>
         <br>
-        <p class="param-description">Git 인증 정보를 나타내는 인터페이스예요.</p>
+        <p class="param-description">libgit2에서 Git 인증 정보를 나타내는 인터페이스예요.<br><br><code>SSHKeyFromPath</code>에는 <code>privateKeyPath</code>, <code>SSHKey</code>에는 <code>privateKey</code>, <code>Plain</code>에는 <code>password</code>가 필요해요. 빈 비밀번호도 허용하며, 사용자 이름의 기본값은 <code>&quot;git&quot;</code>이에요. 공개 키와 패스프레이즈는 선택 사항이에요.<br><br>인증 정보는 연결 전에 검증하며, 인증이 필요 없는 공개 또는 로컬 리모트에도 적용돼요. 인증이 필요하지 않으면 <code>credential</code>을 생략하세요.</p>
       </li>
       <li class="param-li">
         <span class="param-name">customHeaders</span><span class="param-type">string[]</span>
@@ -136,6 +136,16 @@ class Remote {
   </li>
 </ul>
 
+### 에러
+
+<ul class="param-ul">
+  <li class="param-li param-li-root">
+    <span class="param-type">Error</span>
+    <br>
+    <p class="param-description"><code>options.credential</code>에 <code>type</code>별 필수 필드(<code>SSHKeyFromPath</code>의 <code>privateKeyPath</code>, <code>SSHKey</code>의 <code>privateKey</code>, <code>Plain</code>의 <code>password</code>)가 없으면 <code>InvalidArg</code> 오류가 발생해요. 인증이 필요 없는 리모트에도 적용돼요. push 작업이 실패해도 오류가 발생해요.</p>
+  </li>
+</ul>
+
 ## 예제
 
 ```ts

docs/ko/reference/Repository/cloneRepository.md

@@ -106,9 +106,7 @@ function cloneRepository(
           <li class="param-li">
             <span class="param-name">credential</span><span class="param-type">Credential</span>
             <br>
-            <p class="param-description">
-              인증 정보를 설정해요.
-            </p>
+            <p class="param-description">libgit2에서 Git 인증 정보를 나타내는 인터페이스예요.<br><br><code>SSHKeyFromPath</code>에는 <code>privateKeyPath</code>, <code>SSHKey</code>에는 <code>privateKey</code>, <code>Plain</code>에는 <code>password</code>가 필요해요. 빈 비밀번호도 허용하며, 사용자 이름의 기본값은 <code>&quot;git&quot;</code>이에요. 공개 키와 패스프레이즈는 선택 사항이에요.<br><br>인증 정보는 연결 전에 검증하며, 인증이 필요 없는 공개 또는 로컬 리모트에도 적용돼요. 인증이 필요하지 않으면 <code>credential</code>을 생략하세요.</p>
           </li>
           <li class="param-li">
             <span class="param-name">customHeaders</span><span class="param-type">string[]</span>
@@ -218,6 +216,16 @@ function cloneRepository(
   </li>
 </ul>
 
+### 에러
+
+<ul class="param-ul">
+  <li class="param-li param-li-root">
+    <span class="param-type">Error</span>
+    <br>
+    <p class="param-description"><code>options.fetch.credential</code>에 <code>type</code>별 필수 필드(<code>SSHKeyFromPath</code>의 <code>privateKeyPath</code>, <code>SSHKey</code>의 <code>privateKey</code>, <code>Plain</code>의 <code>password</code>)가 없으면 <code>InvalidArg</code> 오류가 발생해요. 인증이 필요 없는 리모트에도 적용돼요. clone 작업이 실패해도 오류가 발생해요.</p>
+  </li>
+</ul>
+
 ## 예제
 
 `https://` 프로토콜을 사용해 리포지토리 클론해요.

docs/ko/reference/Submodule/Methods/clone.md

@@ -165,10 +165,51 @@ class Submodule {
         <br>
         <p class="param-description">콜백을 포함해 fetch를 제어하는 옵션</p>
         <ul class="param-ul">
+          <li class="param-li">
+            <span class="param-name">callbacks</span><span class="param-type">RemoteCallbacks</span>
+            <br>
+            <ul class="param-ul">
+              <li class="param-li">
+                <span class="param-name">packProgress</span><span class="param-type">(stage: PackBuilderStage, current: number, total: number) =&gt; void</span>
+                <br>
+                <p class="param-description">팩 빌드 중 진행 정보를 전달하기 위해 호출할 함수예요. 이 함수는 팩 빌드 작업과 인라인으로 호출되므로 성능에 영향을 줄 수 있어요.</p>
+              </li>
+              <li class="param-li">
+                <span class="param-name">pushNegotiation</span><span class="param-type">(update: PushUpdate[]) =&gt; void</span>
+                <br>
+                <p class="param-description">협상 단계와 업로드 사이에 한 번 호출되는 콜백이에요. 콜백의 인수는 대상에 명령으로 전송될 업데이트를 포함하는 슬라이스예요.</p>
+              </li>
+              <li class="param-li">
+                <span class="param-name">pushTransferProgress</span><span class="param-type">(current: number, total: number, bytes: number) =&gt; void</span>
+                <br>
+                <p class="param-description">push 전송 진행 상황을 모니터링하는 콜백.</p>
+              </li>
+              <li class="param-li">
+                <span class="param-name">pushUpdateReference</span><span class="param-type">(refname: string, status: string | null) =&gt; void</span>
+                <br>
+                <p class="param-description">push 시 업데이트된 각 참조에 대해 호출되는 콜백을 설정해요. 콜백의 첫 번째 인수는 참조 이름이고, 두 번째는 서버에서 보낸 상태 메시지예요. 상태가 <code>null</code>이 아니면 push가 거부된 것이에요.</p>
+              </li>
+              <li class="param-li">
+                <span class="param-name">sidebandProgress</span><span class="param-type">(data: Uint8Array) =&gt; void</span>
+                <br>
+                <p class="param-description">리모트의 텍스트 진행 정보예요. progress 사이드 밴드를 통해 전송된 텍스트가 이 함수로 전달돼요 (이것은 &#39;counting objects&#39; 출력이에요).</p>
+              </li>
+              <li class="param-li">
+                <span class="param-name">transferProgress</span><span class="param-type">(data: RemoteTransferProgress) =&gt; void</span>
+                <br>
+                <p class="param-description">fetch 중 전송 진행 상황과 함께 호출돼요.</p>
+              </li>
+              <li class="param-li">
+                <span class="param-name">updateTips</span><span class="param-type">(refname: string, oldId: string, newId: string) =&gt; void</span>
+                <br>
+                <p class="param-description">참조가 로컬에서 업데이트될 때마다 해당 정보와 함께 콜백이 호출돼요.</p>
+              </li>
+            </ul>
+          </li>
           <li class="param-li">
             <span class="param-name">credential</span><span class="param-type">Credential</span>
             <br>
-            <p class="param-description">libgit2에서 git 자격 증명을 나타내는 인터페이스</p>
+            <p class="param-description">libgit2에서 Git 인증 정보를 나타내는 인터페이스예요.<br><br><code>SSHKeyFromPath</code>에는 <code>privateKeyPath</code>, <code>SSHKey</code>에는 <code>privateKey</code>, <code>Plain</code>에는 <code>password</code>가 필요해요. 빈 비밀번호도 허용하며, 사용자 이름의 기본값은 <code>&quot;git&quot;</code>이에요. 공개 키와 패스프레이즈는 선택 사항이에요.<br><br>인증 정보는 연결 전에 검증하며, 인증이 필요 없는 공개 또는 로컬 리모트에도 적용돼요. 인증이 필요하지 않으면 <code>credential</code>을 생략하세요.</p>
           </li>
           <li class="param-li">
             <span class="param-name">customHeaders</span><span class="param-type">string[]</span>
@@ -234,4 +275,14 @@ class Submodule {
     <br>
     <p class="param-description">새로 생성된 리포지토리 개체</p>
   </li>
-</ul>
+</ul>
+
+### 에러
+
+<ul class="param-ul">
+  <li class="param-li param-li-root">
+    <span class="param-type">Error</span>
+    <br>
+    <p class="param-description"><code>options.fetch.credential</code>에 <code>type</code>별 필수 필드(<code>SSHKeyFromPath</code>의 <code>privateKeyPath</code>, <code>SSHKey</code>의 <code>privateKey</code>, <code>Plain</code>의 <code>password</code>)가 없으면 <code>InvalidArg</code> 오류가 발생해요. 인증이 필요 없는 리모트에도 적용돼요. clone 작업이 실패해도 오류가 발생해요.</p>
+  </li>
+</ul>

docs/ko/reference/Submodule/Methods/update.md

@@ -171,10 +171,51 @@ class Submodule {
         <br>
         <p class="param-description">콜백을 포함해 fetch를 제어하는 옵션</p>
         <ul class="param-ul">
+          <li class="param-li">
+            <span class="param-name">callbacks</span><span class="param-type">RemoteCallbacks</span>
+            <br>
+            <ul class="param-ul">
+              <li class="param-li">
+                <span class="param-name">packProgress</span><span class="param-type">(stage: PackBuilderStage, current: number, total: number) =&gt; void</span>
+                <br>
+                <p class="param-description">팩 빌드 중 진행 정보를 전달하기 위해 호출할 함수예요. 이 함수는 팩 빌드 작업과 인라인으로 호출되므로 성능에 영향을 줄 수 있어요.</p>
+              </li>
+              <li class="param-li">
+                <span class="param-name">pushNegotiation</span><span class="param-type">(update: PushUpdate[]) =&gt; void</span>
+                <br>
+                <p class="param-description">협상 단계와 업로드 사이에 한 번 호출되는 콜백이에요. 콜백의 인수는 대상에 명령으로 전송될 업데이트를 포함하는 슬라이스예요.</p>
+              </li>
+              <li class="param-li">
+                <span class="param-name">pushTransferProgress</span><span class="param-type">(current: number, total: number, bytes: number) =&gt; void</span>
+                <br>
+                <p class="param-description">push 전송 진행 상황을 모니터링하는 콜백.</p>
+              </li>
+              <li class="param-li">
+                <span class="param-name">pushUpdateReference</span><span class="param-type">(refname: string, status: string | null) =&gt; void</span>
+                <br>
+                <p class="param-description">push 시 업데이트된 각 참조에 대해 호출되는 콜백을 설정해요. 콜백의 첫 번째 인수는 참조 이름이고, 두 번째는 서버에서 보낸 상태 메시지예요. 상태가 <code>null</code>이 아니면 push가 거부된 것이에요.</p>
+              </li>
+              <li class="param-li">
+                <span class="param-name">sidebandProgress</span><span class="param-type">(data: Uint8Array) =&gt; void</span>
+                <br>
+                <p class="param-description">리모트의 텍스트 진행 정보예요. progress 사이드 밴드를 통해 전송된 텍스트가 이 함수로 전달돼요 (이것은 &#39;counting objects&#39; 출력이에요).</p>
+              </li>
+              <li class="param-li">
+                <span class="param-name">transferProgress</span><span class="param-type">(data: RemoteTransferProgress) =&gt; void</span>
+                <br>
+                <p class="param-description">fetch 중 전송 진행 상황과 함께 호출돼요.</p>
+              </li>
+              <li class="param-li">
+                <span class="param-name">updateTips</span><span class="param-type">(refname: string, oldId: string, newId: string) =&gt; void</span>
+                <br>
+                <p class="param-description">참조가 로컬에서 업데이트될 때마다 해당 정보와 함께 콜백이 호출돼요.</p>
+              </li>
+            </ul>
+          </li>
           <li class="param-li">
             <span class="param-name">credential</span><span class="param-type">Credential</span>
             <br>
-            <p class="param-description">libgit2에서 git 자격 증명을 나타내는 인터페이스</p>
+            <p class="param-description">libgit2에서 Git 인증 정보를 나타내는 인터페이스예요.<br><br><code>SSHKeyFromPath</code>에는 <code>privateKeyPath</code>, <code>SSHKey</code>에는 <code>privateKey</code>, <code>Plain</code>에는 <code>password</code>가 필요해요. 빈 비밀번호도 허용하며, 사용자 이름의 기본값은 <code>&quot;git&quot;</code>이에요. 공개 키와 패스프레이즈는 선택 사항이에요.<br><br>인증 정보는 연결 전에 검증하며, 인증이 필요 없는 공개 또는 로컬 리모트에도 적용돼요. 인증이 필요하지 않으면 <code>credential</code>을 생략하세요.</p>
           </li>
           <li class="param-li">
             <span class="param-name">customHeaders</span><span class="param-type">string[]</span>
@@ -230,4 +271,14 @@ class Submodule {
     <br>
     <p class="param-description">작업을 취소하기 위한 선택적 AbortSignal</p>
   </li>
-</ul>
+</ul>
+
+### 에러
+
+<ul class="param-ul">
+  <li class="param-li param-li-root">
+    <span class="param-type">Error</span>
+    <br>
+    <p class="param-description"><code>options.fetch.credential</code>에 <code>type</code>별 필수 필드(<code>SSHKeyFromPath</code>의 <code>privateKeyPath</code>, <code>SSHKey</code>의 <code>privateKey</code>, <code>Plain</code>의 <code>password</code>)가 없으면 <code>InvalidArg</code> 오류가 발생해요. 인증이 필요 없는 리모트에도 적용돼요. update 작업이 실패해도 오류가 발생해요.</p>
+  </li>
+</ul>

docs/reference/Remote/Methods/fetch.md

@@ -78,7 +78,7 @@ class Remote {
           <li class="param-li">
             <span class="param-name">credential</span><span class="param-type">Credential</span>
             <br>
-            <p class="param-description">A interface to represent git credentials in libgit2.</p>
+            <p class="param-description">An interface to represent git credentials in libgit2.<br><br><code>SSHKeyFromPath</code> requires <code>privateKeyPath</code>, <code>SSHKey</code> requires <code>privateKey</code>, and<br><code>Plain</code> requires <code>password</code> (an empty password is allowed). The username defaults<br>to <code>&quot;git&quot;</code>. Public keys and passphrases are optional.<br><br>Credentials are validated before connecting, even for public or local remotes<br>that do not require authentication. Omit <code>credential</code> when authentication is not needed.</p>
           </li>
           <li class="param-li">
             <span class="param-name">customHeaders</span><span class="param-type">string[]</span>
@@ -140,6 +140,16 @@ class Remote {
   </li>
 </ul>
 
+### Errors
+
+<ul class="param-ul">
+  <li class="param-li param-li-root">
+    <span class="param-type">Error</span>
+    <br>
+    <p class="param-description">Throws an  <code>InvalidArg</code>  error if  <code>options.fetch.credential</code>  is missing a field required by its  <code>type</code> <br>( <code>privateKeyPath</code>  for  <code>SSHKeyFromPath</code> ,  <code>privateKey</code>  for  <code>SSHKey</code> ,  <code>password</code>  for  <code>Plain</code> ),<br>even if the remote does not require authentication. Throws an error if the fetch fails.</p>
+  </li>
+</ul>
+
 ## Examples
 
 ```ts