# Vault 연동

> 이미 HashiCorp Vault를 쓰고 있다면 토큰을 Vault에 두고 참조만 남길 수 있습니다.

## 언제 쓰나

기본 방식(패스프레이즈로 암호화한 `secrets.json`)은 별도 서버 없이 동작합니다. Vault를 이미 운영하고 있다면 토큰을 Vault KV v2에 두는 편이 낫습니다.

- 토큰을 Vault에서 바꾸면 리포나 다른 컴퓨터를 손대지 않아도 다음 MCP 서버 실행부터 새 값이 쓰입니다.
- 접근 권한과 감사 기록을 Vault 정책으로 관리할 수 있습니다.

## 설정

```sh
aisync vault login --addr https://vault.example.com
```

Vault 토큰을 묻고, 확인한 뒤 키체인에 저장합니다. `VAULT_TOKEN` 환경변수가 있으면 그 값을 씁니다. 이 토큰에는 쓸 경로의 읽기 권한이 필요하고, capture로 토큰을 옮겨 넣으려면 쓰기 권한도 필요합니다.

## 올리면서 Vault로 옮기기

```sh
aisync capture default --vault claude/aisync
```

MCP 서버에서 찾은 토큰을 `claude/aisync/<서버>-<키>` 경로(KV v2 마운트 `claude`)에 `value` 필드로 넣고, 설정에는 이런 참조를 남깁니다.

```json
"SLACK_BOT_TOKEN": "{{vault:claude/aisync/slack-slack_bot_token#value}}"
```

직접 쓸 수도 있습니다. 형식은 `{{vault:<마운트>/<경로>#<필드>}}`이고, 필드를 생략하면 `value`입니다.

## 다른 컴퓨터에서

```sh
aisync vault login --addr https://vault.example.com
aisync pull default
```

Vault에 로그인하지 않은 컴퓨터에서는 받기가 멈추고 무엇이 필요한지 알려 줍니다. 받은 뒤에는 Claude Code가 서버를 띄울 때마다 aisync가 Vault에서 값을 읽어 건넵니다.

## 확인한 동작

실제 Vault(1.18)에서 다음을 확인했습니다.

- capture가 토큰을 Vault에 넣고, 리포에는 참조만 남김
- 다른 컴퓨터에서 Vault 로그인 전에는 받기를 거부
- 받은 뒤 `aisync exec`, `aisync headers`, 실제 `claude mcp list`가 Vault의 값을 서버에 전달
- Vault에서 값만 바꿨을 때 받기 없이 다음 서버 실행부터 새 값 사용

## 어떤 Vault든 쓸 수 있지만, 조건이 있습니다

`--addr`로 주소를 정하므로 직접 운영하는 Vault도 됩니다. 지금 버전은 다음 조건에서 동작합니다.

| 항목 | 지원 |
|---|---|
| 시크릿 엔진 | KV v2만. KV v1 마운트는 읽지 못합니다 |
| 로그인 | Vault 토큰만. OIDC, AppRole, userpass 같은 로그인 방법은 아직 없습니다 |
| 토큰 만료 | aisync는 토큰을 갱신하지 않습니다. 만료되면 MCP 서버가 뜨지 않으니 periodic 토큰을 쓰고 다시 `vault login` 하세요 |
| 인증서 | 시스템이 신뢰하는 인증서만. 자체 서명 인증서는 지정할 수 없습니다 |
| Enterprise 네임스페이스 | 지원하지 않습니다 |
| 서버 수 | 컴퓨터마다 Vault 주소 하나 |

토큰에는 필요한 경로만 허용하는 정책을 붙이세요. 루트 토큰을 설정에 두면 그 컴퓨터가 뚫렸을 때 Vault 전체가 열립니다.