인증·인가, 시크릿, 네트워크, 모델 입력과 저장 데이터의 보안 경계를 설명한다. 설정만으로 보장하는 것과 배포 환경이 책임지는 것을 구분한다.

관련 문서: 여기서 언급하는 변수는 CONFIGURATION.md, 엔드포인트별 인가는 API.md, 조각들이 어떻게 맞물리는지는 ARCHITECTURE.md.

Better Auth의 advanced.cookiePrefix는 agent-studio다. 기본 세션 쿠키는 agent-studio.session_token이며 HTTPS 설정에서는 __Secure-가 붙는다. 페이지 게이트도 같은 접두어를 사용한다. Agent Memory의 agent-memory 쿠키와 분리하며 이전 better-auth 쿠키는 읽지 않는다. 접두어 변경을 배포하면 기존 브라우저 세션은 다시 로그인해야 한다.

멀티 도메인 로그인은 BETTER_AUTH_ALLOWED_HOSTS의 정확한 호스트만 허용한다. config.authBaseUrl이 BETTER_AUTH_URL의 프로토콜과 허용 목록을 Better Auth에 전달하고, 요청의 보존된 Host(없으면 request URL)로 콜백을 결정한다. 전달된 호스트·프로토콜 헤더는 신뢰하지 않는다. 세션·OAuth state 쿠키는 host-only이며 HTTPS이면 Secure다. 로그인 실패의 상대 Location: /login?error=도 콜백 도메인을 유지한다. 설정·provider 등록은 설치 절차를 따른다.

Better Auth 1.7은 앱의 커넥션 풀 위에서 라이브러리 자신의 Postgres 어댑터로 돈다. user, session, account, verification 은 그것이 소유하는 테이블이고(migrations.ts 가 만든다), email·token 의 유일성은 테이블의 유니크 제약이다.

계정의 식별자는 providerId + accountId이며 이 조합에 unique index를 둔다. issuer는 기존 값을 보존하는 nullable 이력 컬럼이고 새 계정에는 쓰지 않는다. 같은 계정 키의 중복은 unique index가 거부한다. 서로 다른 사용자를 자동 병합하거나 provider를 임의로 바꾸지 않는다.

로그인 수단은 전부 선택이고 설치가 고른다 (src/lib/config.ts 의 authProviders, 그대로 auth.ts 와 로그인 페이지로):

Keycloak·표준 OIDC·Google을 함께 설정하면 각 로그인 버튼을 표시한다. Keycloak은 discovery의 issuer·JWKS가 있어야 등록하며 ID 토큰의 서명·issuer·audience와 요청별 nonce를 Better Auth가 검증한다. 로그인 버튼은 설정의 존재를 나타내므로 discovery 실패 시에도 표시되지만 인증은 실패한다. 제공자 복구 뒤 앱을 재시작해 discovery를 다시 읽는다. Keycloak issuer는 배포 운영자가 환경 변수로 지정하며 사내 주소를 허용한다. 브라우저와 서버 모두 그 주소에 접근할 수 있어야 한다. Keycloak role을 앱 tier로 매핑하지 않는다. 기존 관리자 설정과 멤버 tier 정책을 적용한다. Keycloak으로 로그인한 사용자의 앱 로그아웃은 앱 세션만 종료하며 Keycloak SSO 세션은 유지한다. Google·OIDC·Keycloak 로그인은 기존 계정에도 제공자의 최신 사용자 정보를 반영해 이름과 프로필 이미지를 갱신한다. 제공자가 사진을 반환하지 않으면 저장된 이미지를 유지한다. 프로필 동기화는 Chat·Agent 소유권에 사용하는 기존 이메일을 변경하지 않는다. 제공자가 새 이메일을 보내면 허용 도메인은 다시 검사하지만, 소유권 이메일과 해당 이메일의 인증 상태는 보존한다. 앱의 tier는 제공자 프로필에서 가져오지 않으며 기존 관리자·등급 정책을 따른다.

STAGE=alpha|prod는 로그인 수단이 하나도 없으면 부팅을 거부한다(assertAccessControlConfig); local 은 scripts/dev-session.ts 가 세션을 만들어 주므로 없어도 된다. 로그인은 수단과 무관하게 ALLOWED_EMAIL_DOMAINS 로 제한된다. 사용자 생성과 세션 생성 양쪽의 훅에서, 그래서 이미 있는 사용자도 도메인이 목록에서 빠지면 다음 로그인에 거절된다. 빈 목록은 모든 도메인을 허용한다. STAGE=alpha|prod 도 그 상태로 정상 부팅한다 (부팅 시 검증 참고).

admin 전용 멤버 목록은 Better Auth 의 user 행을 읽는다. createdAt 은 가입 시각이고, lastLoginAt 은 세션 생성에 성공한 뒤 갱신된다. 그 이전부터 있던 사용자는 다시 로그인하기 전까지 마지막 로그인 값이 없다. 타임스탬프 갱신 실패는 로그에 남지만, 신원 제공자 로그인에 성공한 것을 인증 실패로 바꾸지는 않는다.

src/shared/pageAccess.ts 는 어떤 페이지가 공개인지에 대한 단일 소유자다. /, /login, /guide. 가이드는 로그인 없이 읽는 정적 안내이며, 가이드에서 연결하는 Agent·설정 페이지와 API는 각자의 인증·권한 검사를 유지한다. src/proxy.ts와 브라우저의 만료 세션 redirect가 같은 판정을 읽는다. matcher 가 닿는 나머지 전부는 세션을 요구하므로 새 라우트는 기본이 보호 상태 다. 그 방향은 의도적이다. 공개 페이지를 목록에 넣는 것을 잊으면 사용자가 1분 안에 신고하는 리다이렉트가 생기지만, 비공개 페이지를 넣는 것을 잊으면 조용히 실패한다.

