---
url: https://docs.ogmabox.com/ko/plugins/frontend-sdk.md
description: Ogma 프런트엔드 플러그인 API, iframe 통합, 브리지 호출, UI 패널, 명령 및 호스트 통신 참조입니다.
---

# 플러그인 프런트엔드 SDK 참조 {#plugin-frontend-sdk-reference}

플러그인 프런트엔드 코드는 샌드박스 iframe 안에서 실행됩니다. 이 문서는 저수준 참조입니다. 개요는 [README.md](./README.md)를 확인하세요.

***

## 보안 모델 {#security-model}

| 속성 | 값 |
|----------|-------|
| Iframe 샌드박스 | `allow-scripts`만 허용(`allow-same-origin` 없음) |
| CSP `script-src` | nonce로 제한되며 진입점 스크립트만 로드됨 |
| CSP `connect-src` | `'self'` - 플러그인이 `/plugins/{id}/api/*`에 POST 요청을 보내고 `/plugins/{id}/events/poll`을 폴링할 수 있음 |
| CSP `default-src` | `'none'` |
| 부모 DOM 접근 | 차단됨(`allow-same-origin` 없음) |
| Ogma 세션 쿠키 | 플러그인에서 접근 불가 |
| 플러그인 간 통신 | 사용 불가 |

데이터 브리지 호출은 모든 요청에 대해 서버 측에서 권한을 확인하며, 표시 및 탐색 동작은 호스트 UI가 처리합니다. 권한 탭에 표시되는 권한 캐시는 표시용일 뿐, 데이터 접근을 제어하지 않습니다.

***

## 브리지 프로토콜 {#bridge-protocol}

플러그인 JS는 `postMessage`를 통해 Ogma 호스트와 통신합니다. 호스트는 `PluginsView.vue`에 있으며 `bridge_request` 메시지를 처리합니다.

### 요청 메시지 형식 {#request-envelope}

```ts
interface BridgeRequest {
  type: 'bridge_request'
  sessionId: string     // nonce assigned when the bridge is set up; prevents stale messages
  requestId: string     // caller-generated correlation id (max 128 chars)
  command: string       // e.g. "ogma.requests.get"
  payload?: unknown     // command-specific input
}
```

전체 메시지 크기 상한: 65 536바이트.

### 응답 메시지 형식 {#response-envelope}

```ts
interface BridgeResponse {
  type: 'bridge_response'
  requestId: string
  ok: boolean
  result?: unknown
  error?: string
  code?: string
}
```

### SDK 사용(권장) {#using-the-sdk-recommended}

원시 `postMessage` 브리지 요청을 수동으로 보내지 마세요. 전역 객체 `ogmaSDK`를 사용하세요.

```js
ogmaSDK.ready(function(sdk) {
  sdk.meta.get().then(function(meta) {
    sdk.log.info("running as " + meta.pluginId);
  });
});
```

SDK는 모든 브리지 통신을 감싸고 요청과 응답의 대응 관계, sessionId 관리 및 Promise 완료 처리를 담당합니다.

***

## 명령 참조 {#command-reference}

### `ogma.meta.get` {#ogma-meta-get}

페이로드가 필요하지 않습니다.

`{ pluginId, packageId, name, version, ogmaVersion }`을 반환합니다.

### `ogma.requests.get` {#ogma-requests-get}

페이로드: `{ id: string }`

일부 필드로 구성된 HTTP 항목을 반환합니다. 필드: `id`, `method`, `host`, `port`, `path`, `query`, `req_len`, `resp_status`, `resp_len`, `roundtrip_ms`, `created_at`. 이 데이터에는 헤더나 본문 바이트가 포함되지 않습니다.

필요 권한: `read_http_history`(자동 부여).

### `ogma.requests.getRaw` {#ogma-requests-getraw}

페이로드: `{ id: string }`. `sdk.requests.getRaw(id)`를 통해 호출합니다.

`requestBodyBase64`, `responseBodyBase64`, 디코딩된 길이(`requestBodyLength`, `responseBodyLength`), `requestBodyTruncated`, `responseBodyTruncated`, `maxBodyBytes`를 반환합니다. 이름과 달리 이 작업은 전체 원시 HTTP 메시지가 아닌 본문 바이트를 반환합니다. 지원되는 콘텐츠 인코딩은 반환 데이터를 구성하기 전에 디코딩됩니다. 각 본문은 256 KiB로 제한되므로 전체 에셋을 처리하기 전에 잘림 플래그를 확인하세요.

필요 권한: `read_http_history`(자동 부여).

### `ogma.requests.search` {#ogma-requests-search}

페이로드: `{ limit?: number, offset?: number, query?: string }`

`query`는 HTTPQL 필터 표현식을 지원합니다. `limit` 상한: 20. `{ items: [...], total: number, limit: number, offset: number }`를 반환합니다.

필요 권한: `read_http_history`(자동 부여).

### `ogma.findings.list` {#ogma-findings-list}

페이로드: `{ limit?: number, offset?: number }`

`{ items: [...], total: number, limit: number, offset: number }`를 반환하며, 페이지당 발견 사항은 최대 20개입니다. 항목은 요약 정보이며 `id`, `title`, `severity`, `status`, `reporter`, `tags`, `created_at` 필드를 포함합니다.

필요 권한: `read_findings`(자동 부여).

### `ogma.scope.getActive` {#ogma-scope-getactive}

페이로드가 필요하지 않습니다. 활성 점검 범위 프리셋 또는 `null`을 반환합니다.

