@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ko-KR/security.md

@@ -0,0 +1,330 @@
+---
+title: "보안"
+description: "에이전트 네이티브 앱의 보안 모델: 입력 유효성 검사, SQL 주입 방지, XSS, 데이터 범위 지정, 비밀 관리 및 인증 패턴."
+---
+
+# 보안
+
+에이전트 기반 앱은 기본적으로 안전하도록 설계되었습니다. 프레임워크는 여러 계층에서 자동 보호 기능을 제공합니다. 즉, SQL 수준 데이터 격리, 매개변수화된 쿼리, 입력 유효성 검사 및 인증을 즉시 사용할 수 있습니다.
+
+## 무료로 얻는 것과 소유한 것 {#what-you-own}
+
+```an-diagram title="Defense in layers" summary="The framework owns most of the threat surface; you own two things — tagging tables for scoping and validating external input."
+{
+  "html": "<div class=\"sec-layers\"><div class=\"diagram-card free\"><span class=\"diagram-pill ok\">Framework owns</span><small class=\"diagram-muted\">SQL isolation &middot; parameterized queries &middot; XSS escaping &middot; auth guard &middot; CSRF cookies &middot; secret encryption</small></div><div class=\"diagram-card you\"><span class=\"diagram-pill warn\">You own</span><small class=\"diagram-muted\">A. tag tables with ownableColumns() &amp; route through access guards<br>B. give every action a Zod schema &amp; send user URLs through the SSRF guard</small></div></div>",
+  "css": ".sec-layers{display:flex;flex-direction:column;gap:12px}.sec-layers .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px}"
+}
+```
+
+표준 패턴을 기반으로 구축하면 프레임워크가 이미 대부분의 위협 표면을 처리합니다.
+
+- **데이터 격리** — 에이전트 SQL가 다시 작성되어 현재 사용자(및 활성 조직)의 행만 볼 수 있습니다. [Data Scoping](#data-scoping)를 참조하세요.
+- **SQL 주입** — `db-query`/`db-exec` 및 Drizzle는 항상 매개변수화됩니다. [SQL Injection Prevention](#sql-injection)를 참조하세요.
+- **XSS** — React 자동 이스케이프, TipTap 및 `react-markdown` 삭제. [XSS Prevention](#xss)를 참조하세요.
+- **인증 및 CSRF** — 모든 `defineAction`는 인증으로 보호됩니다. 쿠키는 `httpOnly` + `SameSite=lax`입니다. [Authentication](#auth)를 참조하세요.
+- **비밀 암호화** — 자격 증명과 저장소는 저장 시 암호화됩니다. [Secrets Management](#secrets)를 참조하세요.
+
+실제로 고려해야 할 작은 표면이 남습니다:
+
+- **A. 범위 지정을 위해 테이블에 태그를 지정하세요.** [`ownableColumns()`](#data-scoping)를 통해 `owner_email`(및 팀 데이터의 경우 `org_id`)를 추가하고 [access guards](#access-guards)를 통해 Drizzle 읽기/쓰기를 라우팅합니다.
+- **B. 외부 입력을 검증하고 라우팅합니다.** 모든 작업에 Zod [`schema:`](#input-validation)를 제공하고 [SSRF guard](#ssrf)를 통해 사용자/에이전트 URL의 서버 측 가져오기를 보냅니다.
+
+이 두 가지를 올바르게 설정하면 나머지는 기본값입니다. [Production Checklist](#production-checklist)는 배송 전 한 페이지의 확인서입니다.
+
+## 보안을 위한 설계 {#secure-by-design}
+
+프레임워크 아키텍처는 표준 패턴을 사용할 때 일반적인 취약점을 방지합니다.
+
+| 취약성      | 프레임워크 보호                                                                  |
+| ----------- | -------------------------------------------------------------------------------- |
+| SQL 주입    | `db-query`/`db-exec` 및 Drizzle ORM의 매개변수화된 쿼리                          |
+| XSS         | React는 JSX를 자동 이스케이프합니다. TipTap은 서식 있는 텍스트를 삭제합니다      |
+| 데이터 유출 | 임시 뷰를 통한 SQL 수준 범위 지정(`owner_email`, `org_id`)                       |
+| 인증 우회   | 인증 가드는 모든 `defineAction` 엔드포인트를 자동 보호합니다                     |
+| 입력 주입   | `defineAction`의 Zod 스키마 유효성 검사                                          |
+| CSRF        | `SameSite=lax` + `httpOnly` 쿠키                                                 |
+| 비밀 노출   | `.env`가 무시되었습니다. 유휴 상태에서 암호화된 자격 증명 및 저장소(AES-256-GCM) |
+| SSRF        | `ssrfSafeFetch`는 내부/메타데이터 대상을 차단하고 리디렉션 리바인딩              |
+
+## 입력 검증 {#input-validation}
+
+모든 작업에 `defineAction`와 Zod `schema:`를 사용하세요. 프레임워크는 코드가 실행되기 전에 자동으로 입력의 유효성을 검사합니다.
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core/action";
+
+export default defineAction({
+  description: "Create a note",
+  schema: z.object({
+    title: z.string().min(1).max(200).describe("Note title"),
+    content: z.string().optional().describe("Note body"),
+  }),
+  run: async (args) => {
+    // args is guaranteed valid — invalid input never reaches here
+  },
+});
+```
+
+잘못된 입력은 명확한 오류 메시지(HTTP의 경우 400, 에이전트 호출의 경우 구조적 오류)를 반환합니다. 레거시 `parameters:` 형식은 런타임 유효성 검사를 제공하지 않습니다.
+
+## SQL 주입 방지 {#sql-injection}
+
+프레임워크의 `db-query` 및 `db-exec` 도구는 매개변수화된 쿼리를 사용합니다. 사용자 입력은 인수로 전달되며 SQL 문자열에 삽입되지 않습니다.
+
+```ts
+// SAFE — parameterized query (framework default)
+await exec({ sql: "INSERT INTO notes (title) VALUES (?)", args: [title] });
+
+// SAFE — Drizzle ORM (always generates parameterized queries)
+await db.insert(notes).values({ title, ownerEmail: email });
+
+// DANGEROUS — string concatenation (never do this)
+await exec(`INSERT INTO notes (title) VALUES ('${title}')`);
+```
+
+```an-callout
+{
+  "tone": "risk",
+  "body": "Never build SQL by string concatenation or template literals. Pass user input as `args` to `exec` / `db-query`, or use Drizzle — both always parameterize. The `pnpm guards` checks catch unscoped and concatenated queries at CI time."
+}
+```
+
+## XSS 예방 {#xss}
+
+React는 모든 JSX 표현식을 자동 이스케이프합니다. 추가 지침:
+
+- 사용자가 제어하는 콘텐츠에는 `dangerouslySetInnerHTML`를 사용하지 마세요
+- 절대 `innerHTML`, `eval()` 또는 `document.write()`를 사용하지 마세요
+- 서식 있는 텍스트 편집의 경우 TipTap(프레임워크 종속성)을 사용하세요. 스키마를 통해 삭제됩니다.
+- 마크다운을 렌더링하려면 `react-markdown`를 사용하세요. React 요소로 안전하게 변환됩니다.
+
+## 서버측 가져오기(SSRF) {#ssrf}
+
+사용자 또는 에이전트가 제어하는 URL의 모든 서버 측 `fetch`는 프레임워크 SSRF 가드를 통과해야 하거나 클라우드 메타데이터(`169.254.169.254`), `localhost` 또는 내부 서비스를 가리킬 수 있습니다.
+
+```ts
+import { ssrfSafeFetch } from "@agent-native/core/extensions/url-safety";
+
+const res = await ssrfSafeFetch(userProvidedUrl, {}, { maxRedirects: 3 });
+```
+
+`ssrfSafeFetch`는 개인/내부 대상을 차단하고, 연결 시 확인된 IP를 다시 확인하고(DNS 리바인딩), 모든 리디렉션 홉을 다시 검증하여 공용 URL가 개인 네트워크로 리디렉션할 수 없도록 합니다. 확장 iframe 프록시, `upload-image` 및 디자인 토큰 가져오기 도구는 모두 이를 통해 라우팅됩니다. 비행 전 확인을 위해서는 `isBlockedExtensionUrlWithDns(url)`와 `redirect: "manual"`를 함께 사용하세요.
+
+## 데이터 범위 지정 {#data-scoping}
+
+프로덕션에서 프레임워크는 에이전트 SQL 쿼리를 현재 사용자의 데이터로 자동으로 제한합니다. 이는 SQL 수준에서 시행되며 에이전트는 이를 우회할 수 없습니다. 이 섹션은 범위 지정 파이프라인에 대한 표준 참조입니다. 역학에 대한 [Authentication](/docs/authentication) 및 [Multi-Tenancy](/docs/multi-tenancy) 문서 링크는 여기에 있습니다.
+
+### 범위 지정 파이프라인 {#scoping-pipeline}
+
+인증된 세션에서 에이전트가 실행하는 SQL까지 범위 지정 흐름:
+
+```
+session.orgId → AGENT_ORG_ID → SQL row scoping
+```
+
+```an-diagram title="The scoping pipeline" summary="Agent SQL never touches base tables directly — it reads through a temporary view scoped to the current identity, so a bare table name can only return owned rows."
+{
+  "html": "<div class=\"scope-pipe\"><div class=\"diagram-node\">Signed-in session<br><small class=\"diagram-muted\">email &middot; orgId</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Request context<br><small class=\"diagram-muted\">AGENT_ORG_ID</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Temporary VIEW<br><small class=\"diagram-muted\">WHERE owner_email = ? AND org_id = ?</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">Agent SQL<br><small class=\"diagram-muted\">bare table names only</small></div></div>",
+  "css": ".scope-pipe{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.scope-pipe .diagram-node{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.scope-pipe .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+로그인된 세션은 `email` 및 (조직이 활성화된 경우) `orgId`를 전달합니다. 프레임워크는 해당 세션에서 요청 컨텍스트를 설정하고, 활성 조직을 에이전트 SQL에 `AGENT_ORG_ID`로 노출하고, 현재 ID가 소유한 행만 볼 수 있도록 모든 쿼리를 다시 작성합니다. 쿼리가 UI, 작업 또는 에이전트에서 발생하는지 여부에 관계없이 동일한 경로가 적용됩니다. 에이전트는 사용자가 구성원이 아닌 조직에 대한 데이터를 읽을 수 없습니다.
+
+### 사용자별 범위 지정(`owner_email`)
+
+사용자별 데이터가 있는 모든 테이블에는 **반드시** `owner_email` 텍스트 열이 있어야 합니다. camelCase Drizzle 속성 이름을 사용하세요. — `accessFilter`는 `resourceTable.ownerEmail`를 읽습니다.
+
+```ts
+import {
+  table,
+  text,
+  integer,
+  ownableColumns,
+} from "@agent-native/core/db/schema";
+
+// Minimal: just the owner column
+export const notes = table("notes", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  content: text("content"),
+  ownerEmail: text("owner_email").notNull(), // REQUIRED — camelCase property
+});
+
+// Or use ownableColumns() to add owner_email + org_id + visibility in one call
+export const notes = table("notes", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  content: text("content"),
+  ...ownableColumns(),
+});
+```
+
+프레임워크는 쿼리를 자동으로 필터링하는 임시 SQL 보기를 생성합니다.
+
+```sql
+CREATE TEMPORARY VIEW "notes" AS
+  SELECT * FROM main."notes"
+  WHERE "owner_email" = 'alice@example.com';
+```
+
+INSERT 문은 열이 아직 없을 때 `owner_email`를 자동으로 삽입합니다.
+
+`db-query` / `db-exec` 도구는 스키마 한정 테이블 참조(`public.<table>`, `main.<table>`)를 거부합니다. 정규화된 이름은 기본 테이블로 확인되고 위의 임시 뷰를 우회합니다. 에이전트는 기본 테이블 이름을 사용합니다. 범위 지정은 자동으로 적용됩니다.
+
+### 조직별 범위 지정(`org_id`)
+
+팀이 데이터를 공유하는 다중 사용자 앱의 경우 `org_id` 열을 추가하세요. 두 열이 모두 있으면 쿼리의 범위는 `WHERE owner_email = ? AND org_id = ?`로 지정됩니다.
+
+`ownableColumns()` 스키마 도우미는 한 번의 호출로 `owner_email`, `org_id` 및 `visibility`를 추가하므로 새 테넌트 인식 테이블은 기본적으로 전체 범위 계약을 얻습니다.
+
+```ts
+import { table, text, ownableColumns } from "@agent-native/core/db/schema";
+
+export const projects = table("projects", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  ...ownableColumns(), // adds owner_email + org_id + visibility
+});
+```
+
+```an-schema title="What ownableColumns() adds" summary="The three columns that make a table tenant-aware and shareable."
+{
+  "entities": [
+    {
+      "id": "ownable",
+      "name": "ownable resource",
+      "note": "Any table that spreads ...ownableColumns()",
+      "fields": [
+        { "name": "owner_email", "type": "text", "nullable": false, "note": "Creator. Auto-filled by write actions; auto-injected on INSERT." },
+        { "name": "org_id", "type": "text", "nullable": true, "note": "Owner's active org at creation. Drives org-visibility checks." },
+        { "name": "visibility", "type": "enum", "nullable": false, "note": "private | org | public — coarse default, defaults to private." }
+      ]
+    }
+  ]
+}
+```
+
+### actions의 액세스 가드 {#access-guards}
+
+원시 에이전트 SQL는 위 임시 보기의 범위에 속합니다. Drizzle를 사용하여 직접 쿼리하는 작업 코드는 프레임워크의 액세스 도우미를 통과해야 읽기 및 쓰기 범위가 현재 ID로 유지됩니다.
+
+- **`accessFilter`** — 현재 사용자/조직이 볼 수 있는 행으로 쿼리를 제한하는 `WHERE` 조건자를 반환합니다. 목록/읽기 쿼리에 사용하세요.
+- **`resolveAccess`** — 현재 요청에 대한 유효 액세스 범위(소유자, 조직, 공유)를 확인합니다.
+- **`assertAccess`** — 쓰기 또는 단일 레코드 읽기를 보호하여 현재 ID가 대상 행에서 작동하지 않을 수 있는 경우 발생합니다.
+
+`ownableColumns()`로 구축된 테이블에는 이러한 범위의 읽기 및 쓰기가 필요합니다. 사용자 정의 Nitro 경로는 소유 가능한 데이터를 쿼리하기 전에 요청 컨텍스트를 설정해야 합니다. `guard-no-unscoped-queries` 검사(`pnpm guards`를 통해 실행)는 CI 시간에 이를 시행합니다. 전체 도우미 API에 대해서는 `sharing` 스킬을 참조하세요.
+
+### 검증
+
+```bash
+pnpm action db-check-scoping           # Check all tables have owner_email
+pnpm action db-check-scoping --require-org  # Also require org_id
+```
+
+## 비밀 관리 {#secrets}
+
+| 비밀번호 유형              | 저장 장소                                                |
+| -------------------------- | -------------------------------------------------------- |
+| 배포 수준 키(앱당 하나)    | `.env` 파일(gitignored, 서버 측에만 해당)                |
+| 사용자별 / 조직별 API 키   | `saveCredential` / `resolveCredential`(저장 시 암호화됨) |
+| 등록된 비밀(사이드바 볼트) | `app_secrets` 볼트(저장 시 암호화됨)                     |
+| OAuth 토큰(구글, GitHub)   | `saveOAuthTokens()`를 통한 `oauth_tokens` 매장           |
+| 세션 토큰                  | 자동(더 나은 인증이 이를 처리함)                         |
+
+사용자별/조직별 자격 증명 및 저장소는 저장 시 `SECRETS_ENCRYPTION_KEY`로 키가 지정된 AES-256-GCM로 암호화됩니다(`BETTER_AUTH_SECRET`로 대체). 생산은 하나 없이는 시작을 거부합니다. 기존 일반 텍스트 자격 증명 행을 암호화하려면 `pnpm action db-migrate-encrypt-credentials`(멱등성, 비파괴)를 실행하세요.
+
+`settings`, `application_state`, 소스 코드 또는 작업 응답에 비밀을 저장하지 마세요. 위의 자격 증명/볼트 API를 사용하세요. 암호화와 사용자별 범위 지정을 모두 처리합니다.
+
+## 인증 {#auth}
+
+인증은 자동입니다. 전체 설정은 [Authentication](/docs/authentication) 문서를 참조하세요.
+
+**보안 핵심 사항:**
+
+- `defineAction` 엔드포인트는 인증 가드에 의해 자동 보호됩니다
+- 사용자 정의 `/api/` 경로는 `getSession(event)`를 호출하고 결과를 확인해야 합니다
+- 상태 변경 작업은 POST(actions의 기본값)를 사용해야 합니다.
+- `SameSite=lax` + `httpOnly` 쿠키는 대부분의 CSRF 공격을 방지합니다.
+
+## A2A 신원 확인 {#a2a-identity}
+
+앱이 A2A 프로토콜을 통해 서로 호출할 때 공유 비밀로 서명된 JWT 토큰을 사용하여 신원을 확인합니다.
+
+```bash
+A2A_SECRET=your-shared-secret-at-least-32-chars
+```
+
+1. 앱 A는 `sub: "steve@example.com"`를 포함하는 JWT에 서명합니다
+2. App B는 동일한 비밀을 사용하여 JWT 서명을 확인합니다
+3. 앱 B는 확인된 `sub` 클레임을 요청 컨텍스트로 읽습니다.
+4. 데이터 범위 지정 적용 — 앱 B에는 Steve의 데이터만 표시됩니다.
+
+프로덕션에 `A2A_SECRET`가 없으면 모든 A2A 엔드포인트와 `/_agent-native/integrations/process-task` 자체 실행 엔드포인트는 **503**을 반환합니다. A2A 트래픽을 호출하거나 수신하는 모든 앱에 설정하세요. (로컬 개발의 경우 프레임워크는 여전히 인증되지 않은 호출을 허용합니다.)
+
+## 인바운드 Webhooks {#webhooks}
+
+인바운드 웹훅 핸들러(Resend, SendGrid, Slack, Telegram, WhatsApp, Recall.ai, Deepgram, Zoom, Google Docs Pub/Sub)는 프로덕션에서 기본적으로 위조된 요청을 거부합니다. 해당 서명 비밀 env var가 누락되면 핸들러는 수락 및 전달 대신 401을 반환합니다.
+
+이것은 이전에는 "경고 및 수락" 입장이었습니다. 그렇지 않으면 놓칠 수 있는 비밀을 설정하거나 로컬 개발자 전용 `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1`를 사용하여 이전 동작을 다시 선택하세요. 통합별 서명 비밀 변수는 [Messaging](/docs/messaging#env-vars)를 참조하세요.
+
+## 제작 체크리스트 {#production-checklist}
+
+### 인증 및 비밀
+
+- [ ] `BETTER_AUTH_SECRET`는 임의의 32자 이상의 문자열(`openssl rand -hex 32`)로 설정됩니다. 단, `A2A_SECRET`에서 파생된 호스팅 작업공간 배포가 아닌 경우
+- [ ] `OAUTH_STATE_SECRET`는 별도의 임의의 32개 이상의 문자 문자열로 설정됩니다(`BETTER_AUTH_SECRET`를 재사용하지 마세요) — [OAuth State Signing](#oauth-state) 참조
+- [ ] A2A 트래픽을 호출하거나 수신하는 모든 앱에 설정된 `A2A_SECRET` — [A2A Identity Verification](#a2a-identity) 참조
+- [ ] `SECRETS_ENCRYPTION_KEY` 세트(또는 `BETTER_AUTH_SECRET` 대체에 의존) - [Secrets Management](#secrets) 참조
+- [ ] `AUTH_SKIP_EMAIL_VERIFICATION`는 프로덕션에서 설정되지 **않습니다**(또는 QA 미리보기 배포에만 설정됨)
+
+### 웹훅 비밀(사용하는 통합에 대한 비밀 설정)
+
+- [ ] 활성화된 각 인바운드 통합에 대한 서명 비밀 세트 - 통합별 목록은 [Inbound Webhooks](#webhooks) 및 [Messaging](/docs/messaging#env-vars)를 참조하세요.
+- [ ] `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS`는 프로덕션에 **설정되지 않았습니다**
+
+### 스키마
+
+- [ ] 모든 사용자 대상 테이블에는 `owner_email`가 있고 다중 사용자 테이블에도 `org_id`가 있습니다. — [Data Scoping](#data-scoping) 참조
+- [ ] 소유 가능한 테이블 읽기/쓰기는 [access guards](#access-guards)를 통과합니다.
+- [ ] 모든 actions는 Zod `schema:`와 함께 `defineAction`를 사용합니다. — [Input Validation](#input-validation) 참조
+- [ ] 사용자/에이전트 URL의 서버 측 가져오기는 `ssrfSafeFetch`를 통과합니다. — [SSRF](#ssrf) 참조
+- [ ] 사용자 콘텐츠가 있는 `dangerouslySetInnerHTML` 없음(또는 출력이 DOMPurify를 통해 실행됨)
+- [ ] 문자열로 연결된 SQL 없음
+- [ ] `pnpm guards`는 깨끗합니다 (`guard-no-unscoped-queries`, `guard-no-env-credentials`, `guard-no-env-mutation`, `guard-no-localhost-fallback`, `guard-no-unscoped-credentials`, `guard-no-drizzle-push`)
+- [ ] 데이터 격리를 확인하기 위해 두 개의 사용자 계정으로 테스트함
+
+### 기타 경화
+
+- [ ] `AGENT_NATIVE_DEBUG_ERRORS`는 실제 제품에서 설정되지 **않습니다**(디버그 미리보기에만 해당)
+- [ ] `AGENT_NATIVE_KEYS_WORKSPACE_FALLBACK`는 조직이 실제로 작업 공간 키를 공유하지 않는 한 **설정되지 않습니다** — [Cross-User Tooling Secrets](#tooling-secrets) 참조
+- [ ] 다중 테넌트 배포에서 **사용자는 자신의 `ANTHROPIC_API_KEY`를 가져옵니다** — 프레임워크는 배포 수준 env var로 폴백하는 것을 거부합니다.
+
+---
+
+아래 섹션에서는 특정 배포에서만 사용할 수 있는 틈새 환경 플래그를 다룹니다. 대부분의 앱은 절대 터치하지 않습니다.
+
+## OAuth 상태 서명 {#oauth-state}
+
+OAuth 흐름(Google, Atlassian, Zoom)은 전용 HMAC 키를 사용하여 상태 봉투에 서명합니다.
+
+```bash
+OAUTH_STATE_SECRET=$(openssl rand -hex 32)
+```
+
+이것은 `GOOGLE_CLIENT_SECRET`(Google과 공유되는 자격 증명)로 대체되었습니다. Google 비밀이 유출되면 공격자가 OAuth 상태 봉투를 위조할 수 있었습니다. 전용 키는 타사 비밀과 무관합니다. `OAUTH_STATE_SECRET`가 설정되지 않은 경우 프레임워크는 `BETTER_AUTH_SECRET`로 대체됩니다. 호스팅된 작업 공간 배포는 이미 필요한 `A2A_SECRET`에서 목적별 OAuth 키를 파생할 수도 있습니다. 해당 서버 비밀을 사용할 수 없으면 OAuth 흐름이 프로덕션에서 실패합니다.
+
+`redirect_uri` 쿼리 매개변수는 허용 목록(동일 출처 + 프레임워크 `/_agent-native/...` 경로)에 대해서도 검증됩니다. 템플릿의 사용자 정의 OAuth 흐름은 상태에 서명하기 전에 프레임워크의 `isAllowedOAuthRedirectUri()` 도우미를 사용해야 합니다.
+
+## 교차 사용자 도구 사용의 비밀 {#tooling-secrets}
+
+`${keys.NAME}`를 참조하는 도구 및 자동화는 기본적으로 사용자별 비밀을 확인합니다. 이 버전에서는 작업 공간 범위 대체가 **기본적으로 꺼져 있습니다**. 그렇지 않으면 악의적인 조직 구성원이 작업 공간 `OPENAI_API_KEY`를 심고 다른 구성원의 API 호출을 수집할 수 있습니다.
+
+귀하의 조직이 실제로 작업 공간 전체 키(예: 단일 회사 Stripe 키)를 공유하는 경우 다음을 사용하여 이전 동작을 다시 선택하세요.
+
+```bash
+AGENT_NATIVE_KEYS_WORKSPACE_FALLBACK=1
+```
+
+작업 영역 범위 비밀 쓰기에는 이 플래그에 관계없이 여전히 조직 소유자/관리자 역할이 필요합니다.

package/corpus/core/docs/content/locales/ko-KR/server.md

@@ -0,0 +1,253 @@
+---
+title: "서버"
+description: "Nitro 서버 경로, 플러그인, 프레임워크 탑재 경로, 요청 컨텍스트 및 SQL 지원 동기화."
+---
+
+# 서버
+
+에이전트 기반 앱은 서버 경로 및 플러그인에 [Nitro](https://nitro.build)를 사용합니다. 대부분의 제품 동작은 [Actions](/docs/actions)에 있어야 합니다. 사용자 정의 경로는 actions가 적합하지 않은 프로토콜 표면(업로드, 스트리밍, 공개 페이지, webhooks, OAuth 콜백 및 공급자별 API)을 위한 것입니다.
+
+```an-diagram title="What runs on the server" summary="Actions are the default. Custom file routes and framework-mounted routes share the same Nitro app and the same SQL database."
+{
+  "html": "<div class=\"diagram-server\"><div class=\"diagram-col entry\"><div class=\"diagram-node\">Browser / UI</div><div class=\"diagram-node\">Agent loop</div><div class=\"diagram-node\">External clients<br><small class=\"diagram-muted\">HTTP · MCP · A2A</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\" data-rough><strong>Nitro server</strong><div class=\"diagram-row\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">default surface</small></div><div class=\"diagram-row\"><span class=\"diagram-pill\">/_agent-native/*</span><small class=\"diagram-muted\">framework routes</small></div><div class=\"diagram-row\"><span class=\"diagram-pill\">/api/*</span><small class=\"diagram-muted\">custom file routes</small></div><div class=\"diagram-row\"><span class=\"diagram-pill\">plugins</span><small class=\"diagram-muted\">startup: migrations, jobs</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL database<br><small class=\"diagram-muted\">Drizzle · the coordination point</small></div></div>",
+  "css": ".diagram-server{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-server .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-server .diagram-panel{display:flex;flex-direction:column;gap:8px;padding:14px 16px}.diagram-server .diagram-row{display:flex;align-items:center;gap:8px}.diagram-server .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 파일 기반 경로 {#file-based-routes}
+
+경로는 `server/routes/`에 있으며 Nitro는 파일 이름을 메서드 및 경로에 매핑합니다.
+
+```text
+server/routes/
+  api/
+    health.get.ts              -> GET  /api/health
+    uploads.post.ts            -> POST /api/uploads
+    webhooks/
+      stripe.post.ts           -> POST /api/webhooks/stripe
+  [...page].get.ts             -> SSR catch-all for public pages
+```
+
+각 경로는 `defineEventHandler`를 내보냅니다.
+
+```ts
+// server/routes/api/health.get.ts
+import { defineEventHandler } from "h3";
+
+export default defineEventHandler(() => ({
+  ok: true,
+  service: "my-template",
+}));
+```
+
+### 경로 명명 규칙 {#route-naming-conventions}
+
+| 파일 이름 패턴     | HTTP 방법 | 예제 경로                |
+| ------------------ | --------- | ------------------------ |
+| `index.get.ts`     | GET       | `/api/items`             |
+| `index.post.ts`    | POST      | `/api/items`             |
+| `[id].get.ts`      | GET       | `/api/items/:id`         |
+| `[id].patch.ts`    | PATCH     | `/api/items/:id`         |
+| `[id].delete.ts`   | DELETE    | `/api/items/:id`         |
+| `[...slug].get.ts` | GET       | `/api/items/*` 또는 포괄 |
+
+## 앱 운영을 위해서는 Actions를 선호하세요 {#actions-first}
+
+UI와 에이전트가 모두 작업을 수행해야 하는 경우 사용자 지정 API 경로 대신 작업을 정의하세요. Actions는 자동으로 다음과 같이 됩니다:
+
+- 에이전트 도구.
+- 유형화된 프런트엔드 후크
+- `/_agent-native/actions/:name` 아래의 HTTP 엔드포인트.
+- MCP 및 A2A 호출 가능 도구.
+- 개발용 CLI 명령.
+
+경로 형태의 프로토콜이나 바이너리/스트리밍 동작이 필요한 경우에만 사용자 지정 `/api/*` 경로를 사용하세요. [Actions](/docs/actions)를 참조하세요.
+
+## 원샷 텍스트 완성 {#complete-text}
+
+대부분의 AI 작업은 사용자가 보고, 조종하고, 감사할 수 있도록 에이전트 채팅을 거쳐야 합니다.
+무슨 일이 일어났나요? 의도적으로 필요하지 않은 좁은 서버측 변환의 경우
+도구, 채팅 기록 또는 실행 상태에서는 `completeText()`를 명시적 이스케이프로 사용
+해치.
+
+```ts
+// actions/classify-message.ts
+import { defineAction } from "@agent-native/core/action";
+import { completeText } from "@agent-native/core/server";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Classify a short message",
+  schema: z.object({ body: z.string() }),
+  run: async ({ body }) => {
+    const result = await completeText({
+      systemPrompt:
+        "Return exactly one label: urgent, follow-up, waiting, or archive.",
+      input: body,
+      maxOutputTokens: 16,
+      temperature: 0,
+    });
+
+    return { label: result.text.trim() };
+  },
+});
+```
+
+`completeText()`는 에이전트와 동일하게 구성된 엔진 계층을 통해 실행됩니다.
+Builder, Anthropic, AI SDK 제공자, 사용자/앱 모델 기본값을 포함한 채팅
+요청 범위의 비밀 및 엔진 정규화된 오류. 서버 전용입니다. 하지 마세요
+클라이언트 코드에서 모델 공급자를 호출합니다. 작업이 사용자를 대상으로 하는 경우 래핑
+UI와 에이전트는 동일한 기능을 공유합니다.
+
+## 컨텍스트 및 액세스 요청 {#request-context}
+
+프레임워크에 의해 마운트된 Actions는 요청 컨텍스트와 함께 자동으로 실행됩니다. 사용자 지정 경로는 그렇지 않습니다. 사용자 정의 경로가 소유 가능한 리소스를 읽거나 쓰는 경우 세션을 로드하고 작업을 래핑합니다.
+
+```an-annotated-code title="Scoping a custom route to the request user"
+{
+  "filename": "server/routes/api/projects.get.ts",
+  "language": "ts",
+  "code": "import { defineEventHandler, createError } from \"h3\";\nimport { getSession, runWithRequestContext } from \"@agent-native/core/server\";\nimport { getDb } from \"../../db/index.js\";\nimport { accessFilter } from \"@agent-native/core/sharing\";\nimport * as schema from \"../../db/schema\";\n\nexport default defineEventHandler(async (event) => {\n  const session = await getSession(event);\n  if (!session?.email) {\n    throw createError({ statusCode: 401, statusMessage: \"Unauthorized\" });\n  }\n\n  return runWithRequestContext(\n    { userEmail: session.email, orgId: session.orgId },\n    async () => {\n      const db = getDb();\n      return db\n        .select()\n        .from(schema.projects)\n        .where(accessFilter(schema.projects, schema.projectShares));\n    },\n  );\n});",
+  "annotations": [
+    { "lines": "7-10", "label": "Custom routes have no auto-context", "note": "Unlike actions, a file route must load the session itself and fail closed when there is no authenticated user." },
+    { "lines": "12-13", "label": "Establish request context", "note": "`runWithRequestContext` makes the user/org available to scoping helpers for the duration of the work." },
+    { "lines": "18-19", "label": "Scope ownable reads", "note": "`accessFilter` constrains the query to rows the caller may see. Never run an unscoped `db.select().from(ownableTable)` here." }
+  ]
+}
+```
+
+`getDb`는 ​​`server/db/index.ts`의 `createGetDb(schema)`를 통해 앱별로 생성되므로 사용자 지정 경로는 `@agent-native/core/db`가 아닌 템플릿(`../../db/index.js`)에서 가져옵니다. [Database — Where the DB Client Lives](/docs/database#db-client)를 참조하세요. 사용자 지정 경로에서 범위가 지정되지 않은 `db.select().from(ownableTable)`를 실행하지 마세요.
+
+## 서버 플러그인 {#server-plugins}
+
+플러그인은 `server/plugins/`에 있으며 시작 시 실행됩니다. 마이그레이션, 공급자 설정, 반복 작업, 통합 어댑터 및 프레임워크 플러그인 구성에 사용하세요.
+
+```ts
+// server/plugins/db.ts
+import { runMigrations } from "@agent-native/core/db";
+
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    )`,
+    },
+  ],
+  { table: "my_app_migrations" },
+);
+```
+
+마이그레이션은 추가적이어야 합니다. 시작 플러그인에 파괴적인 SQL를 넣지 마세요.
+
+## 프레임워크 탑재 경로 {#framework-routes}
+
+프레임워크는 `/_agent-native/` 아래에 자체 경로를 마운트합니다. 해당 네임스페이스를 예약된 것으로 처리하세요.
+
+| 경로 접두어                      | 목적                                                              |
+| -------------------------------- | ----------------------------------------------------------------- |
+| `/_agent-native/actions/:name`   | 액션 HTTP 엔드포인트                                              |
+| `/_agent-native/agent-chat`      | 에이전트 채팅 루프                                                |
+| `/_agent-native/poll`            | SQL 지원 UI 동기화                                                |
+| `/_agent-native/resources/*`     | 작업공간 리소스                                                   |
+| `/_agent-native/extensions/*`    | 런타임 확장 및 확장 프록시(레거시 별칭: `/_agent-native/tools/*`) |
+| `/_agent-native/integrations/*`  | 메시징/웹훅 통합                                                  |
+| `/_agent-native/a2a`             | 에이전트 간 JSON-RPC                                              |
+| `/_agent-native/mcp`             | MCP 엔드포인트                                                    |
+| `/_agent-native/onboarding/*`    | 설정 체크리스트                                                   |
+| `/_agent-native/observability/*` | 추적, 피드백, 평가, 실험                                          |
+| `/_agent-native/file-upload`     | 파일 업로드 공급자 엔드포인트                                     |
+
+맞춤 앱 경로는 `/api/*`, 공개 앱 경로 또는 `/_agent-native/`와 충돌하지 않는 공급자별 콜백 경로를 사용해야 합니다.
+
+## SQL 지원 동기화 {#sync}
+
+에이전트 네이티브는 파일 시스템 감시자나 고정 메모리 내 상태에 의존하지 않습니다. actions 또는 프레임워크 도우미가 데이터를 변경하면 데이터베이스 동기화 버전이 증가합니다. 클라이언트 `useDbSync()` 후크는 `/_agent-native/poll`를 폴링하고 React 쿼리 캐시를 무효화합니다.
+
+데이터베이스가 조정 지점이기 때문에 이는 서버리스 및 다중 인스턴스 배포 전반에 걸쳐 작동합니다. actions 외부에 사용자 정의 변형을 작성하는 경우 프레임워크 도우미를 사용하거나 적절한 동기화 무효화를 내보내 UI 새로 고침을 엽니다.
+
+```an-diagram title="SQL-backed sync loop" summary="No watchers, no sticky state. A write bumps a version in SQL; every client polls the version and refetches."
+{
+  "html": "<div class=\"diagram-sync\"><div class=\"diagram-box\" data-rough>Action / helper<br><small class=\"diagram-muted\">mutates data</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\" data-rough><strong>SQL database</strong><small class=\"diagram-muted\">sync version increments</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&larr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">useDbSync()<br><small class=\"diagram-muted\">polls /_agent-native/poll</small></div><div class=\"diagram-pill ok\">invalidate caches &rarr; UI refreshes</div></div></div>",
+  "css": ".diagram-sync{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sync .diagram-col{display:flex;flex-direction:column;gap:8px;align-items:flex-start}.diagram-sync .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```an-api title="The poll endpoint" method="GET" path="/_agent-native/poll"
+{
+  "method": "GET",
+  "path": "/_agent-native/poll",
+  "summary": "Return the current per-source database sync versions so the client can detect changes.",
+  "description": "`useDbSync()` calls this on an interval (and falls back to it when SSE is unavailable). When a returned version is higher than the client's last-seen value, the matching React Query caches are invalidated and refetch.",
+  "auth": "Session cookie (request-scoped identity)",
+  "responses": [
+    { "status": "200", "description": "Current sync versions keyed by source." }
+  ]
+}
+```
+
+## Webhooks {#webhooks}
+
+인바운드 webhooks는 빠르게 확인하고 유지하며 반환되어야 합니다. 장기 실행 에이전트 작업은 통합 대기열 패턴을 사용해야 합니다.
+
+1. 플랫폼 서명 또는 챌린지를 확인하세요.
+2. SQL에 내구성 있는 작업을 삽입하세요.
+3. 서명된 프로세서 경로를 자체 실행합니다.
+4. 즉시 200을 반환합니다.
+5. 새로운 프로세서 실행이 에이전트 루프를 실행하고 결과를 게시하도록 합니다.
+
+```an-diagram title="Integration queue pattern" summary="The webhook handler returns in milliseconds; a separate signed execution runs the slow agent work."
+{
+  "html": "<div class=\"diagram-webhook\"><div class=\"diagram-box\" data-rough>Inbound webhook<br><small class=\"diagram-muted\">Slack · Stripe · email</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\" data-rough><strong>Handler</strong><div class=\"diagram-step\"><span class=\"diagram-pill\">1</span><small class=\"diagram-muted\">verify signature</small></div><div class=\"diagram-step\"><span class=\"diagram-pill\">2</span><small class=\"diagram-muted\">insert work into SQL</small></div><div class=\"diagram-step\"><span class=\"diagram-pill\">3</span><small class=\"diagram-muted\">self-fire processor</small></div><div class=\"diagram-step\"><span class=\"diagram-pill ok\">4</span><small class=\"diagram-muted\">return 200 now</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Signed processor<br><small class=\"diagram-muted\">runs agent loop, posts result</small></div></div>",
+  "css": ".diagram-webhook{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-webhook .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:14px 16px}.diagram-webhook .diagram-step{display:flex;align-items:center;gap:8px}.diagram-webhook .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+> [!WARNING]
+> 응답을 반환한 후 기다리지 않은 약속에 의존하지 마십시오. 서버리스 호스트는 실행을 정지시킵니다. 정식 통합 대기열은 [Messaging](/docs/messaging)를 참조하세요.
+
+## 고급: 탈출 해치 {#advanced-escape-hatches}
+
+대부분의 템플릿에는 이러한 항목이 필요하지 않습니다. Nitro 파일 경로 및 프레임워크 에이전트
+채팅 플러그인이 이미 앱 서버와 프로덕션 에이전트 핸들러를 연결했습니다.
+외부에서 맞춤형 서버 통합을 구축할 때만 접근하세요
+표준 템플릿 플러그인 스택.
+
+### 프로그래밍 방식의 H3 서버 {#create-server}
+
+H3 앱이 직접 필요한 사용자 정의 패키지 또는 테스트의 경우 `createServer()`
+사전 구성된 앱과 라우터를 반환합니다:
+
+```ts
+import { createServer } from "@agent-native/core/server";
+import { defineEventHandler } from "h3";
+
+const { app, router } = createServer();
+
+router.get(
+  "/api/health",
+  defineEventHandler(() => ({ ok: true })),
+);
+```
+
+### 프로덕션 에이전트 핸들러 {#agent-handler}
+
+프레임워크의 에이전트 채팅 플러그인은 이미 프로덕션 에이전트 핸들러를 마운트하고 있습니다.
+템플릿용. 건물을 지을 때는 `createProductionAgentHandler()`만 직접 호출하세요
+표준 템플릿 플러그인 스택 외부의 사용자 정의 서버 통합 —
+그렇지 않으면 `AGENTS.md`, skills, actions를 통해 에이전트를 사용자 정의하고
+상담원 채팅 플러그인.
+
+```ts
+import { createProductionAgentHandler } from "@agent-native/core/server";
+
+const handler = createProductionAgentHandler({
+  scripts,
+  systemPrompt: "You are the app agent...",
+});
+```