@kition/doc-service 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# @kition/doc-service
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Kits document service, for URL embedding: your page frames a URL your server minted, and the
+service shows a Kition kit editor there (the Note kit today; other kits are not published yet), reading and
+writing the file through HMAC-signed HTTP callbacks to your server. It keeps no document.
+Single-user; for co-editing see `@kition/embed`. An ES module with type declarations, for Node 20.6
+or later, and a `kition-doc-service` command.
+
+```sh
+npm i @kition/doc-service
+```
+
+```ts
+import { startDocService } from '@kition/doc-service'
+
+const service = await startDocService({
+  id: 'docs-example',                     // the `aud` your open tokens name
+  secret: process.env.DOC_SESSION_SECRET!, // at least 32 characters, signs the page's sessions
+  integrators: [{
+    iss: 'acme.app',                       // the `iss` your open 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 your server; 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://kits.example.com/',    // the kit packages, on another origin (or kitsDir and kitsPort)
+  host: '0.0.0.0',                         // default 127.0.0.1
+  port: 8080,
+})
+console.log(service.url)
+```
+
+`createDocService(config)` is the same as a Node `http` handler for your own server. The editor
+page's module is the installed `@kition/embed` (a dependency); `embedDir` points elsewhere.
+
+Or run it from a config file with those options (`.json`, or a module whose default export they are):
+
+```sh
+npx @kition/doc-service ./doc-service.config.mjs
+```
+
+Your server signs the iframe URL's open token with `signOpenToken` from `@kition/sync/openToken`,
+and checks each callback with `verifyCallback` from `@kition/doc-service/callbacks` (it needs only
+`node:crypto`). TypeScript projects need `@types/node`.
+
+Documentation: https://dev.kition.ai/url
+
+License: Apache-2.0

package/dist/LICENSE

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/dist/callbacks.d.ts

@@ -0,0 +1,30 @@
+export declare const SIGNATURE_HEADER = "x-kition-signature";
+export declare const TIMESTAMP_HEADER = "x-kition-timestamp";
+export declare const SUBJECT_HEADER = "x-kition-subject";
+export declare const DOC_KEY_HEADER = "x-kition-doc-key";
+export declare const VERSION_HEADER = "x-kition-version";
+export declare const NAME_HEADER = "x-kition-name";
+/** How far a callback's timestamp may be from the verifier's clock, seconds. */
+export declare const CALLBACK_SKEW_SECS = 300;
+/** The signature of one callback. */
+export declare function signCallback(secret: string, method: string, path: string, timestamp: number, body?: Uint8Array | null): string;
+/** The headers a callback carries: its signature, timestamp, the person, and the file generation. */
+export declare function callbackHeaders(secret: string, method: string, path: string, body: Uint8Array | null, who: {
+    subject: string;
+    docKey: string;
+}, now?: number): {
+    "x-kition-timestamp": string;
+    "x-kition-signature": string;
+    "x-kition-subject": string;
+    "x-kition-doc-key": string;
+};
+/**
+ * Whether a request the integrator received is the document service's: its signature matches and
+ * its timestamp is within `CALLBACK_SKEW_SECS` of `now`. `headers` are lower-cased names.
+ */
+export declare function verifyCallback(secret: string, request: {
+    method: string;
+    path: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: Uint8Array | null;
+}, now?: number): boolean;

package/dist/callbacks.js

