ui_page developer SDK

cdnca-plugin-ui.mjs (in-frame SDK)

// cdnca ui_page plugin SDK (inside the frame), protocol cdnca.plugin-ui/v1.
// See docs/developer/plugin-integration.md §8.3. No dependencies; serve it
// from your own page origin and load it as an ES module:
//
//   import { connect } from './cdnca-plugin-ui.mjs'
//   const host = await connect()
//   const ctx = await host.context()           // user / tenant / site / locale / theme, no credentials
//   const res = await host.request({ method: 'GET', path: '/reports', query: 'range=7d' })
//   // res = { status, body }: your backend's answer, relayed by the control plane
//   await host.navigate('/site/list')          // in-app path; auth pages are refused
//
// The page runs in <iframe sandbox="allow-scripts allow-forms"> (opaque
// origin): no cookies or storage of the control plane, and no
// credentials of the user. Everything goes through one private MessagePort
// the host hands over after "cdnca.hello"; the host answers only these
// three methods (anything else: error "message_not_allowed").

export const PROTOCOL = 'cdnca.plugin-ui/v1'

export class PluginUIError extends Error {
  constructor(code) {
    super(code)
    this.name = 'PluginUIError'
    this.code = code
  }
}

/** The mount nonce the host put in the URL fragment (#cdnca-nonce=...). */
export function readNonce(hash = globalThis.location?.hash ?? '') {
  const value = new URLSearchParams(String(hash).replace(/^#/, '')).get('cdnca-nonce')
  if (!value || !/^[A-Za-z0-9_-]{16,64}$/.test(value)) throw new PluginUIError('nonce_missing')
  return value
}

/**
 * connect performs the hello handshake and resolves to the host API.
 * options: { window, timeoutMs, requestTimeoutMs } (window for tests).
 */
export function connect(options = {}) {
  const win = options.window ?? globalThis.window
  const timeoutMs = options.timeoutMs ?? 10000
  const requestTimeoutMs = options.requestTimeoutMs ?? 30000
  const nonce = readNonce(win.location.hash)
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => {
      win.removeEventListener('message', onReady)
      reject(new PluginUIError('handshake_timeout'))
    }, timeoutMs)
    function onReady(event) {
      // Only the parent (the control plane web app) hands over the port.
      const data = event.data
      if (event.source !== win.parent || !data || data.protocol !== PROTOCOL || data.type !== 'cdnca.ready' ||
        data.nonce !== nonce || !event.ports || event.ports.length !== 1) return
      clearTimeout(timer)
      win.removeEventListener('message', onReady)
      resolve(createHost(event.ports[0], nonce, requestTimeoutMs))
    }
    win.addEventListener('message', onReady)
    // The host's origin is the control plane domain the customer runs; the
    // hello carries nothing secret, the port it answers with is private.
    win.parent.postMessage({ protocol: PROTOCOL, type: 'cdnca.hello', nonce }, '*')
  })
}

function createHost(port, nonce, requestTimeoutMs) {
  const pending = new Map()
  let sequence = 0
  port.onmessage = (event) => {
    const data = event.data
    if (!data || data.protocol !== PROTOCOL || data.nonce !== nonce || !pending.has(data.id)) return
    const { resolve, reject, timer } = pending.get(data.id)
    pending.delete(data.id)
    clearTimeout(timer)
    if (data.ok) resolve(data.result)
    else reject(new PluginUIError(typeof data.error === 'string' ? data.error : 'request_failed'))
  }
  port.start?.()
  function call(method, params) {
    const id = `r${++sequence}`
    return new Promise((resolve, reject) => {
      const timer = setTimeout(() => {
        pending.delete(id)
        reject(new PluginUIError('request_timeout'))
      }, requestTimeoutMs)
      pending.set(id, { resolve, reject, timer })
      port.postMessage({ protocol: PROTOCOL, nonce, id, method, ...(params === undefined ? {} : { params }) })
    })
  }
  return {
    /** Non-sensitive context: { plugin_id, page_id, user, tenant, site_id, locale, theme }. */
    context: () => call('context.get'),
    /** Move the host to an in-app relative path. */
    navigate: (path) => call('navigate', { path }),
    /**
     * Call your own backend (api_base_url + path) through the control plane.
     * request: { method: GET|POST|PUT|PATCH|DELETE, path: '/x', query?: 'a=1', body?: JSON (not with GET) }.
     */
    request: (request) => call('api.request', request),
    close: () => port.close(),
  }
}
Copy

