Durable agent의 보안

실험적 기능입니다. 와이어, SDK 및 이 페이지는 향후 마이너 릴리스에서 변경되거나 기능이 제거될 수 있습니다. Durable agent에 유지 여부를 결정하는 기준이 명시되어 있습니다.

durable agent는 사용자가 실행하거나 배포하는 코드이며, Collie는 해당 텍스트를 신뢰할 수 없는 텍스트로 취급합니다. 이 페이지에서는 durable agent가 접근할 수 있는 대상, 다른 프로세스의 접근을 차단하는 요소, Collie가 해당 텍스트를 처리하는 방식, 감사 로그에 보관되는 내용을 설명합니다. Collie 전반에 관한 내용은 보안에서 다룹니다.

durable agent가 할 수 있는 작업과 할 수 없는 작업

durable agent가 묻고, 페어링된 기기가 결정합니다. durable agent는 사용자가 답변하고 보낸 내용과 통신의 요청을 수신합니다. Collie는 durable agent가 터미널로 진입할 수 있는 경로를 제공하지 않습니다.

사람이 직접 탭해야만 질문에 답변할 수 있습니다. 답변 라우트는 쓰기 게이트 뒤에 있는 페어링된 기기에서만 실행되며, 브리지의 어떤 요소도 durable agent, 훅 또는 모델 출력을 위해 이를 호출하지 않습니다. 휴대전화에서는 'Always allow'를 선택하려면 두 번 탭해야 합니다. 이 권한을 제공하는 durable agent는 가장 주의를 기울여야 하는 권한을 보유하게 됩니다. 적대적인 도구의 답변 한 번으로 이후의 모든 호출이 질문 없이 통과될 수 있기 때문입니다.

승인된 작업이 수행하는 동작은 Collie가 아니라 durable agent가 강제합니다. durable agent의 버튼은 해당 durable agent의 권한으로 실행되며, Collie는 탭 이벤트만 전달합니다.

durable agent는 잠금 화면을 도배할 수 없습니다. Collie는 durable agent와 도구 호출을 키로 삼아 각 질문을 한 번만 결정하고, 최대 한 번만 푸시합니다. 대화당 분당 3회, 호스트당 분당 10회, 호스트당 시간당 30회의 푸시를 허용합니다. 31번째가 될 푸시는 요약 푸시 1건으로 전환되며, 호스트는 이후 1시간 동안 더 이상 푸시를 보내지 않습니다. 카드는 항상 표시됩니다.

주의. 동일한 사용자는 소켓을 통해 질문에 답변할 수 있습니다. 소켓은 다른 사용자를 차단하지만 사용자의 자체 프로세스는 차단하지 못하며, 여기에는 에이전트가 실행하는 도구도 포함됩니다. 자손 검사는 durable agent 자체의 방어 수단이며, Collie는 durable agent가 이를 실행하는지 여부를 알 수 없습니다.

이 검사를 사용하면 durable agent는 자신, 자신이 시작한 프로세스, 그리고 이들과 구별할 수 없는 호출자로부터 수신된 answer, send, abort, action, rename, close, reopen, starter 요청을 거부합니다. 거부 응답은 403 caller-refused이며, 읽기 작업은 계속 열려 있습니다. 이 검사는 SDK가 소켓의 호출자를 읽을 수 있는 Linux 환경의 Bun이 필요합니다. 아래 표는 durable agent가 실행되는 위치에 따라 강제되는 동작을 나타냅니다.

에이전트의 도구를 소켓에 접근할 수 없는 샌드박스에 배치하거나, 카드를 게이트가 아닌 단순 알림으로 취급하거나, Bun에서 durable agent를 실행하십시오. callerCheck: "off"은 검사 없이 실행하도록 durable agent가 자체적으로 선택하는 것입니다.

소켓 전송

비공개 소켓은 다른 모든 사용자를 차단하며, 유일한 게이트는 경로입니다.

ls -ld /run/user/1000 /run/user/1000/desk /run/user/1000/desk/app.sock

소켓에는 토큰과 Authorization 헤더가 전달되지 않습니다. Collie는 전체 경로가 비공개일 때만 연결하며, 매 연결 전에 /부터 하위 방향으로 lstat을 사용하여 이 탐색을 실행하므로 링크를 따라가지 않습니다.

