@xid-kit/electron

SDK de Electron con flujo PKCE en el proceso principal, preload contextBridge, almacenamiento de tokens en el llavero del SO y estrategias de callback loopback o esquema personalizado.

Estado

Estado del registro: UNPUBLISHED. Instala este SDK únicamente desde el checkout del código fuente del repositorio; no uses un registro de paquetes externo.

El estado del paquete es Paquete actual. La app del proceso principal, el preload contextBridge y el bridge del lado del renderer están implementados. Una prueba de ida y vuelta real contra un IdP en infraestructura de producción está pendiente de verificación manual.

Puntos de entrada

Entrada	Propósito
`@xid-kit/electron`	Exportación por defecto: superficie de renderizado y tipos
`@xid-kit/electron/main`	Solo proceso principal: XidElectronApp
`@xid-kit/electron/renderer`	Proceso de renderizado: getXidBridge, XidClient
`@xid-kit/electron/preload`	Script de precarga listo para usar que expone window.xidBridge

Configuración del proceso principal

// 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))
})

Script de precarga

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

Proceso de renderizado

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 the current unexpired access token. Expiry requires a new sign-in.
const token = await bridge.getAccessToken() // null when signed out or expired

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

// Clear local tokens. No refresh or revoke request is sent.
await bridge.signOut()

Esquema personalizado (alternativa al loopback)

// 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)

Almacenamiento de tokens

Los tokens se cifran con safeStorage.encryptString() (llavero del SO) y se almacenan como archivos binarios en app.getPath('userData')/xid-tokens/ por defecto.
Si safeStorage.isEncryptionAvailable() devuelve false (Linux headless sin llavero), setItem() lanza ElectronStorageError con el código encryption_unavailable en lugar de escribir en texto plano silenciosamente.
Anula el directorio de almacenamiento con storageDir en XidElectronMainOptions.

Contrato nativo compartido

Método	Descripción
`signIn(options?)`	Abre el navegador del sistema, intercambia el código y almacena los tokens
`signOut()`	Limpia los tokens locales
`getAccessToken()`	Devuelve el token de acceso actual no caducado sin actualizarlo; borra el estado local caducado y devuelve null. El SDK rechaza offline_access hasta que se implemente DPoP.
`getSession()`	Devuelve el accessToken y expiresAt actuales no caducados, o null