verify-backend.mjs (backend verifier)

// Plugin backend side (Node.js 18+): verify a call the cdnca control plane
// proxied from a ui_page (docs/developer/plugin-integration.md §8.3).
//
//   const verifier = createVerifier({ publicKey, keyId, basePath: '/v1' })
//   const context = verifier.verify({ method, pathWithQuery, body, headers })
//
// publicKey / keyId: shown on the control plane's plugin installation detail
// ("安装签名公钥", GET /v1/plugin-ui/signing-key). basePath is the path part
// of your api_base_url: the signature covers the path relative to it.
// verify throws on any failure; on success it returns the decoded context
// (installation_id, plugin_id, page_id, user_id, role, tenant_scope_id,
// site_id, locale, request_id, nonce, issued_at, expires_at).

import { createHash, createPublicKey, verify as verifySignature } from 'node:crypto'

export const SIGNATURE_DOMAIN = 'cdnca-plugin-ui-proxy/v1'
export const CONTEXT_SCHEMA = 'cdnca.plugin-ui-context/v1'

export function signatureMessage(method, target, body, contextHeader) {
  const digest = createHash('sha256').update(body).digest('hex')
  return Buffer.from(`${SIGNATURE_DOMAIN}\n${method}\n${target}\n${digest}\n${contextHeader}`, 'utf8')
}

function header(headers, name) {
  const value = typeof headers.get === 'function' ? headers.get(name) : headers[name.toLowerCase()] ?? headers[name]
  if (typeof value !== 'string' || !value) throw new Error(`missing ${name}`)
  return value
}

export function createVerifier({ publicKey, keyId, basePath = '', now = () => Date.now(), nonceTTLms = 120000 }) {
  const key = createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: publicKey }, format: 'jwk' })
  const prefix = basePath.replace(/\/$/, '')
  // Each nonce is accepted once within its validity (use a shared store if
  // you run several backend instances).
  const seen = new Map()
  return {
    verify({ method, pathWithQuery, body = Buffer.alloc(0), headers }) {
      if (header(headers, 'X-Cdnca-Plugin-Key-Id') !== keyId) throw new Error('unknown key id')
      if (prefix && !pathWithQuery.startsWith(`${prefix}/`)) throw new Error('path outside api_base_url')
      const target = pathWithQuery.slice(prefix.length)
      const contextHeader = header(headers, 'X-Cdnca-Plugin-Context')
      const signature = Buffer.from(header(headers, 'X-Cdnca-Plugin-Signature'), 'base64url')
      const raw = Buffer.isBuffer(body) ? body : Buffer.from(body)
      if (!verifySignature(null, signatureMessage(method.toUpperCase(), target, raw, contextHeader), key, signature)) {
        throw new Error('bad signature')
      }
      const context = JSON.parse(Buffer.from(contextHeader, 'base64url').toString('utf8'))
      const current = now()
      if (context.schema !== CONTEXT_SCHEMA) throw new Error('unknown context schema')
      if (Date.parse(context.issued_at) > current + 30000 || Date.parse(context.expires_at) <= current) {
        throw new Error('context expired')
      }
      for (const [nonce, expires] of seen) if (expires <= current) seen.delete(nonce)
      if (seen.has(context.nonce)) throw new Error('replayed nonce')
      seen.set(context.nonce, current + nonceTTLms)
      return context
    },
  }
}
Copy