실패한 경로는 유예 없이 즉시 접근할 수 없게 됩니다. collie doctor은(는) durable-socket 행에 동일한 검사 이름을 표시하고 해결 방법을 안내합니다. 아무것도 없는 경로는 no socket at <path>을(를) 읽으며, 이는 개인정보 보호 오류가 아닙니다.

SDK로 빌드된 durable agent는 소켓 폴더가 없으면 0700 모드로 생성합니다. 다른 모드로 이미 존재하는 폴더에서는 시작을 거부합니다. 소켓을 0600 모드로 설정하고, 수신 대기 전에 비정상 종료된 소켓 파일을 제거합니다.

소켓 전송은 Linux 및 macOS 전용입니다. Windows에는 소켓 전송이 없으므로 토큰 전송을 사용하십시오.

토큰 전송

URL과 토큰으로 다른 호스트의 durable agent에 접근하며, 토큰이 접근 제어의 전부입니다.

openssl rand -hex 32

토큰을 가진 사람은 누구나 본인의 휴대전화 역할을 하게 됩니다. 모든 대화를 읽고, 질문에 답하고, 텍스트를 보내고, 턴을 중단하고, 이름을 바꾸거나 닫고, 스타터를 실행할 수 있습니다. 인터넷에서 들어오는 TLS 연결에는 확인할 호출자가 없으므로, 여기에는 하위 프로세스 검사가 존재하지 않습니다. 이러한 방식으로 접근하는 durable agent는 항상 허용을 제공해서는 안 되며, 허용 및 거부만 제공해야 합니다.

호스트는 텍스트를 볼 수 있습니다. TLS는 호스트에서 종료되므로 호스트는 헤더의 토큰을 포함한 각 요청을 볼 수 있으며, 대화 내용은 해당 호스트의 스토리지에 저장됩니다.

Collie는 토큰을 일반 텍스트로 두 곳에 보관합니다. sources.json은(는) 항목용으로 보관하며, 설정 폴더를 백업하거나 동기화하면 함께 복사됩니다. Collie는 해당 파일을 0600 모드로 유지하고, 권한이 더 열려 있는 파일은 시작 시 로그에 한 줄을 남기며 권한을 축소합니다. 그룹이나 기타 사용자가 읽을 수 있는 파일이 있으면 collie doctor에 빨간색 sources 행이 표시됩니다. durable 전용 형식은 .env 또는 config.toml에 보관하며, 이를 담고 있는 파일은 반드시 0600 모드여야 합니다. Collie는 토큰을 절대 출력하지 않습니다. collie durable list에는 (token set), collie doctor에는 set, <n> bytes(으)로 표시되며, 어떤 오류나 로그에도 값이 포함되지 않습니다. attach은(는) --token-env이(가) 지정한 변수에서 토큰을 읽으므로 명령줄에 노출되지 않습니다.

토큰은 만료되지 않습니다. 토큰을 순환하려면 Collie를 재시작하기 전에 durable agent에 새 토큰을 전달하십시오. 그렇지 않으면 휴대전화에 durable agent가 거부했다는 메시지가 표시됩니다. durable agent는 순환이 진행되는 동안 두 번째 토큰을 수용할 수 있습니다. 파킹된 Cloudflare 예제는 COLLIE_TOKEN을(를) 받고, 설정되어 있는 동안 COLLIE_TOKEN_NEXT(ADR 0103)도 받습니다. 단계는 토큰에 설명되어 있습니다.

이는 Collie가 설정된 URL로 보내는 아웃바운드 호출이며, 아무것도 첨부하지 않음으로써 거부됩니다. 각 요청에는 Authorization: Bearer <token>, 통신 규격 버전, 마지막으로 읽은 ETag가 포함되며, 탭의 경우 답변하거나 전송한 본문이 포함됩니다. 읽기는 본문이 없는 GET입니다.