필요 권한: `read_scope`(자동 부여).

### `ogma.projects.getCurrent` {#ogma-projects-getcurrent}

페이로드가 필요하지 않습니다. `{ id, name, status }` 또는 `null`을 반환합니다.

필요 권한: `read_projects`(자동 부여).

### `ogma.log` {#ogma-log}

페이로드: `{ message: string }`

플러그인 로그 버퍼에 기록합니다.

### `ogma.ui.resize` {#ogma-ui-resize}

페이로드: `{ height: number }`(최대 2000)

호스트에 iframe 높이 설정을 요청합니다.

### `ogma.ui.sidebar.registerItem` {#ogma-ui-sidebar-registeritem}

페이로드: `{ name: string, path: string }`(이름 최대 64자, 경로 최대 256자)

플러그인 패널 내 탐색 항목을 등록합니다. 플러그인당 최대 20개입니다. `sdk.navigation.addPage(path, { title, body })`로 해당 페이지 내용을 등록하세요. 항목을 선택하면 새로운 Ogma 최상위 워크스페이스 라우트가 아닌 iframe 내부에 해당 페이지가 표시됩니다.

### `ogma.backend.call` {#ogma-backend-call}

페이로드: `{ method: string, args: unknown[] }`

`sdk.api.register(method, fn)`으로 등록된 백엔드 RPC 핸들러를 호출합니다. 메서드 이름의 최대 길이는 64자입니다.

백엔드 핸들러가 반환한 값을 JSON으로 직렬화하여 반환합니다.

### `ogma.backend.onEvent` {#ogma-backend-onevent}

페이로드: 필요 없음.

수신 확인만 합니다. 실제 이벤트 조회에는 `ogma.events.poll`을 사용하세요.

### `ogma.events.poll` {#ogma-events-poll}

페이로드: `{ since: number }`(마지막 폴링의 인덱스, 시작값은 0)

`{ events: [{ event: string, args: unknown[] }], next_since: number }`를 반환합니다.

### `ogma.navigation.addPage` {#ogma-navigation-addpage}

페이로드: `{ path: string, title?: string }`

브리지는 페이지 경로의 수신을 확인합니다. 주입된 SDK는 `sdk.navigation.addPage(path, options)`의 옵션으로 `{ body: HTMLElement }`도 받아 iframe 안에 내용을 붙이고, 호스트에서 해당 사이드바 항목을 선택하면 페이지 표시 여부를 전환합니다. DOM 노드는 로컬에 남으며 브리지를 통해 직렬화되지 않습니다.

### `ogma.window.showToast` {#ogma-window-showtoast}

페이로드: `{ message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }`

플러그인 패널에 토스트를 표시합니다. 표시 시간은 ms 단위입니다(최대 10000, 기본값 3000).

### `ogma.commands.register` {#ogma-commands-register}

페이로드: `{ id: string, name: string }`

호스트 명령 저장소에 플러그인 명령을 등록합니다. 호스트에서 실행하면 `commandId`와 컨텍스트가 포함된 `plugin_command` 메시지를 iframe으로 보내며, 플러그인은 해당 콜백을 제공해야 합니다. 등록만으로 명령이 실행되지는 않습니다.

### `ogma.menu.registerItem` {#ogma-menu-registeritem}

페이로드: `{ type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }`

플러그인 명령에 연결된 컨텍스트 메뉴 항목을 등록합니다. 먼저 명령을 등록하세요. 레이블은 기본적으로 등록된 명령 이름을 사용하고, 이름이 없으면 ID를 사용합니다. `type`을 생략하면 기본값은 `Request`입니다. 호스트 브리지는 `leadingIcon`을 사용하지 않습니다.

### 테마 도우미 {#theme-helpers}

주입된 SDK는 `sdk.theme.get()`과 `sdk.theme.onChange(callback)`도 제공합니다. 별도의 데이터 브리지 명령 없이 iframe 테마를 읽고 호스트의 테마 업데이트를 구독합니다. 플러그인 UI를 Ogma의 라이트/다크 테마와 일관되게 유지하는 데 사용하세요.

***

## 오류 코드 {#error-codes}

| 코드 | 의미 |
|------|---------|
| `PERMISSION_DENIED` | 플러그인에 필요한 권한이 없습니다. |
| `PLUGIN_DISABLED` | 플러그인이 현재 활성화되어 있지 않습니다. |
| `UNKNOWN_COMMAND` | 지원 목록에 없는 명령입니다. |
| `INVALID_PAYLOAD` | 필수 페이로드 필드가 없거나 타입이 올바르지 않습니다. |
| `NOT_FOUND` | 요청한 리소스가 존재하지 않습니다. |
| `LIMIT_EXCEEDED` | 플러그인별 개수 제한에 도달했습니다(예: 사이드바 항목). |
| `SERVER_ERROR` | 내부 오류입니다. 플러그인 로그를 확인하세요. |

***

## 지원 명령 목록 {#supported-commands-list}

`ogma.meta.get`, `ogma.log`, `ogma.ui.resize`, `ogma.ui.sidebar.registerItem`, `ogma.requests.get`, `ogma.requests.getRaw`, `ogma.requests.search`, `ogma.findings.list`, `ogma.scope.getActive`, `ogma.projects.getCurrent`, `ogma.backend.call`, `ogma.backend.onEvent`, `ogma.events.poll`, `ogma.navigation.addPage`, `ogma.window.showToast`, `ogma.commands.register`, `ogma.menu.registerItem`.