@@ -0,0 +1,37 @@
+import { createHmac as h, createHash as A, timingSafeEqual as d } from "node:crypto";
+const E = "x-kition-signature", f = "x-kition-timestamp", l = "x-kition-subject", g = "x-kition-doc-key", x = "x-kition-version", H = "x-kition-name", b = 300, k = (n) => A("sha256").update(n ?? new Uint8Array()).digest("hex");
+function u(n, t, r, a, e) {
+  return `v1=${h("sha256", n).update(`${t.toUpperCase()}
+${r}
+${a}
+${k(e)}`).digest("hex")}`;
+}
+function S(n, t, r, a, e, o = Math.floor(Date.now() / 1e3)) {
+  return {
+    [f]: String(o),
+    [E]: u(n, t, r, o, a),
+    [l]: e.subject,
+    [g]: e.docKey
+  };
+}
+function D(n, t, r = Math.floor(Date.now() / 1e3)) {
+  const a = (m) => {
+    const i = t.headers[m];
+    return Array.isArray(i) ? i[0] : i;
+  }, e = Number(a(f)), o = a(E);
+  if (!Number.isSafeInteger(e) || Math.abs(r - e) > b || !o) return !1;
+  const s = Buffer.from(u(n, t.method, t.path, e, t.body)), c = Buffer.from(o);
+  return s.length === c.length && d(s, c);
+}
+export {
+  b as CALLBACK_SKEW_SECS,
+  g as DOC_KEY_HEADER,
+  H as NAME_HEADER,
+  E as SIGNATURE_HEADER,
+  l as SUBJECT_HEADER,
+  f as TIMESTAMP_HEADER,
+  x as VERSION_HEADER,
+  S as callbackHeaders,
+  u as signCallback,
+  D as verifyCallback
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { readFile as c } from "node:fs/promises";
+import { resolve as a } from "node:path";
+import { pathToFileURL as l } from "node:url";
+import { startDocService as f } from "./index.js";
+const r = `Usage: kition-doc-service <config.json | config.mjs>
+
+Runs the Kits document service for URL embedding (https://dev.kition.ai/url).
+The config holds startDocService's options: id, secret, integrators, kits,
+kitsUrl (or kitsDir and kitsPort), and optionally port, host, embedDir.`, o = process.argv[2];
+(!o || o === "--help" || o === "-h") && (console.log(r), process.exit(o ? 0 : 1));
+const s = a(o), n = s.endsWith(".json") ? JSON.parse(await c(s, "utf8")) : (await import(l(s).href)).default, t = ["id", "secret", "integrators", "kits"].filter((e) => !n?.[e]);
+t.length && (console.error(`${o} names no ${t.join(", ")}
+
+${r}`), process.exit(1));
+const i = await f(n);
+console.log(`document service:  ${i.url}`);
+console.log(`kit packages:      ${i.kitsUrl}`);
+for (const e of ["SIGINT", "SIGTERM"]) process.once(e, () => void i.close().then(() => process.exit(0)));

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { type DocServiceConfig } from './server.js';
+export { createDocService, type DocServiceConfig, type Integrator, type KitRoute } from './server.js';
+export { callbackHeaders, signCallback, verifyCallback, CALLBACK_SKEW_SECS } from './callbacks.js';
+export { makeSession, readSession, type Session } from './session.js';
+/**
+ * Listens on `port` (0: any free one). With `kitsDir`, also serves the kit packages there on
+ * `kitsPort`, another origin, and `kitsUrl` defaults to it.
+ */
+export declare function startDocService(config: Omit<DocServiceConfig, 'kitsUrl'> & {
+    kitsUrl?: string;
+    port?: number;
+    host?: string;
+    kitsDir?: string;
+    kitsPort?: number;
+}): Promise<{
+    url: string;
+    kitsUrl: string;
+    close: () => Promise<void>;
+}>;

package/dist/index.js

@@ -0,0 +1,272 @@
+import { createServer as H } from "node:http";
+import { readFile as O } from "node:fs/promises";
+import { dirname as W, extname as D, normalize as I, sep as S, join as B } from "node:path";
+import { timingSafeEqual as G, createHmac as K, randomBytes as N } from "node:crypto";
+import { fileURLToPath as J } from "node:url";
+import { decodeOpenToken as M, OpenTokenError as A, verifyOpenToken as V } from "@kition/sync/openToken";
+import { NAME_HEADER as _, VERSION_HEADER as E, callbackHeaders as z } from "./callbacks.js";
+import { CALLBACK_SKEW_SECS as he, signCallback as pe, verifyCallback as ue } from "./callbacks.js";
+const R = (e) => JSON.stringify(e).replace(/</g, "\\u003c"), F = (e) => e.replace(/[&<>"']/g, (n) => `&#${n.charCodeAt(0)};`);
+function X({ session: e, claims: n, kitUrl: c, embedModule: l, nonce: f, title: b }) {
+  const { perms: d } = n, p = {
+    session: e,
+    kit: { id: n.kit, url: c },
+    file: { id: n.file, name: b },
+    user: { id: n.sub, name: n.name || n.sub },
+    mode: d.edit ? "edit" : d.comment ? "comment" : "view",
+    display: { permissions: { download: d.download, export: d.export, share: d.share }, watermark: n.watermark }
+  };
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><meta name="referrer" content="no-referrer"><title>${F(b)}</title>
+<style nonce="${f}">html,body,#editor{margin:0;height:100%;overflow:hidden}</style></head>
+<body><div id="editor"></div>
+<script type="application/json" id="kition-config">${R(p)}<\/script>
+<script type="module" nonce="${f}">
+import { KitionEmbed, EmbedConflictError } from ${R(l)}
+const config = JSON.parse(document.getElementById('kition-config').textContent)
+// The open token stays out of the page's address, history and referrers.
+history.replaceState(null, '', location.pathname)
+const auth = { authorization: 'Bearer ' + config.session }
+async function failed(response) {
+  throw new Error('the document service answered ' + response.status)
+}
+const replica = {
+  read: async () => {
+    const response = await fetch('/v1/replica', { headers: auth })
+    if (response.status === 404 || response.status === 501) return null
+    if (!response.ok) return failed(response)
+    const body = new Uint8Array(await response.arrayBuffer())
+    const length = new DataView(body.buffer, body.byteOffset).getUint32(0)
+    return { snapshot: body.slice(4, 4 + length).buffer, blobs: body.slice(4 + length).buffer, fileStamp: response.headers.get('x-kition-file-stamp') }
+  },
+  write: async (_id, stored) => {
+    const snapshot = new Uint8Array(stored.snapshot), blobs = new Uint8Array(stored.blobs)
+    const body = new Uint8Array(4 + snapshot.length + blobs.length)
+    new DataView(body.buffer).setUint32(0, snapshot.length)
+    body.set(snapshot, 4)
+    body.set(blobs, 4 + snapshot.length)
+    const response = await fetch('/v1/replica', { method: 'PUT', headers: { ...auth, 'x-kition-file-stamp': stored.fileStamp }, body })
+    if (!response.ok && response.status !== 501) return failed(response)
+  },
+}
+const storage = {
+  read: async () => {
+    const response = await fetch('/v1/file', { headers: auth })
+    if (!response.ok) return failed(response)
+    return { bytes: new Uint8Array(await response.arrayBuffer()), version: response.headers.get('x-kition-version') }
+  },
+  stamp: async () => {
+    const response = await fetch('/v1/file/stamp', { headers: auth })
+    if (!response.ok) return failed(response)
+    return (await response.json()).version
+  },
+  write: async (fileId, bytes, { expectedVersion }) => {
+    const response = await fetch('/v1/file', { method: 'PUT', headers: { ...auth, ...(expectedVersion ? { 'if-match': expectedVersion } : {}) }, body: bytes })
+    if (response.status === 409) throw new EmbedConflictError(fileId, response.headers.get('x-kition-version'))
+    if (!response.ok) return failed(response)
+    return await response.json()
+  },
+  replica,
+}
+const editor = await KitionEmbed.mount(document.getElementById('editor'), {
+  kit: config.kit,
+  file: config.file,
+  storage,
+  identity: { user: () => config.user },
+  permissions: { mode: config.mode },
+  display: config.display,
+})
+editor.on('saved', (saved) => parent.postMessage({ kitionDocument: 1, event: 'saved', version: saved.version }, '*'))
+await editor.ready()
+parent.postMessage({ kitionDocument: 1, event: 'ready' }, '*')
+<\/script></body></html>`;
+}
+const T = "kds1.", C = (e) => e.toString("base64url"), L = (e, n) => K("sha256", e).update(`kition-doc-session
+${n}`).digest();
+function Y(e, n) {
+  const c = C(Buffer.from(JSON.stringify(n)));
+  return `${T}${c}.${C(L(e, c))}`;
+}
+function Q(e, n, c = Math.floor(Date.now() / 1e3)) {
+  if (!n?.startsWith(T)) return null;
+  const [l, f, b] = n.slice(T.length).split(".");
+  if (!l || !f || b !== void 0) return null;
+  const d = L(e, l), p = Buffer.from(f, "base64url");
+  if (p.length !== d.length || !G(p, d)) return null;
+  try {
+    const g = JSON.parse(Buffer.from(l, "base64url").toString("utf8"));
+    return typeof g.exp == "number" && c < g.exp ? g : null;
+  } catch {
+    return null;
+  }
+}
+const Z = { ".js": "text/javascript; charset=utf-8", ".mjs": "text/javascript; charset=utf-8", ".map": "application/json", ".css": "text/css", ".wasm": "application/wasm", ".json": "application/json" };
+function q() {
+  try {
+    return W(J(import.meta.resolve("@kition/embed")));
+  } catch {
+    throw new Error("@kition/embed is not installed next to @kition/doc-service: install it, or set embedDir");
+  }
+}
+class a extends Error {
+  constructor(n, c) {
+    super(c), this.status = n;
+  }
+}
+async function ee(e, n) {
+  const c = [];
+  let l = 0;
+  for await (const f of e) {
+    if (l += f.length, l > n) throw new a(413, "too large");
+    c.push(f);
+  }
+  return new Uint8Array(Buffer.concat(c));
+}
+function te(e) {
+  if (e.secret.length < 32) throw new Error("the session secret needs at least 32 characters");
+  const n = new URL(e.kitsUrl).origin, c = e.fetch ?? fetch, l = e.now ?? (() => Math.floor(Date.now() / 1e3)), f = e.maxBytes ?? 256 * 1024 * 1024, b = e.embedDir ?? q(), d = (o) => e.integrators.find((s) => s.iss === o);
+  async function p(o, s, t, i, h = {}) {
+    const m = d(o.iss);
+    if (!m) throw new a(401, "unknown integrator");
+    const r = new URL(`${m.callbackUrl.replace(/\/$/, "")}/files/${encodeURIComponent(o.file)}${t}`), u = z(m.secret, s, r.pathname + r.search, i, { subject: o.sub, docKey: o.docKey }, l());
+    return c(r, { method: s, headers: { ...h, ...u }, ...i ? { body: i } : {} });
+  }
+  async function g(o, s) {
+    if (!o) throw new a(400, "no token");
+    let t;
+    try {
+      const w = d(M(o).iss);
+      if (!w) throw new A("unknown-key");
+      t = await V(o, w.keys, e.id, l());
+    } catch (w) {
+      throw new a(401, w instanceof A ? `open token refused: ${w.code}` : "open token refused");
+    }
+    const i = d(t.iss), h = { iss: t.iss, tenant: t.tenant, sub: t.sub, name: t.name, file: t.file, version: t.version, docKey: t.doc_key, perms: t.perms, watermark: t.watermark, kit: "", exp: 0 }, m = await p(h, "HEAD", "", null);
+    if (m.status === 404) throw new a(404, "no such file");
+    if (!m.ok) throw new a(502, `the integrator answered ${m.status}`);
+    const r = m.headers.get(_) || t.file, u = D(r).toLowerCase(), v = e.kits.find((w) => w.extensions.includes(u));
+    if (!v) throw new a(415, `no kit opens ${u || "this file"}`);
+    const U = { ...h, version: m.headers.get(E) ?? t.version, kit: v.id, exp: l() + (e.sessionTtl ?? 8 * 3600) }, x = N(16).toString("base64"), k = X({ session: Y(e.secret, U), claims: U, kitUrl: new URL(v.path, e.kitsUrl).href, embedModule: "/assets/embed/index.js", nonce: x, title: r });
+    s.writeHead(200, {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store",
+      "referrer-policy": "no-referrer",
+      "x-content-type-options": "nosniff",
+      "content-security-policy": [
+        "default-src 'none'",
+        `script-src 'self' 'nonce-${x}' 'wasm-unsafe-eval'`,
+        `style-src 'nonce-${x}'`,
+        "connect-src 'self'",
+        `frame-src ${n}`,
+        "img-src 'self' data: blob:",
+        "base-uri 'none'",
+        "form-action 'none'",
+        `frame-ancestors ${i.origins.length ? i.origins.join(" ") : "'none'"}`
+      ].join("; ")
+    }), s.end(k);
+  }
+  async function $(o, s, t) {
+    const i = /^Bearer (\S+)$/.exec(o.headers.authorization ?? "")?.[1], h = Q(e.secret, i, l());
+    if (!h) throw new a(401, "no session");
+    const m = h.perms.edit || h.perms.comment;
+    if (o.method === "GET" && t === "/v1/file") {
+      const r = await p(h, "GET", "", null);
+      if (!r.ok) throw new a(r.status === 404 ? 404 : 502, `the integrator answered ${r.status}`);
+      s.writeHead(200, { "content-type": "application/octet-stream", "cache-control": "no-store", [E]: r.headers.get(E) ?? "" }), s.end(Buffer.from(await r.arrayBuffer()));
+      return;
+    }
+    if (o.method === "GET" && t === "/v1/file/stamp") {
+      const r = await p(h, "HEAD", "", null);
+      if (r.status === 404) return j(s, 200, { version: null });
+      if (!r.ok) throw new a(502, `the integrator answered ${r.status}`);
+      return j(s, 200, { version: r.headers.get(E) });
+    }
+    if (o.method === "PUT" && (t === "/v1/file" || t === "/v1/replica")) {
+      if (!m) throw new a(403, "this session is read-only");
+      const r = await ee(o, f), u = t === "/v1/replica", v = {}, U = o.headers["if-match"];
+      !u && typeof U == "string" && (v["if-match"] = U);
+      const x = o.headers["x-kition-file-stamp"];
+      u && typeof x == "string" && (v["x-kition-file-stamp"] = x);
+      const k = await p(h, "PUT", u ? "/replica" : "", r, v);
+      if (k.status === 409) {
+        s.writeHead(409, { [E]: k.headers.get(E) ?? "" }), s.end();
+        return;
+      }
+      if (u && k.status === 501) throw new a(501, "the integrator keeps no replicas");
+      if (!k.ok) throw new a(502, `the integrator answered ${k.status}`);
+      const w = u ? {} : await k.json().catch(() => ({}));
+      if (!u && typeof w.version != "string") throw new a(502, "the integrator answered no version");
+      return j(s, 200, u ? {} : { version: w.version });
+    }
+    if (o.method === "GET" && t === "/v1/replica") {
+      const r = await p(h, "GET", "/replica", null);
+      if (r.status === 404 || r.status === 501) throw new a(r.status, "no replica");
+      if (!r.ok) throw new a(502, `the integrator answered ${r.status}`);
+      s.writeHead(200, { "content-type": "application/octet-stream", "cache-control": "no-store", "x-kition-file-stamp": r.headers.get("x-kition-file-stamp") ?? "" }), s.end(Buffer.from(await r.arrayBuffer()));
+      return;
+    }
+    throw new a(404, "not found");
+  }
+  async function y(o, s) {
+    const t = I(decodeURIComponent(o.slice(14)));
+    if (t.startsWith("..") || t.includes(`${S}..`) || t.startsWith(S)) throw new a(404, "not found");
+    const i = await O(B(b, t)).catch(() => null);
+    if (!i) throw new a(404, "not found");
+    s.writeHead(200, { "content-type": Z[D(t)] ?? "application/octet-stream", "x-content-type-options": "nosniff", "cache-control": "public, max-age=300" }), s.end(i);
+  }
+  return async function(s, t) {
+    try {
+      const i = new URL(s.url ?? "/", "http://service");
+      if (s.method === "GET" && i.pathname === "/v1/open") return await g(i.searchParams.get("token"), t);
+      if (i.pathname.startsWith("/v1/")) return await $(s, t, i.pathname);
+      if (s.method === "GET" && i.pathname.startsWith("/assets/embed/")) return await y(i.pathname, t);
+      throw new a(404, "not found");
+    } catch (i) {
+      const h = i instanceof a ? i.status : 500;
+      i instanceof a || console.error("[kition-doc-service]", i), t.headersSent ? t.end() : j(t, h, { error: i instanceof a ? i.message : "failed" });
+    }
+  };
+}
+function j(e, n, c) {
+  e.writeHead(n, { "content-type": "application/json", "cache-control": "no-store" }), e.end(JSON.stringify(c));
+}
+const P = (e, n, c) => new Promise((l, f) => {
+  e.once("error", f), e.listen(n, c, () => l(e.address().port));
+});
+async function le(e) {
+  const n = e.host ?? "127.0.0.1";
+  let c = null, l = e.kitsUrl;
+  if (e.kitsDir) {
+    const d = e.kitsDir;
+    c = H(async (g, $) => {
+      const y = I(decodeURIComponent(new URL(g.url ?? "/", "http://kits").pathname)).replace(/^[/\\]+/, ""), o = y.startsWith("..") || y.includes(`${S}..`) ? null : await O(B(d, y.endsWith(S) || !y ? B(y, "index.html") : y)).catch(() => null);
+      if (!o) {
+        $.writeHead(404).end();
+        return;
+      }
+      const s = { ".html": "text/html; charset=utf-8", ".js": "text/javascript", ".mjs": "text/javascript", ".css": "text/css", ".wasm": "application/wasm", ".json": "application/json" }[D(y) || ".html"];
+      $.writeHead(200, { "content-type": s ?? "application/octet-stream", "x-content-type-options": "nosniff" }), $.end(o);
+    });
+    const p = await P(c, e.kitsPort ?? 0, n);
+    l ??= `http://${n}:${p}/`;
+  }
+  if (!l) throw new Error("kitsUrl or kitsDir is needed");
+  const f = H(te({ ...e, kitsUrl: l })), b = await P(f, e.port ?? 0, n);
+  return {
+    url: `http://${n}:${b}`,
+    kitsUrl: l,
+    close: async () => {
+      await new Promise((d) => f.close(d)), c && await new Promise((d) => c.close(d));
+    }
+  };
+}
+export {
+  he as CALLBACK_SKEW_SECS,
+  z as callbackHeaders,
+  te as createDocService,
+  Y as makeSession,
+  Q as readSession,
+  pe as signCallback,
+  le as startDocService,
+  ue as verifyCallback
+};

package/dist/page.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The editor page the service answers `GET /v1/open` with: `@kition/embed` mounting the kit for the
+ * session's file, its storage provider the service's own `/v1/file` and `/v1/replica`, with the
+ * session as the bearer. Nothing in it is trusted by the service: every call is checked again.
+ */
+import type { Session } from './session.js';
+export type PageOptions = {
+    session: string;
+    claims: Session;
+    kitUrl: string;
+    embedModule: string;
+    nonce: string;
+    title: string;
+};
+export declare function editorPage({ session, claims, kitUrl, embedModule, nonce, title }: PageOptions): string;

package/dist/server.d.ts

@@ -0,0 +1,39 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type OpenTokenKey } from '@kition/sync/openToken';
+export type Integrator = {
+    /** The issuer its open tokens name (`iss`). */
+    iss: string;
+    /** Its keys: each bound to its tenant and to `iss`. */
+    keys: OpenTokenKey[];
+    /** Where its callbacks are (`{callbackUrl}/files/{file}`). */
+    callbackUrl: string;
+    /** The secret callbacks are signed with (shared with the integrator). */
+    secret: string;
+    /** Origins allowed to frame the editor (`frame-ancestors`). */
+    origins: string[];
+};
+export type KitRoute = {
+    id: string;
+    path: string;
+    extensions: string[];
+};
+export type DocServiceConfig = {
+    /** The service's id: the `aud` its open tokens name. */
+    id: string;
+    /** Signs sessions; at least 32 characters, never shared. */
+    secret: string;
+    integrators: Integrator[];
+    /** Which kit opens which files, by name extension; `path` is the kit package under `kitsUrl`. */
+    kits: KitRoute[];
+    /** Where kit packages are served: another origin than the service's (EM4). */
+    kitsUrl: string;
+    /** `@kition/embed`'s built module directory (its `dist`); default: the installed `@kition/embed`'s. */
+    embedDir?: string;
+    /** A session's life, seconds (default 8 hours). */
+    sessionTtl?: number;
+    /** The largest document or replica a page may write, bytes (default 256 MiB). */
+    maxBytes?: number;
+    fetch?: typeof fetch;
+    now?: () => number;
+};
+export declare function createDocService(config: DocServiceConfig): (request: IncomingMessage, response: ServerResponse) => Promise<void>;

package/dist/session.d.ts

@@ -0,0 +1,22 @@
+import type { OpenPerms } from '@kition/sync/openToken';
+export type Session = {
+    /** The integrator (`iss`) and its tenant. */
+    iss: string;
+    tenant: string;
+    sub: string;
+    name: string;
+    file: string;
+    version: string;
+    docKey: string;
+    perms: OpenPerms;
+    watermark: {
+        text: string;
+    } | null;
+    /** The kit the page opens. */
+    kit: string;
+    /** Unix seconds. */
+    exp: number;
+};
+export declare function makeSession(secret: string, session: Session): string;
+/** The session `token` names, or `null` when it is not one of ours, was changed, or expired. */
+export declare function readSession(secret: string, token: string | null | undefined, now?: number): Session | null;

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@kition/doc-service",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The Kits document service: serves single-user kit editor pages for iframe URLs carrying a signed open token, reading and writing through the integrator's HMAC-signed HTTP callbacks (URL embedding, L8).",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./callbacks": {
+      "types": "./dist/callbacks.d.ts",
+      "import": "./dist/callbacks.js"
+    }
+  },
+  "bin": {
+    "kition-doc-service": "./dist/cli.js"
+  },
+  "engines": {
+    "node": ">=20.6"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@kition/sync": "0.1.0",
+    "@kition/embed": "0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KitionAI/kition-sdk.git",
+    "directory": "packages/doc-service"
+  },
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "node ../../tools/build-package.mjs"
+  }
 }