https를 통한 모든 폴링은 호스트에서 비용을 청구할 수 있는 요청이며, "변경 사항 없음" 응답 역시 요청 수에 포함됩니다. 휴대전화가 열려 있지 않으면 유휴 폴링이 10초마다 실행되므로 Collie는 하루에 8,640회 요청을 보내며, 휴대전화로 보고 있는 동안에는 2초마다 요청을 보냅니다. 중단되었거나 토큰을 거부하는 durable agent에는 최대 10초에 한 번 요청하며, 이러한 요청에도 비용이 청구됩니다. Collie가 하루 종일 폴링하는 durable agent에는 유료 요금제를 사용하십시오.

Collie가 durable agent의 텍스트를 처리하는 방식

Collie는 다른 컴포넌트가 읽기 전에 durable agent에서 전달된 모든 문자열을 정리하고 텍스트로 렌더링합니다.

durable agent는 상한선 내의 문자열을 보내야 합니다. Collie는 에이전트가 이를 준수했다고 신뢰하지 않습니다. 각 문자열은 세 단계를 거칩니다.

1. 01
   제어 문자가 제거됩니다. Collie가 C0 제어 문자, DEL 및 C1 제어 문자를 제거합니다. 여러 줄을 포함하는 필드인 항목 텍스트, 도구 호출 출력 및 요약, 질문 사유에서는 줄바꿈과 탭을 유지합니다.
2. 02
   비가시 문자 및 방향 문자가 제거됩니다. Collie가 방향 표시 문자 U+200E, U+200F, U+061C, 재정의 및 격리 문자 U+202A~U+202E 및 U+2066~U+2069, 너비가 0인 문자 U+200B~U+200D, 단어 결합자 U+2060, 바이트 순서 표시(BOM) U+FEFF, 그리고 보이지 않는 문장 전체를 전달할 수 있는 태그 문자 U+E0000~U+E007F를 제거합니다.
3. 03
   문자열이 잘립니다. Collie가 온전한 문자 단위로 바이트 상한에 맞게 자르고 끝에 …을 붙입니다.

정리 과정에서 제목이나 사유가 변경된 질문 카드는 "Text shortened" 표시를 가집니다. 남은 단어가 없는 옵션이나 벨트 버튼은 제외되므로 빈 버튼이 표시되지 않습니다. 비어 있는 필드는 id로 명명됩니다.

Id는 정리되거나 잘리지 않습니다. id는 제어 문자, 공백 및 /, ?, # 문자가 없는 1~128바이트여야 하며, 그렇지 않으면 해당 id를 가진 객체는 삭제됩니다.

Collie는 텍스트를 있는 그대로 표시합니다. markdown 항목은 제목, 목록, 강조, 코드 범위 및 링크를 표시하며 원시 HTML은 렌더링되지 않습니다. 태그는 문자 그대로 표시됩니다. markdown 항목 내부의 링크는 웹 주소만 엽니다. link 항목에는 호스트가 포함되고 사용자 이름이나 비밀번호가 없으며 공백, 제어 문자 또는 보이지 않는 문자가 없는 최대 2048자의 https:// 주소가 필요합니다. 그렇지 않으면 Collie는 해당 항목을 버리고 대화당 한 줄씩 로그에 기록합니다. 이미지와 파일은 항목이 아닙니다.

로그에 기록되는 내용

Collie는 휴대전화가 영구 에이전트에 기록하는 모든 쓰기 작업을 <state-dir>/audit.log 모드 0600에 기록합니다.

각 줄에는 영구 에이전트의 이름이 session으로, 페어링된 기기 및 이벤트가 표시됩니다.

대화나 탭을 닫고 이름을 변경하는 작업은 일반적인 이벤트인 pane.close, pane.rename, tab.rename를 사용합니다. COLLIE_AUDIT_CONTENT=none은 요청 ID와 같은 몇 가지 명명된 필드를 제외한 상세 정보의 모든 문자열을 수정하므로, send의 미리보기도 함께 수정됩니다. 로그는 사후에 발생한 일을 보여줍니다. 어떤 작업도 차단하지 않습니다.

Collie는 또한 사용자가 입력한 텍스트 없이 각 응답, 전송, 중지, 버튼 탭 및 스타터에 대한 영수증을 보관합니다. 보관 기간은 Collie가 durable agent의 데이터를 보관하는 위치에 명시되어 있습니다.