SQUIDSHELL / DEVELOPERS
연결하고, 확인하고, 실행하세요.
에이전트 인증부터 암호화된 금고까지. 흐름을 직접 살펴보고, 프로젝트에 맞는 예제를 가져가세요.
첫 요청부터 확인하기
인증 없이 공개 API를 실행해 응답 구조를 확인하세요. 금고를 바로 연결하려면 아래 설치 예제로 이동할 수 있습니다.
SDK 설치·금고 연결로 이동 ↓curl --fail-with-body 'https://api.squidshell.com/v1/desktop-clients'성공 응답은 message_code: 100과 data를 포함합니다. HTTP 상태와 message_code를 함께 확인하세요. 플랫폼별 다운로드 버전은 서로 다를 수 있습니다.
인증과 복호화는 별개입니다.
단계를 선택해 각 주체가 무엇을 보관하고 검사하는지 확인하세요.
키 발급
계정 세션으로 마이페이지에 로그인해 에이전트별 키를 만듭니다. 금고, 권한, 만료일을 지정하고 발급 시 한 번 표시되는 값을 비밀 저장소에 넣으세요.
Account session → /dashboard/api-keys서버에 접근할 권한
마이페이지에서 발급·폐기. 서버는 해시를 저장합니다.
내용을 복호화할 열쇠
SDK가 로컬 생성. 서버에 전송하지 않습니다.
조건을 바꾸면 서버가 어떻게 판단하는지 확인할 수 있습니다. 요청 형식이 올바르고 사용량 한도를 넘지 않은 경우를 가정합니다.
이 조건에서는 요청이 허용됩니다. 암호문을 읽어도 복호화 키는 별도로 필요합니다.
자신의 키로 인증 확인
실제 키는 이 페이지에 입력하지 않습니다. OS·CI 비밀 저장소에서 환경 변수로 주입한 뒤 로컬 터미널에서 실행하세요.
curl --fail-with-body 'https://api.squidshell.com/v1/agent/vaults/YOUR_VAULT_UUID/content' \
-H "Authorization: Bearer $SQUIDSHELL_API_KEY"금고 연결부터 에이전트 실행까지
단계와 CLI·SDK 형식을 선택하면 해당 코드가 바뀝니다. 실제 비밀값은 비밀 저장소에서 공급하고 모델 컨텍스트에는 넣지 마세요.
설치
Node.js 24 이상에서 프로젝트에 SDK를 설치하세요. CLI는 같은 패키지에 포함됩니다. 현재 0.1.0 베타입니다.
npm install squidshell-sdk@0.1.0Windows에서는 Node.js SDK 예제를 사용하거나 셸 문법에 맞게 CLI 줄바꿈·경로를 바꾸세요.
서버에는 무엇이 보일까요?
아래 가짜 값으로 AES-256-GCM 암호화·복호화를 직접 실행합니다. 실제 요청을 보내지 않으며 새로고침하면 데모 키가 사라집니다. 실제 금고 작업은 위 Node.js SDK·CLI를 사용하세요.
[
{
"name": "deploy-token",
"value": "DEMO_ONLY_NOT_A_REAL_SECRET"
}
]암호화를 실행하면 여기에 표시됩니다.
암호화부터 시작해 보세요.
교체·공유·복구
필요한 상황을 펼쳐 운영 절차와 보호 범위를 확인하세요.
API 키만 정기 교체하려면?
- 같은 금고에 필요한 최소 권한으로 새 에이전트 키를 발급합니다.
- 비밀 저장소의 키를 교체하고 /agent/me 및 실제 읽기를 확인합니다.
- 확인 후 이전 API 키를 폐기합니다. 유출된 키라면 이전 키 폐기를 먼저 진행하세요.
API 키 교체는 금고 암호화 키를 바꾸지 않습니다.
금고 키까지 유출됐다면?
관련 API 키를 폐기하고 새로 발급한 읽기·쓰기 키로 rotate를 실행합니다. 새 키 파일을 승인된 에이전트에만 전달하고, 금고 안에 들어 있던 실제 서비스 비밀값도 교체하세요.
교체는 앞으로의 스냅샷을 보호합니다. 이미 복사된 평문이나 이전 키·암호문을 지울 수는 없습니다.
키 교체 코드 보기 ↑다른 에이전트와 금고를 공유하려면?
에이전트별로 별도의 API 키와 금고 접근 권한을 부여합니다. 암호화된 키 파일과 비밀번호는 신뢰할 수 있는 별도 경로로 전달하세요. 현재 베타는 기기 페어링이나 서버 중계 공개키 공유를 제공하지 않습니다.
동일한 금고 키 보유자는 얻은 스냅샷의 모든 항목을 복호화할 수 있습니다. 권한 경계가 다르면 금고도 나누세요.
키 파일이나 비밀번호를 잃으면?
암호화된 키 파일과 비밀번호를 각각 백업하고 실제 복구를 연습하세요. 모든 사본을 잃으면 서버도 금고 내용을 복구할 수 없습니다. API 키 재발급으로 복호화 키가 복구되지는 않습니다.
현재 보안 범위와 한계는?
- 이름·값은 AES-256-GCM으로 함께 암호화합니다. 금고 UUID·revision·키 식별자는 인증된 부가 데이터에 바인딩됩니다.
- 서버는 금고 표시 이름, 소유자, 크기, revision, 키 식별자, 시간·접근 메타데이터를 볼 수 있습니다.
- 로컬 키 파일은 scrypt(N=131072, r=8, p=1)와 AES-256-GCM으로 보호합니다. POSIX는 0600 권한·심볼릭 링크 검사를 적용하며 Windows ACL은 별도 확인이 필요합니다.
- 서버는 암호문을 복호화하거나 암호학적으로 검증하지 못합니다. 형식·권한·revision·크기·nonce 재사용만 검사하므로 쓰기에는 SDK를 사용하세요.
- SDK는 같은 인스턴스의 최고 revision 또는 minimumRevision보다 낮은 응답을 거부합니다. 별도 체크포인트가 없는 새 클라이언트에 대한 영구적인 롤백 방지는 아닙니다.
- 독립 보안 감사를 받은 제품 또는 1Password 동등 인증으로 소개하지 않습니다. 기존 데스크톱 SSH 키 저장 방식과는 별도입니다.
API와 오류 처리
| 경로 | 조건 |
|---|---|
GET /v1/agent/me | 유효한 에이전트 API 키 |
GET /v1/agent/vaults/{id}/content | vault:read + 금고 허용 |
PUT /v1/agent/vaults/{id}/content | vault:write + 금고 허용 + If-Match |
PUT은 암호문 envelope만 받습니다. SDK가 If-Match와 암호화를 처리합니다. 평문 스냅샷 한도: 1 MiB / 1,000개 항목.
| 결과 | 다음 조치 |
|---|---|
401 | 키 형식·만료·폐기·계정 상태를 확인합니다. |
403 | 필요한 vault:read / vault:write 권한을 확인합니다. |
404 | 금고 UUID와 명시적 접근 허용을 확인합니다. |
409 | 최신 스냅샷을 다시 읽고 변경을 재적용합니다. 무조건 재전송하지 마세요. |
413 / 429 | 크기 한도를 확인하거나 Retry-After에 따라 재시도합니다. |
KEY_MISMATCH / INTEGRITY | 금고 키·암호문 무결성을 확인합니다. 검증 실패 시 평문을 사용하지 않습니다. |
AI용 원문 문서
사람이 읽는 설명과 예제는 위 페이지에서 모두 확인할 수 있습니다. 아래는 LLM·도구가 가져가기 위한 Markdown 원문입니다.