Embed by link: a kit editor in a signed iframe (@kition/embed-server)

Run @kition/embed-server, mint a signed iframe URL on your server for one person and one file, and answer the HMAC-signed callbacks that read and save the file in your storage. Single-user, free, no key.

For integrators that cannot run @kition/embed in their own page: your server mints a URL, your page frames it, and the embed server (@kition/embed-server) shows the kit's editor and reads and writes the document through HTTP callbacks to your server. Single-user: co-editing goes through Kition Server (Co-editing). Design: url-embedding.md. A runnable example is examples/url-embed (node examples/url-embed/serve.mjs).

<iframe src="https://docs.example.com/v1/open?token=ko1.…" allow="clipboard-read; clipboard-write; fullscreen"></iframe>

1. Run the embed server

npm i @kition/embed-server

It needs Node 20.6 or later, and brings @kition/embed (the editor page's module) and @kition/sync with it.

import { startEmbedServer } from '@kition/embed-server'

await startEmbedServer({
  id: 'docs-example',                   // the `aud` your tokens name
  secret: process.env.DOC_SESSION_SECRET, // ≥ 32 characters, signs the page's sessions
  integrators: [{
    iss: 'acme.app',                     // the `iss` your tokens name
    keys: [{ kid: 'acme-1', publicKey: '<base64url Ed25519>', tenant: 'acme', iss: 'acme.app' }],
    callbackUrl: 'https://app.acme.com/kition',
    secret: process.env.ACME_CALLBACK_SECRET, // shared with you; signs every callback
    origins: ['https://app.acme.com'],   // who may frame the editor
  }],
  kits: [{ id: 'kit.note', path: 'note-ui/', extensions: ['.md'] }], // one entry per kit package you serve
  kitsUrl: 'https://cdn.example.com/kition/',  // kit packages: static files on your CDN (or kitsDir + kitsPort)
  host: '0.0.0.0',                       // default 127.0.0.1
  port: 8080,
})

createEmbedServer(config) gives the same as a Node http handler for your own server. The editor page's module is the installed @kition/embed's dist; embedDir names another.

Or run it with no code of your own, from a file holding those options (.json, or a module whose default export they are, so secrets can come from process.env):

npx @kition/embed-server ./embed-server.config.mjs   # or kition-embed-server, once installed

2. Mint the iframe URL

On your server, for a person you signed in and a file they may open, sign an open token (ko1., the same as managed co-editing, managed-collab.md section 1) with signOpenToken from @kition/sync/openToken (or the Rust crate kition-open-token):

const token = await signOpenToken({
  iss: 'acme.app', aud: 'docs-example', tenant: 'acme',
  sub: user.id, name: user.name,
  file: 'res-42',            // your immutable file id
  version: 'v7',             // the version you open
  doc_key: 'res-42.g3',      // the file's generation: change it when the file is replaced
  perms: { edit: true, comment: true, download: true, share: false, export: true },
  watermark: null,           // or { text: 'Ann · Confidential' }
  iat: now, exp: now + 300,  // at most an hour; a few minutes is enough
}, 'acme-1', privateKey)
const src = `https://docs.example.com/v1/open?token=${encodeURIComponent(token)}`

Decide perms from your own ACL at that moment. The token only opens the page: the page then works on a session the embed server signed (8 hours by default), and drops the token from its address.

permsThe editor
editEdits and saves
comment (without edit)Read-only content, comments, saves the comments
neitherView only; the embed server refuses its writes (403)
download, export, shareShows Download, Export and Print, Share only when true
watermarkDrawn over the document

3. Answer the callbacks

The embed server calls, under your callbackUrl:

RequestAnswer
HEAD /files/{file}200 with X-Kition-Version and X-Kition-Name (the file name picks the kit); 404
GET /files/{file}200 with the bytes and X-Kition-Version; 404
PUT /files/{file} with If-Match: <version>200 {"version": "<new>"}; 409 with X-Kition-Version when the file moved on or X-Kition-Doc-Key is not its generation
GET /files/{file}/replica200 with the stored replica and X-Kition-File-Stamp; 404 none; 501 not kept
PUT /files/{file}/replica with X-Kition-File-Stamp200; 501 not kept

Every request carries X-Kition-Timestamp, X-Kition-Subject (the token's sub), X-Kition-Doc-Key, and X-Kition-Signature: v1=<hex>, the HMAC-SHA256 with your callback secret of

METHOD "\n" path-and-query "\n" timestamp "\n" hex(SHA-256(body))

Verify it before anything else, and refuse a timestamp more than 300 s off:

import { verifyCallback } from '@kition/embed-server/callbacks'
if (!verifyCallback(secret, { method: req.method, path: req.url, headers: req.headers, body })) return res.writeHead(401).end()

Versions are yours (opaque strings that change on every write). Never accept a write without checking If-Match against the current version: that is what keeps two open tabs, or a stale one, from writing over each other.

4. Hear the editor

The page posts { kitionDocument: 1, event: 'ready' } and { kitionDocument: 1, event: 'saved', version } to its parent.

Security notes

  • The embed server keeps no document: every read and write is a callback to you.
  • The page's content security policy allows only the embed server's scripts, only kitsUrl frames, and only your origins as framers.
  • Display permissions (download, export, share, watermark) are what the editor shows; they do not stop a person who can read a document from copying it.
From kition-sdk docs/sdk/url.md, where the snippets are tested.Source on GitHub