---
title: "@xid-kit/electron"
description: "메인 프로세스 PKCE 흐름, contextBridge preload, OS keychain 토큰 저장소, loopback 또는 사용자 정의 스킴 콜백 전략이 있는 Electron SDK."
locale: "ko"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/ko/llms.txt
> Use this file to discover all available pages before exploring further.

# @xid-kit/electron

## 상태

패키지 상태: **현재 패키지**. 메인 프로세스 앱, contextBridge preload, 렌더러 측 브리지가 구현되었습니다. 프로덕션 인프라에서의 실제 IdP 왕복 테스트는 아직 수동 검증 대기 중입니다.

## 진입점

| 항목 | 목적 |
| --- | --- |
| `@xid-kit/electron` | 기본 내보내기: 렌더러 인터페이스 및 타입 |
| `@xid-kit/electron/main` | 메인 프로세스 전용: XidElectronApp |
| `@xid-kit/electron/renderer` | 렌더러 프로세스: getXidBridge, XidClient |
| `@xid-kit/electron/preload` | window.xidBridge를 노출하는 기성 preload 스크립트 |

## 메인 프로세스 설정

```ts
// main.ts
import { app, ipcMain } from 'electron'
import { XidElectronApp } from '@xid-kit/electron/main'

const xidApp = new XidElectronApp({
  issuer: 'https://xid.dev',
  clientId: 'client_abc123',
  // callbackStrategy: 'loopback' (default, RFC 8252 s.7.3) | 'custom-scheme'
})

app.whenReady().then(async () => {
  await xidApp.init(ipcMain)
  const win = new BrowserWindow({
webPreferences: {
  contextIsolation: true,
  preload: path.join(__dirname, 'preload.js'),
},
  })
  win.on('closed', () => xidApp.dispose(ipcMain))
})
```

## Preload 스크립트

```ts
// preload.ts
import '@xid-kit/electron/preload'
// Exposes window.xidBridge with storage, signIn, signOut,
// getAccessToken, getSession, setTokenStorage
```

## 렌더러 프로세스

```ts
import { getXidBridge } from '@xid-kit/electron/renderer'

const bridge = getXidBridge()

// Opens system browser, waits for loopback callback, exchanges code.
const accessToken = await bridge.signIn()

// Get current access token (transparently refreshes if near expiry).
const token = await bridge.getAccessToken() // null when not signed in

// Get full session (accessToken + expiresAt in epoch seconds).
const session = await bridge.getSession()

// Sign out and clear tokens.
await bridge.signOut()
```

## 사용자 정의 스킴(loopback의 대안)

```ts
// main.ts
import { app } from 'electron'
import { XidElectronApp } from '@xid-kit/electron/main'

app.setAsDefaultProtocolClient('myapp')

const xidApp = new XidElectronApp({
  issuer: 'https://xid.dev',
  clientId: 'client_abc123',
  callbackStrategy: 'custom-scheme',
  customScheme: 'myapp',  // redirect_uri = myapp://callback
})

xidApp.registerDeepLinkHandler(app)
```

## 토큰 저장소

- 토큰은 `safeStorage.encryptString()`(OS keychain)으로 암호화되어 기본적으로 `app.getPath('userData')/xid-tokens/`에 바이너리 파일로 저장됩니다.
- `safeStorage.isEncryptionAvailable()`이 `false`(키링이 없는 헤드리스 Linux)를 반환하면, `setItem()`은 평문을 조용히 쓰는 대신 코드 `encryption_unavailable`로 `ElectronStorageError`를 발생시킵니다.
- `XidElectronMainOptions`의 `storageDir`으로 저장소 디렉터리를 재정의하세요.

## 공유 네이티브 계약

| 방법 | 설명 |
| --- | --- |
| `signIn(options?)` | 시스템 브라우저를 열고 코드를 교환하며 토큰을 저장합니다 |
| `signOut()` | 로컬 토큰 삭제 |
| `getAccessToken()` | 현재 토큰을 반환합니다(만료가 임박하면 갱신). 로그아웃 시 null을 반환합니다 |
| `getSession()` | accessToken과 expiresAt을 반환하거나 null을 반환합니다 |

Source: https://xid.dev/ko/sdks/electron/index.mdx