페이지 게이트는 세션 쿠키의 유효성이 아니라 존재 를 확인한다. 유효성까지 확인하려면 모든 내비게이션마다 세션을 읽어야 하고, 그러고도 그것은 인가 결정이 아니다. 인가는 실제로 데이터를 만지는 요청을 보는 withAuth 와 assertAgentOwner 에서 서버 측에 남는다. 따라서 존재하지만 유효하지 않은 쿠키는 페이지에 도달하고 그 뒤의 API 에서 401 을 받는다. 브라우저의 공통 응답 경계는 같은 origin의 /api/* 401을 받으면 현재 path·query·fragment를 next로 보존해 /login으로 full navigation한다. Root layout이 이미 세션을 유효하지 않다고 판정한 보호 페이지도 같은 경로를 탄다. 게이트가 없애는 것은 평범한 로그아웃 상태이며, 그 방문자에게 콘솔 shell이나 API error box를 렌더링하지 않는다.

/api 는 matcher 밖에 있다. 그 라우트들은 스스로 인증하며, 프로그램 호출자에게는 HTML 리다이렉트가 아니라 반드시 401 로 답해야 한다.

next 파라미터는 주소창에서 오므로 /login 은 그것을 safeNextPath(src/shared/safeNextPath.ts)로 되읽는다. //host 와 /\host 를 거부하지 않으면 로그인 플로우가 오픈 리다이렉트가 된다.

로그인 오류는 signInError.ts의 코드로 전달하고 로그인 페이지가 자기 문구로 표시한다. 알 수 없는 error 값은 일반 오류로 바꾸며 제공자의 텍스트나 허용 도메인 목록을 그대로 반사하지 않는다.

Agent 는 공유 카탈로그이되, 공개 범위(visibility)를 갖는다. public(기본값이자 visibility 필드가 없을 때의 의미)은 로그인한 사용자가 조회하고 member 이상이 실행·복제한다. private은 소유자만 접근할 수 있으며 관리자도 실행·복제 권한을 얻지 않는다. 설정 관리 권한은 별도 검사한다. 공개 범위 판정은 src/domain/agent/access.ts의 mayAccessAgent가 소유하고, Agent 조회를 포함한 검사는 assertAgentAccessible을 사용한다.

콘솔·Chat과 개인 API 토큰은 인증된 사용자의 현재 assertAgentAccessible 판정을 적용한다. 개인 토큰은 Agent 소유자가 아니라 발급 사용자 ID에 묶인다. Slack·Telegram·Teams는 전달 인증 후 연결한 Studio 사용자의 현재 계정·member 등급· Agent 접근을 확인한다. 이메일이나 bot 소유자만으로 호출자를 추정하지 않는다. Slack 앱의 채널 키워드 알림은 키워드를 저장한 인증 계정의 사용자 ID와 revision으로 실행한다. 현재 계정·Agent 접근·연동 활성화·등록 revision을 모델·도구·Workspace 효과 전에 다시 검사하며, 키워드 변경·삭제로 권한을 철회한다. 다른 앱의 DM·thread 답글과 봇 자신의 메시지는 실행하지 않는다. Slack의 명령·native 중단·thread-start는 사람의 연결 검사를 지난다. Trigger·Webhook의 전달 인증은 머신 요청 인증을 따른다.

private agent 를 local subagent 로 바인딩 하는 것도 읽기다: 편집자가 접근할 수 없는 agent 는 Agent 설정 저장 시점에 거절된다 (assertSubavailableAgentsAccessible). 이미 바인딩된 참조는 agent 가 뒤늦게 private 이 되어도 편집 가능성을 잃지 않는다. 실행 시점의 transfer 는 현재 호출자의 Agent 접근 권한을 다시 확인한다. 비용 대시보드의 agent 합계 는 visibility 이전처럼 열려 있다: 이름과 지출 집계는 카탈로그 운영의 일부로 남겨 둔 결정이다.

trace 와 Slack 설정은 읽기 도 게이트되는데, 다른 사용자의 런타임 입출력과 마스킹된 자격 증명의 가장자리를 노출하기 때문이다. agent 합계 는 카탈로그가 공유되므로 열어 둔다. 호출자별 내역은 개인을 지목하므로 usage/actors 는 그렇지 않다. capability 레지스트리는 guest도 member와 같은 메뉴에서 조회한다. guest는 Agent·연동·레지스트리·모델 즐겨찾기를 변경하거나 Artifact를 삭제할 수 없으며, 강등된 기존 Agent 소유자에게도 같은 제한이 적용된다. Agent 변경 API는 withMemberAuth와 소유권 검사를 함께 사용한다. 초안 preview와 MCP 연결 테스트는 외부 서비스 요청을 실행하므로 member 이상을 요구한다. Agent 실행·Chat 전송·승인 재개·Workspace 새 작업은 member 이상에게 허용한다. guest는 기존 본인 기록을 조회하고 실행 중단·종료·승인 폐기를 할 수 있다. 실행 중 강등도 새 모델·도구 효과를 차단한다.

설치 공용 자원의 관리자 권한과 Agent 소유권은 별개다. isAdminEmail은 공용 레지스트리·설정의 관리자 목록을 확인하며, 목록이 비면 member 이상에게 초기 관리 권한을 허용한다. isEffectiveAdmin은 이 규칙과 저장된 admin tier를 합친다. isConfiguredAdmin은 ADMIN_EMAILS에 명시된 계정을 찾아 admin 승격과 tier 잠금에 사용한다. 어느 관리자 판정도 다른 사람의 Agent 관리 권한을 부여하지 않는다.

GET /api/me는 email, tier, 공용 자원 관리용 isAdmin을 반환한다. Agent 편집 여부는 isAgentOwner와 tierMayEdit로 판단한다. 서버의 assertAgentOwner가 같은 소유권을 검사한다.

ADMIN_EMAILS에 지정된 주소는 로그인 또는 멤버/프로필 조회 때 admin tier로 승격되고, 목록에 있는 동안 tier가 잠긴다. 목록에서 제거해도 자동 강등하지 않으며 관리자가 등급을 변경한다. tier는 Better Auth user 행의 서버 전용 필드다. 실행은 사용자 ID로 현재 계정·등급·Agent 접근을 확인한다. 이메일 기반 tier 조회의 캐시는 30초이며 변경을 처리한 인스턴스에서 무효화된다.

월 비용 한도는 Settings → Access의 memberTiers와 memberTierLimits가 정한다. admin은 무제한이며 guest는 한도와 무관하게 실행하지 못한다. 나머지 등록 등급은 member 권한을 갖는다. 미등록 등급은 guest로 해석한다. 등급 삭제와 사용자 배정은 공동 transaction lock을 사용하며 사용자가 남은 등급은 삭제할 수 없다. 월 한도는 설정 캐시 TTL에 따라 전파된다.

월 상한은 Chat·Workspace를 포함한 멤버 자신의 일별 행을 UTC 월 1일부터 합산한다. 실행 전에 이미 한도에 도달하면 새 실행을 거절한다. 등급·사용량 조회 실패도 실행을 중단한다. 완료된 사용량을 기준으로 검사하므로 진행 중인 실행이 잔액을 초과할 수 있다. 프로필 페이지가 읽는 것과 같은 창, 같은 행이다. 모든 호출 출처에는 확인된 Studio 사용자가 있고 같은 사용자 ID의 개인 한도를 공유한다. 플랫폼 actor는 출처 기록을 위해 유지한다. 개인 API token은 발급 사용자의 안정적인 ID에 묶이며 인증마다 현재 계정·등급·Agent 접근을 검사한다. 계정 존재 여부와 현재 tier는 이메일 tier 캐시 대신 사용자 ID로 조회한다. 확인된 사용자의 호출 권한 거절은 403, 잘못된 credential이나 삭제된 발급 계정은 401이다. 권한 저장소 장애는 인증을 허용하지 않는다.

Agent 설정·연동·Workspace 정책의 변경과 Agent 관리 자료·Trace·호출자별 Usage 조회는 assertAgentOwner로 소유자를 확인한다. public은 공유 실행 범위이며 편집 권한을 부여하지 않는다. 일반 Artifact는 생성자 또는 해당 Agent 소유자가 관리하며, 비공개 source 파일은 파일 소유자만 접근한다. 조회는 변경 감사 행을 생성하지 않는다.

저장되는 모든 자격 증명. MCP 서버 헤더, Agent별 헤더 오버라이드, MCP OAuth 의 access/refresh token·client secret·인가 중인 PKCE verifier, Slack 봇 token 과 서명 시크릿, Telegram 봇 token 과 webhook 시크릿, Teams(Azure Bot) 클라이언트 시크릿, 개인 API·Webhook token, 그리고 시크릿인 앱 설정(LLM API 키와 plugins 저장소의 GitHub token)은 AES_ENCRYPTION_KEY 로 AES-256-GCM 암호화된다(src/infrastructure/crypto/secretEncryption.ts). 새 값은 모두 enc:v2: 로 쓴다. v2 는 row 와 field 정체성을 AES-GCM AAD 로 묶으므로 암호문만 다른 위치로 옮기면 인증에 실패한다. 기존 enc:v1: 값은 다시 저장하거나 재발급하기 전까지 그대로 읽는다.

개인 credential은 agent + purpose + userId + credentialId에 묶인다. Slack 의 bot token·signing secret, Telegram 의 bot token·webhook secret, Teams 의 app password 는 agent + integration + field 를 쓴다. MCP registry header 는 항목 이름과 header 이름에, managed MCP 의 environment 는 항목 이름과 변수 이름에 묶인다. HTTP header의 override 병합만 이름의 대소문자를 무시하고, AAD 는 environment와 같은 공통 map 규칙에 따라 저장된 키 철자를 그대로 쓴다.

Agent의 MCP header override는 agent + configuration + mcp + server + header에 묶인다. 현재 설정을 같은 Agent에서 수정해도 암호화 문맥은 유지되며 다른 Agent로 복제할 때는 시크릿을 복사하지 않는다.

읽기는 길이를 보존하는 마스크 를 반환한다. 콘솔이 값을 보여 주지 않으면서 어떤 자격 증명이 설정돼 있는지는 보여 줄 수 있게 하기 위해서다:

드러난 두 가장자리가 만나는 일은 결코 허용되지 않는다. 가장자리를 드러내려면 평문이 필요하므로 마스킹은 복호화를 한다. 그것을 호출하는 admin/소유자 게이트가 걸린 읽기 뷰 안에서만이고, 복호화 실패는 에러를 내는 대신 값을 통째로 감춘다. 아무것도 드러나지 않을 만큼 짧은 값은 아예 복호화되지 않으며, 그 판단은 암호문 길이로 내린다(AES-GCM 은 평문 길이를 보존한다).

업데이트 시 마스킹된 값이나 빈 값은 저장된 시크릿을 보존한다. 저장된 상대가 없는 키에 온 마스킹된 값은 버린다. 마스크는 이미 있는 시크릿을 확인해 줄 수만 있고, 만들어 낼 수는 없다. 헤더 오버라이드 맵의 null 은 명시적 제거로 그대로 통과한다. 제거는 시크릿이 아니다. 헤더 이름은 일반 데이터 키로 처리한다. API 검증·암호화 병합·MCP 전송에서 __proto__ 같은 이름도 누락하지 않으며, SDK가 만든 프로토콜 헤더는 등록한 기본 헤더보다 우선한다. 새로 입력한 값은 enc:v1: 또는 enc:v2: 로 시작하더라도 평문으로 취급해 항상 새로 암호화한다. 암호문 접두사는 저장소에서 읽은 값의 형식일 뿐, API 입력이 신뢰할 수 있는 저장 값이라는 증거가 아니다. Agent별 MCP 문자열 오버라이드는 저장 당시 registry URL 의 fingerprint 와 함께 보관한다. 같은 이름의 URL 이 바뀌거나 fingerprint 가 없는 예전 값이면 옛 시크릿을 보내지 않는다. 새 endpoint 용 자격 증명을 다시 입력해야 한다.

이 앱이 발급하는 시크릿 중 둘은 평문으로 되읽을 수 있다:

둘 모두 읽기에도 POST를 사용한다. 응답 본문이 살아 있는 자격 증명이므로 캐시·브라우저 기록· 프리페치 바깥에 둔다. 모든 reveal은 실제 수행자의 email과 함께 감사 행을 남긴다.

따라서 둘은 해시가 아니라 암호화해서 저장되며, 이는 의도된 트레이드오프다. 데이터스토어만으로는 하나도 쓸 수 없지만, 데이터스토어 더하기 AES_ENCRYPTION_KEY 면 쓸 수 있다. 그 키를 테이블 덤프와 살아 있는 agent 자격 증명 사이에 서 있는 것으로 다뤄라. 공용 agent token은 개인 credential로 간주하지 않으며 새 사용자별 토큰을 발급해야 한다.

이 앱이 발급하는 시크릿은 GitHub 의 ghp_/gho_ 처럼 제품과 종류를 밝히는 접두사를 지녀(src/shared/generatedSecret.ts), 유출된 문자열이 무엇을 여는지 추적할 수 있다:

랜덤 secret은 32바이트(256비트)다. 개인 API·Webhook token은 공개 credential UUID와 secret을 함께 사용하며 UUID만으로는 인증되지 않는다. 과거 공용 토큰은 개인 사용자를 추정하는 근거로 쓰지 않는다.

agent token 의 표시용 마스크는 생성 시점에 계산돼 암호문 옆에 저장되므로, token 을 나열하는 데는 복호화 비용이 들지 않는다. 그 마스크는 접두사와 가장자리 문자만 실어 나르며, token 을 복원하기에 충분한 적은 결코 없다.

세션 쿠키가 없는 호출자는 표면별 자격 증명을 사용한다:

하나의 token 이 세 틱을 모두 연다. 세 endpoint 전체에 쓰기 권한을 주는 배포 credential이다. CronJob 이 어떤 schedule 이 도래했는지 물을 수 있게 해 주는 그 문자열이 plugins sync 도 실행하고, 그 sync 는 두 레지스트리 skill 과 MCP 서버. 를 모두 쓴다. 저장소가 선언한 이름을 채택하고 provenance 를 그것으로 다시 쓴다. 그것은 프로브가 아니라 쓰기 자격 증명으로 범위를 잡고 회전시켜라.

trigger 시크릿은 활성화 플래그를 읽기 전에 비교된다. 비활성 trigger 가 틀린 시크릿에 활성 trigger 와 다르게 답할 수 없게 하기 위해서다. 그 차이는 어떤 trigger 가 존재하는지에 대한 오라클이다.

상수 시간 비교는 소유자가 하나, src/shared/timingSafe.ts 이고 tests/architecture.test.ts 가 고정한다.

리플레이 억제는 Slack event_id, Telegram의 agent·bot·update_id, Teams의 agent·App ID·conversation·activity ID를 키로 한 조건부 claim을 사용한다. 완료 claim은 중복을 막고, 실패 또는 만료된 처리 lease는 재전달 시 다시 claim할 수 있다. ACK 후 실행하는 과정과 외부 도구 효과를 하나의 transaction으로 묶지는 않으므로 end-to-end exactly-once를 보장하지 않는다. 플랫폼이 재전달하지 않으면 유실 이벤트를 스스로 복구하는 worker도 없다. Agent webhook의 멱등 계약은 Trigger 설계를 따른다.

Teams signing metadata는 HTTP 성공 응답만 사용한다. 조회 실패도 재시도 간격에 포함하며 만료된 키를 장애 중 인증에 사용하지 않는다. 조회·캐시의 현재 계약은 Teams 설계를 따른다.

JSON 본문은 schema 검증 전에 bounded reader를 지난다. 관리·편집 요청은 Skill 전체 파일 한도에서 파생한 editor 한도, 이미지·문서를 실을 수 있는 실행 요청은 attachment 한도에서 파생한 turn 한도를 쓴다. 모델 등록은 editor 한도를 사용한다. webhook 네 종류는 서명 검증에 필요한 raw 본문을 공통 1MB 한도 아래에서 읽는다. 선언된 Content-Length가 한도를 넘으면 body를 읽지 않고 413을 답하고, chunked body는 누적 바이트가 한도를 넘는 즉시 stream을 취소한다. 256KiB prose allowance를 넘는 큰 실행 본문은 프로세스 단위의 바이트 예산에 과금된다. 예산은 최대 turn 본문 두 개 분량이고, 요청은 자기가 실제로 읽은 바이트만큼만 쓴다. 과금은 파싱부터 run 또는 stream이 입력을 놓을 때까지 유지되고, 연결에서 분리되어 계속 도는 chat은 내부 drain 완료까지 유지한다. 일반 text turn은 아무것도 쓰지 않는다. 예산이 모자라면 body를 취소한 뒤 Retry-After를 포함한 429를 답한다.

예산은 요청 수가 아니라 메모리에 유지하는 큰 본문의 바이트를 센다. 정확한 상한과 소유 파일은 고정 제한을 따른다.

tests/architecture.test.ts는 API route의 직접 request.json()과 request.formData() 호출을 거부한다. Zod의 필드 크기 검사는 파싱 뒤의 값 규칙이지, 파싱 전에 발생하는 메모리 할당 제한이 아니다.

Cookie session으로 인증하는 POST·PUT·PATCH·DELETE는 Origin이 request origin 또는 설정된 PUBLIC_BASE_URL origin과 정확히 같아야 한다. 멀티 도메인에서는 허용 목록에 있는 요청 Host와 인증 설정의 프로토콜로 만든 origin과 정확히 같아야 하며, 다른 허용 도메인의 origin도 거부한다. Origin이 없거나 null이거나 URL로 해석되지 않으면 403이다. 세 session wrapper가 일반 console API를 한 번에 보호하고, agent 실행 API는 Authorization 헤더가 없을 때만 cookie session을 사용하며 같은 검사를 적용한다. bearer token, webhook signature처럼 cookie를 쓰지 않는 머신 호출에는 CSRF 검사를 적용하지 않는다.

리버스 프록시 밖의 origin과 앱이 보는 request origin이 다르면 단일 도메인은 PUBLIC_BASE_URL을 설정하고, 멀티 도메인은 BETTER_AUTH_ALLOWED_HOSTS를 설정한 뒤 원래 Host를 전달한다.

next.config.ts는 일반 경로에 framing 차단 CSP, X-Frame-Options: DENY, nosniff, strict-origin-when-cross-origin을 적용한다. 일반 콘솔에는 script/style의 로드를 제한하는 CSP가 없으므로 이 정책이 script injection까지 차단한다고 보지 않는다.

/api/artifacts/{id}/view와 /api/objects/*는 이 규칙에서 제외하고 각 route가 자체 sandbox 정책을 설정한다. 오류 응답에도 헤더가 필요하다. 라우트의 CSP를 바꿀 때는 전역 헤더가 덮어쓰지 않는지 실제 응답을 확인한다. 파일별 정책은 데이터 노출과 보존을 따른다.

운영자가 등록한 MCP 서버 URL은 src/infrastructure/net/ssrfGuard.ts가 등록 시점과 디스패치 시점 모두 에서 검증한다. 거부되는 것: http(s) 가 아닌 스킴, userinfo 를 실은 URL(https://user:pass@host, 주소 안의 자격 증명은 여기서 무언가를 인증하는 방식이 아니고, 호스트를 다른 것처럼 읽히게 만드는 상투적 수단이다), 그리고 사설·루프백·링크로컬(클라우드 메타데이터 주소 169.254.169.254 포함) 또는 그 밖의 예약 대역으로 해석되는 호스트. DNS 조회가 예외로 실패하면 주소 거부로 바꾸지 않고 호출 실패로 전달한다. 조회가 정상적으로 끝났지만 주소가 없거나 금지 대역을 포함하면 거부한다.

IPv6 는 주소 하나에 철자가 여럿이므로, 텍스트가 아니라 8개 그룹으로 펼친 값으로 판정한다. IPv4 를 안에 담는 접두사(IPv4-mapped, IPv4-compatible, NAT64 64:ff9b::/96, 6to4 2002::/16)는 통째로 막지 않고 담긴 IPv4 로 판정한다 — IPv6 전용 망에서 공인 주소에 닿는 정상 경로가 그것이기 때문이다. 64:ff9b::8.8.8.8 은 통과하고 64:ff9b::10.0.0.1 은 거부된다.

이 registry의 공개 주소 디스패치는 fetchPublicUrl(src/infrastructure/net/publicFetch.ts)을 지난다. 배포가 지정한 LLM·인증·스토리지·카탈로그 endpoint까지 모두 이 가드로 검사하는 것은 아니다. 그 주소들은 배포 설정의 신뢰 경계다.

LLM 제공자 요청은 src/infrastructure/llm/providerFetch.ts에서 모든 redirect를 거부한다. SDK의 채팅·임베딩·이미지 요청, SigV4, decision·rerank·오디오, Workspace의 native 요청과 제공자 discovery·연결 probe가 같은 규칙을 적용한다. 따라서 307/308 응답으로 프롬프트·문서· 오디오·자격 증명을 다른 주소에 다시 보내지 않는다. 제공자는 최종 endpoint로 등록한다.

공개 registry 요청에는 다음 검사를 적용한다:

• DNS는 모든 요청과 redirect 홉에서 다시 확인하고 커넥션을 검증한 주소에 고정한다. 등록 시 검증만으로 연결의 안전을 보장하지 않는다.
• 네이티브 리다이렉트 추종은 꺼져 있고 교차 출처 리다이렉트는 거부한다. 저장된 자격 증명이 다른 호스트로 전달될 수 없게 하기 위해서다.
• 디스패처는 커넥션 재사용을 위해 origin|pinned address 별로 풀링된다. 이것이 캐시하는 것은 전송 계층뿐 이다. 가드는 여전히 요청마다 돌기 때문에, 사설 주소로 해석되기 시작한 호스트는 풀링된 디스패처에 닿기 전에 거부되고, 다른 곳으로 해석되는 호스트는 다른 키를 받는다.

Slack 이미지 업로드의 files.getUploadURLExternal 응답은 HTTPS files.slack.com/upload/v1/ 주소인지 확인한 뒤 바이트를 보내며, 업로드 요청의 redirect는 따르지 않는다.

모델 입력의 이미지는 URL로 가져가지 않는다. 실행 API는 지원하는 이미지 바이트를 요청 안에 인라인으로 받으며, LLM 채널은 모든 image_url이 bounded data: URL인지 마지막으로 다시 확인한다. https://만 검사한 뒤 원격 URL을 제공자에게 그대로 넘기면 요청은 이 앱이 아니라 제공자 네트워크에서 발생한다. 그 경로에는 fetchPublicUrl의 DNS·주소·redirect 검사가 닿지 않으므로 허용하지 않는다. 모델이 웹의 이미지를 읽어야 하면 FetchUrl 도구가 이 앱의 아웃바운드 경계로 바이트를 가져와 같은 inline 형식으로 돌려준다.

공개 URL 이면 무엇이든 허용된다. 신뢰하는 엔드포인트만 등록하라. Registry endpoint URL 은 userinfo, query parameter 와 fragment 를 받지 않는다. 이 값들은 멤버가 읽는 registry view 와 운영 로그에서 자격 증명을 노출하기 쉬우므로, 인증 정보는 encrypted header 또는 OAuth 연결에 둔다. 이전 행에 남은 userinfo, query 와 fragment 는 저장된 주소에만 남고 reader-facing view 에서는 제거한다. 이 규칙은 주소가 실제로 바뀔 때만 적용한다. 저장된 주소를 그대로, 또는 콘솔이 보여 준 redacted 형태로 되돌려 보내는 저장은 이동이 아니므로 거절하지도, 저장된 credential 을 버리지도 않는다 (resolveRegistryUrlPatch). 그러지 않으면 편집 폼이 자기가 읽은 값을 되돌려 보내는 것만으로 레거시 항목이 다른 endpoint 를 가리키게 되고, 원래 주소는 다시 입력할 수도 없다. LLM provider의 이름·종류·endpoint·인증 방식과 credential은 한 보안 단위다. 등록 provider의 endpoint·종류·인증 방식을 바꾸면 기존 key의 마스크·빈 입력으로 옮길 수 없다. key가 필요한 새 연결에는 새 값을 입력하며 SigV4는 API key 없이 AWS credential chain을 사용한다. 실행 모델은 Settings에서 선택한 등록 모델이어야 한다. 기본 모델 선택이 별도 기본 채널을 만들지는 않는다.

MCP 클라이언트는 @modelcontextprotocol/client 위에서 돌고, 가드는 그 옆에 놓이는 대신 그 안으로 주입된다. 트랜스포트에 fetch 로 주어지는 것이 boundedFetch(src/infrastructure/mcp/session.ts)이므로 프로브, 핸드셰이크, 모든 도구 호출, 세션 해제까지 전부 같은 경계를 지난다. SDK 를 자기 fetch 에 맡겨 두면 운영자가 넣은 URL 을 곧장 네트워크로 가져갈 것이다. 같은 래퍼가 응답 바이트 상한도 함께 나르는데, SDK 에는 그런 개념 자체가 없다.

클러스터에서 이 앱이 부르기로 되어 있는 MCP 서버들은 구조상 사설이다. Kubernetes Service 는 가드가 거부하는 ClusterIP 로 해석된다. MCP_INTERNAL_HOST_SUFFIXES 는 배포가 그 이름들이 무엇인지 밝히는 방법이다:

MCP_INTERNAL_HOST_SUFFIXES=agent-mcps.svc.cluster.local

로컬 앱의 MCP를 연결하려면 localhost를 명시적으로 추가한다. 예를 들어 MCP_INTERNAL_HOST_SUFFIXES=agent-mcps.svc.cluster.local,localhost는 http://localhost:3100/api/organizations/opspresso/mcp를 허용한다. localhost는 정확히 그 호스트만 허용하며 하위 도메인과 IP 주소는 포함하지 않는다. 기본값은 계속 차단이며, 이 MCP 설정을 추가해도 모델의 FetchUrl 허용 목록은 바뀌지 않는다.

선언된 접미사 아래의 호스트는 그 질문이 던져지는 모든 곳에서 public URL 가드를 건너뛴다. 항목을 등록할 때와 편집할 때, 콘솔의 "Test connection" 프로브, admin 이 항목의 OAuth 메타데이터를 읽을 때, agent 자신의 도구 목록, 그리고 디스패치. 각각 skipsUrlGuard 를 통해서다. 차단된 주소 대역이 넓어지는 것은 아니다. 다른 모든 항목은 여전히 원래 받던 검사를 받는다. 이것은 가드를 느슨하게 하는 것이 아니라 managed 루프백 옆에 놓인 두 번째 좁은 예외다.

내부 주소 예외도 자동 redirect 추종은 허용하지 않는다. MCP 세션·OAuth 메타데이터·내부 FetchUrl은 src/infrastructure/net/redirectPolicy.ts의 fetchSameOrigin을 통해 최대 5회만 같은 출처로 이동한다. 공개 URL도 같은 redirect 규칙을 사용하며, 각 요청 직전에 DNS를 검증하고 확인된 주소로 연결한다. 다른 출처로 이동하는 응답은 본문을 해제한 뒤 거부한다.

이름을 맞추는 술어는 하나다. src/domain/security/internalHosts.ts 의 isDeclaredInternalHost. 그리고 목록은 둘이다. MCP_INTERNAL_HOST_SUFFIXES 는 이 앱이 부르기로 되어 있는 서비스를, URL_FETCH_INTERNAL_HOST_SUFFIXES 는 모델이 읽어도 되는 페이지를 말하고, 두 목록은 의도적으로 서로를 모른다. 술어가 domain 의 중립 모듈에 있는 이유가 그것이다: skipsUrlGuard(MCP 쪽, provenance 와 합친 형태) 옆에 두면 FetchUrl 리더가 MCP 모듈을 import 하게 되는데, 그 리더는 MCP 목록을 읽어서는 안 된다.

그 좁음이 설계의 전부이고, 각 부분은 tests/internalHosts.test.ts 가 고정한다:

• 설정으로만. 목록은 환경에서 온다. 레지스트리 항목이 자기 예외를 스스로 지정할 수 없고, 의도적으로 런타임 설정이 아니다. 아웃바운드 경계를 넓히는 일은 그때 admin 을 쥔 사람이 제출하는 폼이 아니라 배포를 거쳐야 한다.
• 레이블 단위로 고정. agent-mcps.svc.cluster.local 은 mcp-url-fetch.agent-mcps.svc.cluster.local 을 허용하고 evil-agent-mcps.svc.cluster.local 은 거부한다. 단순한 "…로 끝난다"였다면 통과시켰을 아슬아슬한 경우다. 앞에 붙은 점은 허용되며 같은 뜻이다.
• 단일 레이블 접미사는 없다. local 이나 internal 은 이름 공간 하나를 통째로 허용하게 된다. 의도라기보다 오타일 가능성이 훨씬 높으므로 존중하지 않는다. 명시한 localhost만 정확한 호스트 일치로 허용하며, 접미사로 확장하지 않는다.
• IP 리터럴은 결코 안 된다. 그 예외는 누군가 게시한 이름을 위한 것이다. 주소에는 맞출 이름이 없으므로, 사설 주소는 여전히 provenance 로 자기 길을 얻어야 한다.
• http(s) 만, 그리고 userinfo 로 호스트 검사를 지나쳐 접미사를 밀반입할 수 없다.

그 대가: 그 접미사 아래의 호스트는 admin 이 저장할 수 있는 어떤 URL 로도 도달 가능해지고, 그것이 바로 가드가 평소에 없애는 능력이다. 그 서버들을 실제로 돌리는 네임스페이스만큼 접미사를 구체적으로 유지하라.

managed MCP 서버(runtime: "managed")는 이 앱이 자기 호스트에서 직접 띄운 컨테이너이고 127.0.0.1:<port> 로 닿는다. 운영자가 타이핑한 것이라면 가드가 정확히 거부할 주소다. 신뢰는 대신 provenance 에 놓인다. 프로비저너가 포트를 바인딩한 뒤 그 주소를 기록했다.

isManagedLoopback(src/domain/mcp/types.ts)이 이 우회가 적용되는지를 결정하는 유일한 자리이고, 의도적으로 좁다. 항목은 managed 를 주장해야 하고 그리고 리터럴 루프백 주소를 지녀야 한다:

• 127.0.0.1 로 해석되는 호스트명은 거부된다. 확인과 요청 사이에 다른 곳으로 해석될 수 있다.
• 루프백을 가리키는 remote 항목은 거부된다. 그 주소는 타이핑된 것이다.
• 레지스트리는 managed 항목의 URL 을 옮기기를 거부한다.
• 라이프사이클 use case 는 프로비저너가 보고하더라도 루프백이 아닌 주소를 저장하기를 거부하고, 그것이 지목한 컨테이너를 정지시킨다. 정지까지 실패하면 원래 거부와 cleanup 실패를 함께 드러내며 컨테이너가 정리됐다고 주장하지 않는다.

프로비저너는 이미지 레퍼런스, 포트, 그리고 선택적인 argv 배열 을 받는다. 셸 명령은 결코 받지 않는다. 유일한 런타임인 Docker 프로비저너(MANAGED_MCP_RUNTIME=docker, src/infrastructure/mcp/dockerProvisioner.ts)는 argv 를 execFile 로 Docker CLI 에 배열째 넘기고, 구조적으로 쓰이는 값. 이름(MANAGED_NAME), 이미지 레퍼런스, 환경 키·값, argv, endpoint path. 은 src/domain/mcp/provisioner.ts의 패턴으로 API 입력과 Docker 실행 양쪽에서 검사한다. 항목을 편집할 수 있는 운영자가 그것으로 호스트에서 임의 코드를 돌릴 수는 없어야 한다. 호스트 파일 경로는 입력으로 받지 않으며, 저장된 환경 값만 프로세스가 만든 0600 임시 env file 로 전달한다.

컨테이너는 각각 메모리와 memory+swap을 모두 512MiB, CPU 1개, PID 256개로 제한하고 Linux capability를 모두 버리며 no-new-privileges로 실행된다. root filesystem은 read-only이고 /tmp만 noexec,nosuid 64MiB tmpfs로 쓸 수 있다. 따라서 managed image는 영속 로컬 쓰기를 가정하면 안 된다. 한 호스트에는 managed 항목을 8개까지만 만들 수 있고 서로 다른 이름의 동시 생성도 count-then-create 구간에서 직렬화된다. 기존 항목의 restart·reconcile은 이 상한 때문에 막히지 않는다.

application/mcpMetadataHeaders.ts가 저장된 예약 header를 제거하고 확인한 신원을 붙인다. 다른 대소문자 표기도 같은 이름으로 취급하며 OAuth 가용성 검사 전에 제거한다. 사용자가 정적 header를 저장해 다른 사람·Agent·대화를 사칭할 수 없다.

이메일은 MCP discovery부터 평문으로 전송하며 PII 필터가 가리지 않는다. 서버 등록은 사용자 이메일과 복원된 도구 인자 공개를 포함하는 신뢰 결정이다. 이 header만으로 인증되지 않으며 서버는 별도 Bearer·OAuth grant와 함께 위임 신원을 검증해야 한다.

registry Test와 Agent 도구 조회는 요청 사용자 email을 전송한다. 카탈로그·managed health probe에는 사용자·대화가 없다. Agent 도구 조회는 OAuth와 override를 사용하지만 tenant header는 보내지 않는 현재 차이가 있다. 따라서 tenant마다 도구 목록이 다른 서버에서는 probe와 런의 목록이 다를 수 있다.

API 대화 주소의 caller 부분은 배포 키로 만든 digest다. 이메일의 평문 hash가 아니지만 동일 사용자를 연결할 수 있는 가명이지 익명화는 아니다. 메신저·Chat의 주소 형식은 관측성 설계를 따른다. firing이나 대화 ID 없는 요청은 대화 header를 보내지 않는다.

FetchUrl은 모델이 지목한 주소를 src/infrastructure/net/httpResource.ts로 요청한다. registry의 등록 시 검증을 거치지 않으므로 호출 자체의 URL·DNS·redirect·byte 제한이 경계다. 같은 공개 fetch 경계는 Teams 첨부와 source 파일 주소에도 적용하지만 각 경로의 credential· 내부 호스트 예외는 별도 정책을 따른다.

• MCP 의 내부 호스트 예외는 결코 참조하지 않는다. MCP_INTERNAL_HOST_SUFFIXES 는 이 앱이 자기 클러스터의 MCP 서비스에 닿을 수 있게 하려고 존재한다. 여기서 그것을 존중하면 프롬프트 인젝션 하나가 http://mcp-argocd.agent-mcps.svc.cluster.local/ 을 읽는 일로 바뀐다. 어댑터가 skipsUrlGuard 를 import 하거나 그 목록·process.env·lib/config 에 닿기만 해도 tests/architecture.test.ts 가 실패한다.
• 자기 목록은 따로 있다. URL_FETCH_INTERNAL_HOST_SUFFIXES. 사내 위키나 내부 API 가 구조상 사설 주소인 설치형 네트워크를 위한 것이고, composition root 가 주입하며 배포로만 넓어진다. 그 접미사 아래의 호스트(isDeclaredInternalHost, 같은 술어, 같은 주의: 레이블 경계, 단일 레이블 거부, IP 리터럴 거부, http(s) 만)는 주소 가드 없이 요청되지만, 나머지는 그대로다: 같은 15초 타임아웃, 같은 두 헤더, 같은 리다이렉트 상한(5)이고, 리다이렉트는 네이티브 추종 없이 홉마다 확인되어 선언된 집합을 벗어나거나 출발 origin 을 벗어나면 거부된다. 예외가 리다이렉트 한 번으로 넓어져서는 안 되는 유일한 것이기 때문이다. 빈 목록(기본)은 모든 모델 선택 URL 이 가드를 마주한다는 뜻이다. 그 대가는 MCP 목록의 것과 같다: 접미사 아래의 모든 페이지가 프롬프트 인젝션 하나로 읽힌다. 정말로 모델이 읽어도 되는 존만큼 좁게 선언하라.
• 아무것도 인증하지 않는다. 테넌트 헤더 없음, MCP OAuth token 없음, Slack token 없음, 호출자 헤더 전달 없음. 항상 GET 이고 본문은 결코 없다. 교차 출처 리다이렉트는 애초에 붙지 않은 것을 전달할 수 없고. fetchPublicUrl 이 어차피 그것을 거부한다.
• 거부는 일반화된다. PublicFetchError 는 자기가 거부한 호스트를 지목한다. 그것을 모델에게 건네면 도구가 어떤 내부 이름이 존재하는지에 대한 오라클이 된다. 호출자는 "그 주소는 여기서 도달할 수 없다"를 받고, 상세는 origin 만 로그로 간다. URL 자체가 자격 증명인 경우가 많다.
• 런당 제한된다. MAX_URL_FETCHES_PER_RUN(20)은 요청의 개수 를 제한하는데, 다른 어떤 예산도 그렇게 하지 않는다. "많은 요청, 전부 실패"는 네트워크 스윕이 취하는 모양이다.
• 기본은 꺼짐. Agent가 parameters.urlFetch 로 옵트인한다. 그 capability 는 주입된 의존성에서 파생되므로 Playground 프리뷰와 런이 서로 어긋날 수 없다.

이것이 막지 못하는 것. 공개돼 있지만 민감한 호스트. 파드의 이그레스 주소를 신뢰하는 IP 허용목록 기반 SaaS. 는 가드를 통과한다. 유출도 마찬가지다. https://attacker.example/?leak=… 을 요청하도록 설득당한 모델은 평범한 아웃바운드 요청을 하는 것이고, PII 필터링은 도움이 되지 않는다. fetch 에는 복원된 인자가 필요하기 때문이다(마스킹된 URL 은 해석되지 않는다). 이것은 아래에서 MCP 도구 인자에 대해 이미 말한 것과 같은 한계다. 차이는 URL 이 마찰이 더 적은 통로라는 점이다.

이 HTTP 요청은 앱 프로세스에서 수행한다. SSRF 가드와 별개로 배포의 egress 정책을 적용하고, 허용한 내부 페이지와 IP 기반 신뢰 서비스가 모델에 노출될 수 있음을 고려한다.

관리자는 registry에 OAuth 메타데이터와 선택적 공유 client를 등록하고, connection은 Studio 사용자 ID·MCP 서버별로 본인의 grant를 보관하며 Agent 간에 재사용한다. 실행 경로는 well-known 문서를 다시 읽지 않고 저장된 계약으로 token을 해석한다. 발견·연결·callback의 HTTP 형태는 API, refresh 수명은 MCP 설계를 따른다.

protected-resource 문서는 MCP 주소의 401 challenge가 지정한 URL을 우선한다. challenge가 없으면 well-known 후보를 읽는다. resource 문서는 그 MCP 항목의 내부 호스트 예외를 사용할 수 있지만, 문서가 지목한 authorization server까지 같은 예외를 주지는 않는다. authorization·token·registration endpoint는 HTTPS와 URL 정책으로 검사한다. 메타데이터 조회 실패 메시지에는 후보 주소의 userinfo·query·fragment와 전송 오류 원문을 싣지 않는다.

resource identifier는 문서를 찾은 대상과 일치해야 한다. 제한된 예외는 https://mcp.slack.com/mcp가 공식 well-known 문서를 지목할 때 문서의 resource: https://mcp.slack.com을 허용하는 조합이다. 다른 origin·경로 조합으로 일반화하지 않는다.

authorization server는 RFC 8414 path-inserted, OpenID path-inserted, OpenID path-appended 순서로 발견한다. 경로를 가진 issuer에서 root 문서로 후퇴하지 않으며 문서의 issuer를 검증한다. Google discovery는 광고 주소 https://accounts.google.com/에 대해 메타데이터의 https://accounts.google.com만 추가로 허용한다. callback의 iss에는 이 예외를 적용하지 않는다. Entra의 common endpoint처럼 문서가 다른 tenant issuer를 돌려주면 일치 검사를 통과하지 못하므로 resource가 사용할 tenant issuer를 직접 광고해야 한다.

registry URL 변경은 이전 auth를 폐기한다. 새 주소의 Discover가 필요하며 이전 연결을 같은 이름이라는 이유로 재사용하지 않는다. OAuth 메타데이터와 공유 앱 저장은 읽은 auth에 대한 조건부 쓰기로 동시 변경을 보호한다.

등록 client credential은 발급 issuer에, token은 발급 당시 resource에 묶인다. 이 필드가 없는 연결이나 pending state를 현재 registry에 속한다고 추측하지 않는다. 새 연결이 필요하다고 알리고 grant 사용·인가 완료를 거절한다.

공유 앱은 clientFromRegistry와 Client ID를 기록하고 code 교환·refresh 때 현재 Secret을 읽는다. Secret 회전은 기존 grant에 반영하지만 Client ID의 교체·제거는 기존 grant를 차단한다. 개별 동적 등록 Secret은 해당 사용자의 connection에 보관한다. 연결 화면의 서비스 계정은 인증·접근 판정에 사용하지 않는다. 공식 OAuth endpoint 조합의 GitHub·Google 기본 조회는 해당 제공자의 고정 계정 API를 사용한다. 일반 OIDC는 검증한 discovery의 UserInfo endpoint를 사용하며, 관리자 지정 HTTP 계약도 HTTPS·URL 정책으로 저장과 dispatch 때 검증한다. Notion·Plaud token과 수동 MCP 계약은 발급된 resource에 해당하는 현재 registry URL의 현재 사용자 조회 도구에만 사용한다. 수동 MCP 계약은 서버가 readOnlyHint: true로 선언한 도구만 호출한다. lookup 설정은 관리자 전용이며 자동 선택으로 임의의 도구나 쓰기 작업을 실행하지 않는다. 모든 요청은 공개 URL 가드와 동일 origin redirect 정책을 따른다. 계정 조회 응답은 선택한 계정 label만 보관하고 오류 원문이나 token은 화면·로그에 전달하지 않는다. Studio 사용자 이메일을 서비스 계정으로 추정하지 않는다. 수동 JSON Pointer와 도구 인자에 token·password 등 자격 증명 필드를 허용하지 않으며, 서버 응답이 조회 token을 label에 포함해 반사하더라도 계정 표시·저장으로 넘어가지 않는다. Client ID·Secret 수동 입력은 관리자 공용 앱 설정에만 제공한다. 개인 연결 목록은 Client Secret과 access/refresh token을 반환하지 않는다. issuer·resource가 바뀐 grant는 실행에서 거절하며 사용자는 현재 서버 설정으로 다시 인가한다.

/api/mcps/oauth/client-metadata는 authorization server가 쿠키 없이 가져가는 문서다. secret은 없고 client 이름·client ID URL·고정 redirect URI를 제공한다. 요청 Host 대신 설정된 공개 base로 주소를 만든다. 이 URL을 실제 client ID로 선택하는 인가 준비 단계에서 HTTPS·공개 도달 가능 조건을 확인한다.

문서는 Agent 이름이나 사용자 정보를 포함하지 않는다. 실제 callback은 시작한 사용자의 ID·state·연결·현재 Agent 접근 권한을 요구한다. 공개 base가 없거나 provider가 가져갈 수 없는 주소면 metadata 방식 대신 지원되는 등록 경로를 사용하거나 설정 오류를 반환한다.

metadata client는 자기 호스팅 URL이므로 등록 client와 달리 issuer 변경 때 client ID 자체를 폐기할 필요는 없다. 다만 grant의 issuer·resource 검사는 그대로 적용한다. 배포의 공개 base가 달라지면 새 문서 주소로 갱신한다.

refresh 결과는 connection revision을 비교해 저장한다. refresh token을 생략한 응답은 이전 값을 유지하고 새 값이 있으면 교체한다. 경쟁에서 진 요청은 원래 issuer·resource에 속한 connected 상태의 승자 grant만 사용한다.

회전형 refresh credential은 provider 요청 전에 DB claim을 확보한 프로세스만 사용한다. 다른 프로세스는 결과를 기다리고, 만료된 claim이나 전송 결과가 불명확한 갱신은 다시 실행하지 않는다. 기존 credential 데이터는 보존하지만 needs_reauth로 표시해 사용자가 다시 인증하도록 한다. 403 insufficient_scope는 그 요청의 typed challenge에서 scope를 얻어 재인가에 보탠다. 병렬 도구 호출의 결과를 세션 전체의 마지막 challenge로 해석하지 않는다.

token은 registry·Agent header보다 우선하는 마지막 credential이다. OAuth 서버는 호출자의 유효한 개인 grant가 없으면 warning과 함께 제외한다. Agent 소유자·다른 사용자·registry의 정적 인증으로 대신 호출하지 않는다. 예약 신원 header는 credential로 계산하지 않는다.

Workspace는 chat 소유자에게만 공개되며 실행·승인은 현재 Agent 접근도 다시 확인한다. Workspace 설정 쓰기는 Agent 소유자에게 한정하고 revision 조건과 Agent 수명 경계로 보호한다. Agent의 도구 활성화는 해당 Agent에 명시적으로 연결한 GitHub MCP 계정을 정책 범위 내 사용하는 것을 허용한다. Runtime 모델 선택은 관리자에게 한정하며 도구를 끄면 새 실행·Git 승인을 거절한다. 등록 저장소·정확한 소유자 허용은 DB에서 현재 값을 읽으며 일반 Agent가 수정하지 않는다. 소유자 허용은 해당 계정의 향후 저장소도 포함하므로 관리 화면에서 그 범위를 명시한다. 조회 실패는 접근을 거절하고 selected의 빈 목록은 모든 Git 대상을 차단한다. all은 해당 Agent의 GitHub MCP 권한 안에서 모든 저장소를 허용한다. new의 자동 등록은 서버의 실제 생성 성공에만 적용하고 MCP 결과나 모델이 주장한 생성 사실·시각을 권한 근거로 사용하지 않는다. 생성 receipt와 등록은 원자적으로 저장하며 불명확한 생성은 반복하지 않는다. 저장소 정책은 Sandbox 자원·네트워크나 Agent의 GitHub MCP 자격증명, 개별 게시 승인을 변경하지 않는다. 변경은 settings.update 감사에 기록한다. Sandbox에는 호스트 mount, Docker socket, 배포 자격증명과 장기 Git 자격증명을 전달하지 않는다. Git 메타데이터는 root 소유로 두고 Agent의 실행 계정은 작업 파일만 수정한다. GitHub API·clone·push는 현재 Agent의 GitHub MCP 인증을 사용하며 Plugin 토큰이나 다른 Agent의 연결로 폴백하지 않는다. OAuth issuer·resource·client 검사와 갱신은 기존 MCP 인증 제공자가 수행한다. OAuth 토큰은 발급한 GitHub authority와 일치하는 API·Git endpoint에만 사용한다. 서버의 임시 bare Git 저장소에서 인증하고 Sandbox에는 자격증명 없는 bundle만 전달한다. 서버에서는 저장소 checkout·hook·build script를 실행하지 않는다. 공개 Git endpoint는 HTTPS와 DNS pinning을 사용하고 내부 호스트 예외는 배포의 별도 목록을 따른다.

효과는 검토한 tree/HEAD와 권한 근거를 가진 동작 레코드를 먼저 claim한 뒤 실행한다. 코딩 요청의 작업 브랜치 Commit·Push·PR은 추가 확인 없이 실행하며 authorization: coding-request로 기록한다. main 반영·태그·릴리즈·배포는 별도 사용자 확인을 유지한다. 자동 게시도 소유권·현재 정책·fingerprint·lease를 다시 검사한다. 종료·삭제가 먼저 기록되면 pending/실행 claim을 거절한다. 종료된 Workspace의 새 Git 검토는 소유자·살아 있는 Chat·Agent와 action lease를 원자적으로 확인한 뒤 복원하며 삭제는 되돌리지 않는다. main 병합은 PR 소유 범위와 CI를 재확인하고 GitHub의 정확한 head SHA 조건을 사용한다. 배포는 허용된 main workflow와 승인한 inputs로만 요청한다. 전송 오류 이후의 불확실한 효과는 자동 재실행하지 않는다. main 직접 푸시는 검토한 main SHA와 게시된 작업 HEAD를 대조하고 force: false로 실행한다. 검사 미보고는 none으로 승인 화면에 표시하고, 대기 중·실패한 검사와 구분한다. 모든 main 반영은 GitHub 브랜치 규칙을 따르며 권한·보호 규칙을 우회하는 옵션을 제공하지 않는다. 태그는 검토한 원격 main, 릴리즈는 검토한 기존 태그의 정확한 commit을 사용한다. 태그를 덮어쓰지 않으며 GitHub의 저장소 범위 contents 쓰기 권한으로 실행하고 생성 응답과 릴리즈 태그를 검증한다. /api/workspaces/github/webhook은 서명과 delivery ID로 PR 메타데이터만 갱신하며 승인 권한이 없다. Agent Trigger인 /api/webhook/{agent}는 별도 Agent 시크릿으로 실행을 시작한다. 관리자가 githubReview를 활성화하면 서명된 PR 이벤트에 대해 해당 Agent의 GitHub MCP 연결로 리뷰 댓글을 게시할 수 있다. 자동 리뷰 게시 설정은 관리자만 변경하며, 접근 가능한 저장소 전체 또는 명시적 저장소 목록으로 한정한다. PR의 본문·URL이 게시 목적지를 결정하지 않는다. 공급자 API가 확인한 base repository·PR 번호·commit_id에 COMMENT만 게시한다. 모델에는 Skill과 검증된 PR·HEAD·base에 고정된 ReviewSource를 제공한다. 파일 경로는 상대 경로로 검증하고 공급자 API만 호출하며, 반환된 download URL·submodule URL을 따라가지 않는다. 읽기 요청 전후에 커밋과 현재 연동 위임을 확인한다. 완전한 변경 자료가 확보되지 않은 실행은 전체 리뷰로 게시하지 않는다. PR 리뷰 Workspace는 개인 Webhook 토큰 발급자의 현재 권한과 Agent 저장소 정책으로 생성한다. 검증된 커밋의 bare bundle만 Sandbox에 전달하고 서버 Git 자격 증명은 넣지 않는다. command 런타임과 이 리뷰의 Workspace만 제공하며 저장소 생성·연결, 다른 Workspace 선택, Git publication·배포를 거절한다. 끝나지 않았거나 결과를 읽지 않은 검사는 게시를 막는다. 성공·실패 모두 Workspace 정리를 요청하고 실제 종료를 확인하며 게시 영수증은 정리 실패에도 보존한다. 개인 Webhook 토큰은 발급 사용자의 권한으로 선택 범위의 리뷰를 요청한다. 토큰·계정 권한 회수는 새 조회·도구 호출·게시·큐 실행에 적용한다. Workspace는 actor 종류와 별도로 표면이 확인한 관리 사용자의 현재 계정·Agent 접근과 저장소 정책을 검사한다. 대화형 실행과 자동화 모두 member 이상이어야 한다. 개인 API token은 발급 사용자를, 메신저는 연결한 Studio 사용자를, Schedule은 등록자를 사용한다. Schedule의 등록자 ID는 변경되지 않으며 현재 계정·Agent 접근을 실행 전에 다시 확인한다. Webhook 호출자는 개인 토큰 발급자이며 공유 설정에서 다른 사용자의 권한을 위임하지 않는다. 외부 payload는 email·actor를 지정할 수 없다. 플랫폼 actor는 원래 연동 호출자로 유지한다. 큐 작업 실행 직전에도 사용자 권한을 다시 확인하며 외부 호출은 Git 승인을 직접 소비할 수 없다. 승인·CI 결과의 Chat 재개는 원래 소유자·Agent 접근·Workspace 선택과 SDK Session을 다시 확인한다. 그 결과 이벤트는 새 사용자 요청이나 다음 Git 동작에 대한 승인으로 취급하지 않는다.

Native CLI에는 공급자 API 키 대신 하나의 Workspace Run에 한정된 서명 토큰을 전달한다. AES_ENCRYPTION_KEY에서 별도 HKDF 목적 키를 파생하며 오브젝트 URL 서명과 교환할 수 없다. Run 만료·취소·종료·원래 인증 수단 철회는 다음 모델 요청을 거절한다. 요청자의 Authorization, 쿠키, 임의 헤더를 공급자에게 전달하지 않는다. 공유 Provider에 저장된 대화·prompt·파일·도구 리소스는 참조할 수 없으며 Responses는 저장을 끈다. Gateway 주소는 배포자가 지정하고 Sandbox 네트워크에서 Studio에 필요한 통신만 허용한다. Workspace 계약을 따른다.

SDK Session 이력과 승인 대기 RunState는 runtime_sessions에 별도로 저장한다. 같은 배포의 AES_ENCRYPTION_KEY를 사용하며 대화 ID와 소유자를 인증 데이터에 묶은 암호문만 읽는다. 원문 상태에는 모델/도구 이력과 각 Agent의 PII 복원 매핑이 포함될 수 있다. DB 접근 권한과 암호화 키를 분리해 관리하고 백업·복구 시 같은 키를 유지하라.

암호화된 Session에는 최초 실행의 Studio 사용자 ID를 저장한다. 새 턴과 승인 재개는 로그인 세션의 ID와 일치해야 하며 이메일만으로 다른 계정에 이력을 인계하지 않는다. 사용자 ID가 없거나 다른 Session은 실행하지 않으며 새 Chat을 시작해야 한다. Workspace Git 승인은 요청자의 Studio 사용자 ID를 보관하고 같은 계정의 결정만 허용한다. 후속 실행 큐는 이 ID를 변경할 수 없으며 현재 계정·Agent 접근과 SDK Session의 사용자 ID를 다시 검사한다.

승인은 Chat 소유자가 정확한 revision과 항목 ID를 지정한다. 동일 출처 session 변경 검사, Agent 접근 재확인, 실행 lease와 Session CAS를 함께 적용한다. 승인 상태는 도구 실행 전에 pending에서 running으로 선점한다. 중복·낡은 결정, 변경된 설정과 연결은 거부하며 승인 후 중단된 실행은 자동으로 반복하지 않는다. 삭제 tombstone은 늦게 끝난 실행의 재생성을 막는다.

SDK tracing은 로컬 processor가 이름·시간·상태·사용량만 수집한다. SDK의 공개 exporter를 설치하지 않으며 원문 모델/도구 입력·출력과 credential을 native span으로 내보내지 않는다. 배포가 선택한 OTLP exporter와 실행 오류/경고 기록의 접근 범위는 기존 운영 정책을 따른다.

parameters.piiFiltering은 Agent별 선택 기능이다. SDK 모델 요청의 텍스트와 system prompt에서 탐지한 값을 [[PII:…]]로 치환하고 표시할 응답에서 복원한다. 스트리밍의 토큰 경계와 하위 Agent의 치환 매핑도 유지한다. 소유 코드는 application/llm/pii.ts, runtime/model.ts, runtime/tools.ts다.

이미지 bytes의 개인정보 제거는 보장하지 않는다. 일반적인 이름·이미지 속 개인정보·패턴에 맞지 않는 값도 탐지 대상이 아니다. 탐지 범위는 email, 전화번호, 한국 주민/외국인등록번호의 지원 형식, Luhn 검사를 통과한 13–19자리 결제 카드 번호다. 범용 DLP로 사용하지 않는다.

preview는 모델을 호출하지 않아도 recall·discovery를 수행할 수 있으며 조립한 원문을 보여준다. 준비 단계의 원문 전송이 허용되지 않는 환경에서는 해당 capability와 연결을 선택하지 않아야 한다. 외부 제공자가 동일한 계정인지와 무관하게 각 채널의 전송·보존 정책을 확인한다.

회상된 기억과 첨부·도구 결과는 신뢰할 수 없는 텍스트다. rememberedBlock은 기억을 <recalled> 경계와 인용문으로 감싸 지시와 구분하지만 prompt injection을 제거하지 않는다. 무엇을 기억하고 누가 검색할 수 있는지는 연결된 Memory 서버의 저장·권한 정책이 소유한다.

parameters.callerContext 로 Agent별 옵트인. 켜져 있으면 Slack 런은 누가 묻고 있는지를 모델에게 알려 주고. 표시 이름, 시간대, 아바타의 URL. 한 스레드에 사람이 둘 이상이면 화자마다 라벨을 붙인다. Telegram 런과 Teams 런은 각자의 이벤트가 실어 오는 것으로 같은 일을 한다. 보낸 사람의 이름, 그리고 그 밖에는 아무것도 없다. 둘 다 시간대도 email 도 넘겨주지 않는다.

이름은 piiFiltering 이 마스킹하지 않는 PII 다. 그 패턴들은 email, 전화번호, 등록번호/카드 번호에 맞고 사람의 이름은 그 어느 것에도 맞지 않으므로, 호출자 블록이 싣는 것은 필터링이 켜져 있어도 쓰인 그대로 모델에 도달한다. 그래서 그 블록은 email 을 싣지 않으며, 그래서 이것이 기본 동작이 아니라 Agent별 옵트인이다. 켜는 것은 실제 사람의 이름을 프롬프트에, 그리고 제공자가 로깅하는 무엇에든 집어넣겠다는 결정이다.

옵트인은 모델에 넣을 이름·시간대·아바타를 위한 프로필 조회를 게이트한다. Slack 의 private agent 접근 검사와 artifact 소유자 식별에 필요한 email 조회는 옵트인과 독립적으로 users.info 를 호출할 수 있다. 그 email 은 모델의 caller 블록에 들어가지 않는다. 이름이 메시지와 함께 도착하는 Telegram 에서는 옵트인하지 않은 이름이 대화 트랜스크립트에 쓰이지도 않는다(데이터 노출과 보존 참고). transfer 는 호출자를 자식에게 실어 나르고(RunOrigin), 거기서 자식 Agent 자신의 옵트인이 다시 결정한다. 그래서 이름은 몇 홉 떨어져 있든 그것을 요청한 Agent에만 도달하고, 소유자가 한 번도 옵트인하지 않은 agent 는 그것을 결코 보지 않는다. 해석된 프로필은 워크스페이스별로 메모리에 캐시되고(1시간, 실패는 1분), 크기가 제한되며, 결코 영속되지 않는다.

표시 이름은 공격자가 통제한다. 누구나 자기 것을 무엇으로든 설정할 수 있고, 그것이 시스템 프롬프트에 실린다. 공유 스레드의 화자 라벨을 통해, 자기 대화만이 아니라 다른 사람의 대화 안에서. callerFrom(src/domain/execution/actor.ts)은 RunCaller 가 만들어지는 유일한 자리이고 따라서 그 이름을 안전하게 만드는 유일한 자리다. 제어 문자는 제거하고, 공백은 한 줄로 접고, 이름은 60자로 제한하며, 아바타는 https: URL 일 때만 받아들인다. 그것이 프롬프트 인젝션을 불가능하게 만들지는 않지만. 메시지 본문도 신뢰되지 않는다. 신원 메타데이터가 독자가 볼 수 없는 지시를 숨길 자리가 되는 것은 막는다.

LLM 답변과 tool 결과는 Slack mrkdwn으로 전달되므로 텍스트 안의 mention token은 단순한 표시가 아니다. <@U…>는 사용자를, <!subteam^…>은 사용자 그룹을, <!channel>·<!here>· <!everyone>은 넓은 청중을 실제로 알릴 수 있다. 그 텍스트는 질문·외부 문서·도구 결과에 의해 영향받으므로 알림 권한으로 취급하지 않는다.

neutralizeSlackMentions(src/domain/slack/outboundText.ts)가 알림 가능한 완전한 token만 escape한다. slackClient는 chat.postMessage, chat.update, 그리고 stream의 text/chunk 축을 Slack에 쓰기 직전에 모두 이 함수를 통과시킨다. 따라서 streaming 실패 뒤 edit로 물러나거나 마감 시 남은 답을 다시 보내는 경로도 같은 규칙을 받는다. 일반 Markdown, URL link, channel reference, 알림을 만들지 않는 date token은 보존한다.

parameters.slackWorkspace 로 Agent별 옵트인. 켜져 있으면 런은 자기 agent 의 봇이 설치된 워크스페이스의 채널 히스토리, 스레드, 사용자 이름을 읽을 수 있다.

Agent 는 공유 카탈로그다 (private agent 라면 그 접근 범위 안에서). 따라서 agent 를 실행할 수 있는 사람은 누구나 그 봇이 읽을 수 있는 것을 읽을 수 있다. 봇이 초대된 모든 채널이며, groups:history 가 적용되는 비공개 채널도 포함이다. 그것이 이것을 Slack 에 연결된 모든 agent 가 갖는 capability 가 아니라 Agent별 옵트인으로 만든 이유 전부다. 켜는 것은 어떤 채널의 내용을 그 채널 자신의 멤버보다 더 넓은 사람들에게 닿게 하겠다는 결정이다.

두 가지는 빠뜨려서가 아니라 구조적으로 거부된다:

• 쓰기 없음. chat:write 는 봇에게 부여돼 있고. 답장 전송에 필요하다. 의도적으로 어떤 도구에서도 닿을 수 없다. 런은 자기가 쓰지 않은 텍스트에 조종된다. 글도 올릴 수 있는 런은, 어떤 채널에 심어 둔 메시지가 봇으로 하여금 다른 곳에서 말하게 만들 수 있는 런이다.

• email 은 모델에 도달하지 않는다. users:read.email 이 부여돼 있는데도 그렇다. SlackUser 와 SlackUsers 는 이름, 직함, 시간대, 상태 문구, 아바타로 답한다. 동료가 프로필을 클릭해서 보는 전부다. 주소는 결코 답하지 않는다. 그것은 호출자 컨텍스트가 이미 적용하는 규칙이고, 이유도 같다. email 은 Slack 밖에서 사람을 식별하며, 어떤 답도 잘 쓰이기 위해 그것을 필요로 하지 않는다.

  이메일은 private Agent 접근 판정, MCP 위임 신원과 Artifact의 개인 귀속에 별도로 사용한다. Slack actor는 발신자의 Slack 사용자 ID로 유지한다. 개인 예산과 동시성은 일회용 코드로 연결한 Studio 사용자 ID에 합산한다. toUserDetail은 이메일을 모델용 도구 결과에 복사하지 않는다. 이 조회는 모델 표시 문맥을 제어하는 callerContext와 독립적이다.

안으로 실려 오는 것은 첨부된 문서와 똑같은 방식으로 신뢰되지 않는다. 채널의 메시지는 그 채널에 있는 누구든 쓴 것이고, 그것이 텍스트로 모델에 도달한다. PII 필터링은 다른 것과 마찬가지로 그 도구 결과에도 적용되며(parameters.piiFiltering), 턴별 도구 결과 예산이 그 크기를 제한한다. 트랜스크립트의 길이는 Slack 이 정하는 것이므로, 통째로 청구되는 대신 fit 을 거친다.

리더는 봇 token 을 쥐고 있고, 그것은 생성 시점에 바인딩된다. 워크스페이스를 지목하는 도구 인자는 모델이 워크스페이스를 고르게 만들 것이고, 그것이 올바른 모양인 요청은 없다.

문서의 텍스트는 턴 안으로 들어가므로, 누구든 첨부할 수 있는 것은 무엇이든 말할 수 있다. Slack 채널에서 그것은 묻는 사람만이 아니다. 봇이 볼 수 있는 곳에 파일을 떨어뜨릴 수 있는 누구든이다.

이에 대해 하는 일: 모든 문서는 framedDocument(src/application/llm/documentParts.ts)가 감싸며, 파일의 이름을 밝히고 어디서 끝나는지를 표시하고 그 구간을 데이터로 다루고 결코 지시로 다루지 말라고 모델에게 말한다. 이름은 JSON 이스케이프되므로 조작된 파일명이 끝 표시를 위조할 수 없다.

그것은 완화이지 해결이 아니다. 어떤 문구도 주입된 텍스트를 안전하게 만들지 못하고, 메시지 본문은 이미 신뢰되지 않았다. agent 의 권한을 그에 맞춰 잡아라. 첨부를 읽는 agent 는 파일을 든 낯선 사람에게 주지 않을 권한을 쥐고 있어서는 안 된다.

알아 둘 만한 다른 속성들:

• 문서는 읽힐 뿐, 실행되거나 렌더링되지 않는다. 추출은 텍스트만 내놓는다. HTML 은 마크업과 활성 내용을 제거한 텍스트로 읽히며, 스크립트를 실행하거나 외부 리소스를 가져오지 않는다.
• 문서를 대신해 무언가를 가져오는 것은 없다. 첨부 안의 URL 은 다른 것과 마찬가지로 텍스트일 뿐이다. Agent가 바인딩한 도구만이 그것에 작용할 수 있고, 그 도구 자신의 가드 아래에서 그렇다.
• 텍스트는 PII 필터를 지난다. Agent가 옵트인하면 턴의 나머지와 마찬가지이고, 한계도 같다 (email, 전화번호, 한국 등록번호, 카드 번호, 이름은 아니다).
• Chat은 원본과 추출문을 분리해 보관한다. 턴당 최대 40,000자의 추출문과 파일 참조는 소유자 전용 chat 행에 남고, 원본은 source: attachment인 artifact로 저장한다. 원본은 기존 artifact와 같은 생성자·Agent 소유자 읽기 정책, artifact 보존 기간과 오브젝트 접근 모드를 따른다. 원본은 chat 삭제만으로 삭제되지 않으며 artifact 삭제·보존 정책이 소유한다.

• Trace 는 제한된 메타데이터만 저장한다. 문자 수, token, 비용, 소요 시간, subagent 의 trace id. 원본 프롬프트와 도구 결과는 영속되지 않지만, trace 의 error 와 warnings 는 실패 텍스트를 그대로 최대 1,000자까지 보관하고, 제공자나 도구의 에러 문자열은 내용을 품을 수 있다.
• 런의 추론은 켠 Agent에서 복원된 채로 저장된다. parameters.reasoningTrace 를 켠 Agent는 assistant 메시지에 그 런의 사고를 남기는데(AssistantChatMessage.reasoning, 메시지당 최대 40,000바이트), 그것은 content 와 같은 출처. 즉 마스킹이 풀린 텍스트다. PII 필터는 모델이 보는 것을 제한하지 콘솔에 저장되는 것을 제한하지 않으므로(content 도 마찬가지다), piiFiltering 을 켠 Agent에서도 추론은 걸러지지 않은 채 chat 행에 앉는다. 추론은 요청을 모델 자신의 말로 되풀이하는 자리라 입력이 실어 온 것을 그대로 품기 쉽다. 옵트인인 이유가 이것이고, 보존 기간은 chat 행과 같다(RETENTION.chatDays).
• /api/metrics 는 agent, 사용자, model 을 지목하지 않는다. 메트릭 라벨은 히스토그램의 le 와 build 정보의 유한한 version·stage뿐이다.
• 로그 라인은 런의 correlation id 를 실을 뿐, 프롬프트 내용은 결코 싣지 않는다.
• Trace, usage 행, chat, trigger 배달 행은 모두 expiresAt 을 지니고 schedule-scan 틱의 sweep 이 지운다. scan 호출이 없는 배포에서는 이 DB sweep이 실행되지 않는다. OPERATIONS.md 참고.
• 메시징 파일 참조 기록은 Slack·Telegram·Teams에서 대화·actor별로 생성 파일 ID와 이름만 7일간 보관한다. URL이나 바이트는 기록하지 않는다. 최근 20개 기록, 기록당 20개 파일, 런당 20,000자로 제한하며 참조를 얻어도 File 도구의 권한 검사를 통과해야 한다.
• Telegram·Teams 대화 트랜스크립트 는 agent 의 봇과 주고받은 모든 턴의 텍스트 를 7일간 보관한다. 대화별로 질문과 답을. 두 플랫폼 모두 히스토리를 돌려주지 않아 후속 질문이 그 앞의 질문을 실어 날라야 하기 때문이다. 그것은 chat 메시지처럼 저장된 사용자 텍스트다. chat 과 달리 그 대화의 다음 런 외에는 아무것도 그것을 읽지 않는다. 보낸 사람의 플랫폼 사용자 id(Telegram user id, Teams 는 Entra object id)는 턴 옆에 저장되고, 보낸 사람의 이름 은 Agent가 callerContext 에 옵트인했을 때만 저장되며, 옵트인을 끈 Agent는 이전에 저장된 이름도 읽지 않는다. 행은 agent 파티션에 있어 agent 를 지우면 함께 지워진다.
• 생성된 이미지 는 S3_BUCKET_NAME 이 설정돼 있으면 추측할 수 없는 UUID 키 아래 저장되고, chat 행은 주소가 아니라 오브젝트 키 를 보관한다. 읽기 시점에 키가 주소가 되며, 수명은 독자에 맞춰 고른다. chat 뷰에는 15분, 메시징 답변에 포함된 링크에는 7일(SigV4 pre-sign 의 상한이고, proxied 토큰도 같은 값을 쓴다). 그 링크는 그것이 함께 온 답을 이미 읽을 수 있던 청중이 쥔다(src/shared/artifactUrlTtl.ts). 주소의 모양 은 ARTIFACT_ACCESS_MODE 가 정한다:

  • proxied. 스토어는 앱에게만 닿고 독자는 앱의 주소 PUBLIC_BASE_URL/api/objects/<key>?exp=<unix>&sig=<hmac>[&dl=<filename>] 를 받는다 (src/infrastructure/storage/objectUrlToken.ts). 그 라우트는 세션을 요구하지 않으며 그것이 계약이다: 주소를 쥐는 것은 <img> 태그와 Slack 메시지라 쿠키를 낼 수 없다. 토큰이 자격 증명이다. 키·만료·파일명을 함께 덮는 HMAC-SHA256 이고, 서명 키는 AES_ENCRYPTION_KEY 에서 HKDF(agent-studio/object-url/v1)로 파생되어 그 바이트가 저장된 토큰을 암호화하는 바이트와 결코 같지 않다. 증명하는 것은 이 배포가 이 키에 대해 이 수명과 이 파일명으로 발행했다 는 사실뿐이다. 파일명은 장식이 아니라 서명에 묶여 있어 dl 을 떼어 다운로드를 인라인 보기로 바꿀 수 없고, 만료와 서명 불일치는 하나의 403 으로 답한다(둘을 구별해 주면 위조자에게 어느 쪽을 고칠지 알려 준다). 없어진 오브젝트는 404, 읽기는 MAX_PROXIED_OBJECT_BYTES 에서 끊기며, Cache-Control: private 의 max-age 는 토큰의 남은 수명을 넘지 않는다. 바이트는 콘솔의 origin 에서 나가므로 브라우저가 문서로 렌더할 수 있는 타입(HTML, SVG, 텍스트)은 /view 와 같은 sandbox; default-src 'none' 아래 불투명 origin 에 놓이고, 래스터 이미지와 PDF 만 frame-ancestors 'none' 으로 끝난다. next.config.ts 가 이 주소를 콘솔 헤더에서 제외하는 이유가 그것이다.

  • authenticated. 스토어의 pre-signed URL. 스토어가 브라우저에서 닿아야 하고 버킷은 비공개로 남는다.

  • public. 영구적인 직접 URL. 명시적인 공개 읽기 버킷 정책을 요구하고 URL 을 얻은 누구에게나 바이트를 노출한다. 애플리케이션 인증은 여전히 갤러리 메타데이터와 삭제를 보호하지만 오브젝트는 보호하지 않는다. 주소가 보기가 아니라 다운로드인 곳에서는 어쨌든 미리 서명한다. 브라우저가 저장할 파일 이름은 ResponseContentDisposition 이 실어 나르는데 S3 는 익명 GET 에서 그것을 거부하므로, 서명되지 않은 링크는 오브젝트를 UUID 키로만 저장할 수 있다.

  • 레거시 행은 공개 url 을 지니고 있을 수 있고 그대로 되읽힌다. 그것을 다시 쓴다고 해서 이미 공개인 그 오브젝트들에 누가 닿을 수 있는지는 아무것도 바뀌지 않는다. 공개 노출 여부는 현재 bucket policy·ACL이 결정한다. 앱의 metadata나 access mode만 바꿔서는 기존 객체를 비공개로 전환하지 못한다. 정책을 닫으면 옛 공개 URL도 더는 접근되지 않을 수 있다.

  • 페이지는 오브젝트 주소로 나가지 않는다. SAVABLE_TYPES 에 포함된, 사람이 읽도록 만든 artifact 만 /view 를 통해 앱이 바이트로 답한다. 서명한 오브젝트 URL 은 sandbox 헤더를 실을 수 없고, 한 번 건네지면 그것을 연 사람의 권한보다 오래 살며, public 모드에서는 영구다. 임의의 마크업이 실행되는 영구 주소는 저장소가 아니라 호스팅이다. /view 는 삭제와 같은 조건으로 매 요청을 인가하고, Content-Security-Policy 의 sandbox 로 문서를 불투명 오리진에 놓는다. HTML 원문은 별도의 iframe에만 들어가고 콘솔의 쿠키·스토리지·DOM에 닿지 못한다. nosniff와 no-referrer도 함께 적용한다.

  • HTML은 미리보기를 여는 즉시 격리된 iframe에서 실행한다. 원문을 선언된 charset으로 엄격하게 디코딩하고, 전체 내용을 이스케이프한 srcdoc 속성으로 전달한다. 바깥 화면에는 제품의 제어 코드만 실행되며, 원문 script·이벤트·canvas·SVG는 iframe 안에서 보존한다. HTTP CSP와 iframe 모두 sandbox allow-scripts를 적용하고 allow-same-origin, top-navigation, popup, form, download 권한을 주지 않는다. iframe을 제거하면 실행 상태를 버리고, 다시 시작하면 원본을 새 iframe에 넣는다. 코드 오류나 상태를 저장 성공과 혼동하지 않는다.

  • 격리와 통신 제한의 범위를 구분한다. HTML의 INTERACTIVE_HTML_VIEW_POLICY는 fetch/XHR/WebSocket, 외부 script·CSS·image·font, worker, 외부 프레임 이동과 폼 제출을 제한한다. frame-src 'none'은 inline srcdoc을 허용하면서 네트워크 frame 탐색을 막는다. 내부 목차 링크는 기준 URL을 about:srcdoc으로 지정해 처리하며, base-uri about:으로 외부 기준 URL을 거절한다. 카메라·마이크·위치 등은 Permissions Policy로 제한한다. 이 정책은 WebRTC 등 모든 브라우저 통신이나 CPU·메모리를 강제 격리하지 않는다. 미리보기 열기는 HTML 코드 실행을 포함하므로 신뢰하는 파일을 다룬다는 전제로 사용한다. 완전한 무통신·자원 격리가 필요하면 별도의 실행 환경이 필요하다. iframe에서 보고한 오류는 현재 iframe의 Window를 확인한 뒤 고정 안내로만 표시한다. 차단된 리소스와 외부 이동도 고정 안내로 표시하고, 스크립트 오류를 우선한다. 오류 원문·주소를 부모 화면에 렌더하거나 서버로 보내지 않으며 특권 API·인증 정보는 전달하지 않는다.

  • 정적 view는 스크립트를 실행하지 않는다. ARTIFACT_VIEW_POLICY에는 어떤 allow-*도 붙이지 않는다. Markdown은 raw HTML을 텍스트로 내보내고, CSV는 이스케이프된 표, SVG는 <img>로 표시한다. HTML 실행 정책은 이 경로에 적용하지 않는다.

  • 전역 헤더와의 충돌을 검사한다. next.config.ts는 자체 CSP를 사용하는 두 경로를 제외한다. 새 파일 응답이나 정책 변경도 응답 헤더의 경계를 유지해야 한다.

  • 일반 런 Artifact의 object 만료는 저장소 정책이 담당한다. 틱은 메타데이터 행을 지우며 artifacts/의 bytes에는 별도 lifecycle을 적용한다. 비공개 source-files/는 worker가 파일별 보존 기한을 검사하고 본문을 삭제 표식으로 교체하므로 같은 일괄 만료 규칙을 적용하지 않는다. INSTALL.md의 저장소 정책을 따른다.

• 비공개 파일 Artifacts는 같은 S3_BUCKET_NAME을 사용하지만 일반 object 접근 경로로 읽거나 URL을 발급할 수 없다. source-files/ 키는 일반 어댑터와 bearer URL 검증에서 거절하며, 소유자·Agent·파일 상태·만료를 확인하는 다운로드·미리보기 경로만 사용한다. public 모드에서는 가져오기 전에 비공개 파일 쓰기를 거절한다. 실제 bucket policy와 ACL의 익명 읽기 차단은 배포 환경이 소유한다.
• Artifact 행 은 런이 만들어 낸 모든 오브젝트를 지목하고, 그것이 저장된 이미지나 문서를 나열하고 지울 수 있게 만드는 전부다. 언급할 만한 귀결이 셋 있다:
  • 행은 갤러리를 읽을 수 있게 하려고 프롬프트의 500자 발췌 를 보관한다. 그것은 ARTIFACT_RETENTION_DAYS 동안 사는 사용자 텍스트이며, 그것을 실어 온 chat 메시지보다 오래 남는다. PII 필터링은 모델 이 보는 것을 한정할 뿐, 저장되는 것을 한정하지 않는다.
  • agent 의 artifact 탭은 그 Agent의 소유자가 읽을 수 있다. trace 가 쓰는 것과 같은 규칙이고, 이유도 같다(다른 사람의 런타임 출력을 담고 있다). 실제로는 trace 보다 더 넓은 노출이다. Agent trace는 항상 기록하고 기본 30일을 보관하지만, artifact 는 모든 오브젝트이고 180일을 보관한다.
  • artifact 를 지우면 오브젝트를 먼저, 행을 나중에 지우므로 중단된 삭제는 재시도로 수렴한다. chat 메시지는 그 키의 사본을 자기 안에 갖고 있으므로 트랜스크립트는 그 뒤로 이미지를 사용할 수 없음으로 렌더링한다. 확인 문구가 그 사실을 미리 말해 준다.

• 유출된 개인 토큰은 폐기·재발급한다. 본인 API·Webhook 토큰은 Integrations 또는 DELETE·POST /api/agents/{name}/token 및 …/webhook-token으로 관리한다. 실행은 현재 계정·credential을 다시 검사한다.
• 설정 전파는 즉시가 아니다. 강등된 admin의 권한 변경는 그 쓰기를 처리하지 않은 인스턴스에서 설정 캐시가 만료될 때까지 계속 동작한다(SETTINGS_CACHE_TTL_MS, 기본 5초). 인스턴스 간 즉시 취소에는 공유 무효화 신호가 필요한데, 아직 없다. 쓰기를 처리한 인스턴스는 캐시 세대를 쓰므로, 이미 진행 중이던 읽기가 무효화된 항목을 다시 채울 수 없다.
• 인증 rate limit 은 클라이언트 IP 로 키잉하고, 프록시 뒤에서 그것은 TRUSTED_PROXY_CIDRS 로 해석된다. CONFIGURATION.md 참고. 프록시 둘 뒤에서 그것을 비워 두면 모든 요청이 같은 홉으로 해석돼 하나의 공유 버킷에 떨어지므로, 리미터는 남용자가 아니라 함대 전체를 조인다.
• AWS 자격 증명은 AWS 를 쓰는 기능에만 필요하고(Bedrock, AWS S3 자체), 역할이나 표준 AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY 쌍으로 온다. MinIO 같은 S3 호환 스토어의 자격 증명은 그것과 다른 S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY 쌍이다. 한 프로세스가 둘 다 쓸 수 있다. 키를 이미지에 굽지 마라.
• AES_ENCRYPTION_KEY 를 회전하면 저장된 시크릿만이 아니라 proxied 오브젝트 주소도 전부 무효가 된다. 서명 키가 거기서 파생된다. 발급된 링크가 무효화되고 기존 credential·SDK Session·Workspace checkpoint도 새 키로는 복호화할 수 없다. 키 교체만으로 기존 암호문을 다시 암호화하는 자동 이관은 제공하지 않는다.