@zumer/snapdom-plugins 3.0.0-beta.0 → 4.0.0

package/vector/src/public.js

@@ -0,0 +1,57 @@
+/**
+ * The public face of SnapDOM Vector: the plugin a customer registers, with two
+ * exports and one option.
+ *
+ *   const shot = await snapdom(el, { plugins: [vector()] })
+ *   const svg = await shot.toVector()   // standalone SVG, universal target
+ *   await shot.toFigma()                // Figma's paste format, on the clipboard
+ *
+ * The engine in index.js keeps its whole surface (the SVD document, the SVG, Figma
+ * and PDF emitters, every tuning option) because the test suites and demos drive
+ * it. The customer bundle is built from THIS file, so none of that is part of the
+ * product: `exclude` is the only option that reaches the engine, and the engine's
+ * defaults decide everything else. `test/verify-plugin.mjs` pins both exports.
+ */
+import { vector as engine } from './index.js'
+
+/** Only `exclude` crosses into the engine; anything else a caller passes is dropped. */
+const publicOptions = (options) => (options && options.exclude !== undefined ? { exclude: options.exclude } : {})
+
+/**
+ * Create the plugin. A capture it runs on gains `toVector()` and `toFigma()`.
+ *
+ * @param {{exclude?: string|Function|Array<string|Function>}} [options]  factory
+ *   default for every export; the same option on a call wins for that call.
+ * @returns {object} snapdom plugin
+ */
+export function vector (options = {}) {
+  const inner = engine(publicOptions(options))
+  return {
+    name: inner.name,
+    beforeRender: inner.beforeRender,
+    defineExports (captureCtx) {
+      const exports = inner.defineExports(captureCtx)
+      return {
+        vector: (ctx, opts) => exports.vectorSvg(ctx, publicOptions(opts)),
+        figma: (ctx, opts) => {
+          if (typeof navigator === 'undefined' || !navigator.clipboard?.write || typeof ClipboardItem === 'undefined') {
+            return Promise.reject(new Error('[snapdom-vector] toFigma() needs the async clipboard API: ' +
+              'call it from a page served over https or localhost'))
+          }
+          // The write starts before the export finishes and is handed promises, so a
+          // browser that ties clipboard access to the user's click still sees one.
+          const envelope = exports.vectorFigmaClipboard(ctx, publicOptions(opts))
+          const part = (key, type) => envelope.then(result => new Blob([result[key]], { type }))
+          const written = navigator.clipboard.write([new ClipboardItem({
+            'text/html': part('html', 'text/html'),
+            'text/plain': part('plain', 'text/plain'),
+          })])
+          // The export's own error wins over the clipboard's generic one.
+          return Promise.all([envelope, written]).then(() => undefined)
+        },
+      }
+    },
+  }
+}
+
+export default vector

package/vector/src/writer/encrypt.js

@@ -0,0 +1,227 @@
+/**
+ * Standard security handler, revision 6: AES-256, and nothing older.
+ *
+ * A PDF that leaves the browser as a download IS the delivery channel, so the
+ * only encryption worth writing here is the kind that protects the file at rest
+ * once it has been shared. That rules two things out, in opposite directions:
+ *
+ *  - **RC4 and the /V 1–4 revisions are not offered.** A 40-bit key is brute
+ *    forced in seconds and 128-bit RC4 is not far behind; both also need MD5,
+ *    which the platform deliberately does not provide. Writing them by hand to
+ *    ship a weaker product is not a trade this file makes.
+ *  - **Permission flags are not protection and are not sold as such.** `/P` is
+ *    a request a viewer may honour; any tool can ignore it. What actually keeps
+ *    a document shut is the user password, because without it the bytes cannot
+ *    be read at all. The flags are written because the format has them, and the
+ *    caller is told what they are worth.
+ *
+ * Everything here comes from `crypto.subtle`: SHA-256/384/512 for Algorithm 2.B
+ * and AES-CBC for the rest. No dependency, no hand-rolled cipher, no MD5.
+ *
+ * **One thing WebCrypto will not do**, and the workaround, because it looks like
+ * a bug otherwise: 2.B and the key wrapping need AES-CBC with NO padding, and
+ * WebCrypto always appends a PKCS#7 block. The bytes it produces before that
+ * block ARE the unpadded CBC stream — CBC is sequential, so block n cannot
+ * depend on anything after it — so every no-padding call here encrypts and then
+ * truncates. `_encryptcheck.mjs` asserts that prefix property rather than
+ * trusting it.
+ *
+ * **Determinism survives.** The salts and the file encryption key are derived,
+ * not randomised: the key is HKDF-SHA256 over the password with the document's
+ * own plaintext digest as salt, and the salts are further derivations of that
+ * digest. The same document encrypted with the same password is byte-identical,
+ * which is the promise the rest of this writer makes and this file is not
+ * allowed to break. Nothing is weakened by it — a salt travels in the file in
+ * the clear anyway, it differs per document because the digest does, and the key
+ * is still unreachable without the password.
+ */
+
+const utf8 = (s) => new TextEncoder().encode(s)
+
+/** Concatenate byte runs. */
+function cat(...runs) {
+  let n = 0
+  for (const r of runs) n += r.length
+  const out = new Uint8Array(n)
+  let at = 0
+  for (const r of runs) { out.set(r, at); at += r.length }
+  return out
+}
+
+const hex = (b) => [...b].map(x => x.toString(16).padStart(2, '0')).join('').toUpperCase()
+
+async function sha(bits, data) {
+  return new Uint8Array(await crypto.subtle.digest(`SHA-${bits}`, data))
+}
+
+/**
+ * AES-CBC with no padding, by encrypting and dropping the block WebCrypto adds.
+ * `data.length` must be a multiple of 16, which every caller here guarantees.
+ */
+async function aesNoPad(key, iv, data) {
+  const k = await crypto.subtle.importKey('raw', key, 'AES-CBC', false, ['encrypt'])
+  const full = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-CBC', iv }, k, data))
+  return full.subarray(0, data.length)
+}
+
+/** AES-CBC with the PKCS#7 padding the PDF stream/string format wants, IV first. */
+async function aesCbc(key, iv, data) {
+  const k = await crypto.subtle.importKey('raw', key, 'AES-CBC', false, ['encrypt'])
+  return cat(iv, new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-CBC', iv }, k, data)))
+}
+
+/**
+ * ISO 32000-2, Algorithm 2.B — the hardened password hash revision 6 uses.
+ *
+ * The loop is the point of it: at least 64 rounds, each one AES over 64 copies
+ * of (password ‖ K ‖ udata) and then one of three SHA-2 variants chosen by the
+ * data itself, and it only stops once the last byte of a round's output falls
+ * below round − 32. That makes a guess cost work no table can amortise.
+ *
+ * @param {Uint8Array} password  UTF-8, already truncated to 127 bytes
+ * @param {Uint8Array} salt      8 bytes
+ * @param {Uint8Array} udata     the 48-byte /U for an owner hash; empty for a user one
+ */
+async function hash2B(password, salt, udata) {
+  let k = await sha(256, cat(password, salt, udata))
+  for (let round = 0; ; round++) {
+    const block = cat(password, k, udata)
+    const k1 = new Uint8Array(block.length * 64)
+    for (let i = 0; i < 64; i++) k1.set(block, i * block.length)
+    const e = await aesNoPad(k.subarray(0, 16), k.subarray(16, 32), k1)
+    let mod = 0
+    for (let i = 0; i < 16; i++) mod += e[i]
+    k = await sha([256, 384, 512][mod % 3], e)
+    if (round >= 63 && e[e.length - 1] <= round - 31) break
+  }
+  return k.subarray(0, 32)
+}
+
+/** A PDF password: UTF-8, capped at 127 bytes, cut on a code point boundary. */
+function passwordBytes(text) {
+  const raw = utf8(String(text ?? ''))
+  if (raw.length <= 127) return raw
+  let end = 127
+  while (end > 0 && (raw[end] & 0xc0) === 0x80) end--
+  return raw.subarray(0, end)
+}
+
+/**
+ * The permission bits of `/P`. Bits 1–2 and 7–8 are reserved and always 1; every
+ * bit this does not turn off stays on, so the default grants everything.
+ *
+ * Bit 10 — extraction for accessibility — is NOT exposed. It is deprecated in
+ * PDF 2.0 (a conforming reader must always allow it) and PDF/UA requires an
+ * encrypted file to keep permitting it, so an exporter whose entire selling
+ * point is an extractable text layer has no business offering to switch it off.
+ */
+const PERMISSION_BITS = {
+  print: 3, modify: 4, copy: 5, annotate: 6,
+  fillForms: 9, assemble: 11, printHighRes: 12,
+}
+
+function permissionValue(permissions, warn) {
+  let p = -1 // every bit set
+  // Bits 1, 2, 7, 8 are reserved and must be 1; -1 already has them.
+  for (const [name, value] of Object.entries(permissions || {})) {
+    const bit = PERMISSION_BITS[name]
+    if (bit === undefined) {
+      warn(`encrypt.permissions.${name} is not a permission — ignored. Known: ` +
+        `${Object.keys(PERMISSION_BITS).join(', ')}.`)
+      continue
+    }
+    if (value === false) p &= ~(1 << (bit - 1))
+  }
+  return p | 0
+}
+
+/**
+ * Everything a document needs to be encrypted: the file key, and the /Encrypt
+ * dictionary that lets a reader recover it from a password.
+ *
+ * @param {object} args
+ * @param {string} args.userPassword     opens the document; '' means "opens without one"
+ * @param {string} [args.ownerPassword]  lifts the permission flags; defaults to the user one
+ * @param {object} [args.permissions]    `{print:false, copy:false, …}`
+ * @param {Uint8Array} args.seed         a digest of the document's PLAINTEXT bytes
+ * @param {(msg:string)=>void} args.warn
+ */
+export async function buildEncryption({ userPassword, ownerPassword, permissions, seed, warn }) {
+  const user = passwordBytes(userPassword)
+  // An owner password equal to the user one is the common case and is fine; what
+  // is NOT fine is an owner password alone, because then anyone opens the file
+  // and only the advisory flags stand between them and everything.
+  const owner = passwordBytes(ownerPassword ?? userPassword)
+  const p = permissionValue(permissions, warn)
+
+  // Derived, never random — see the file comment. Distinct info strings keep the
+  // four derivations from ever colliding.
+  const derive = async (info, bytes) => {
+    const ikm = await crypto.subtle.importKey('raw', cat(user, owner), 'HKDF', false, ['deriveBits'])
+    const bits = await crypto.subtle.deriveBits(
+      { name: 'HKDF', hash: 'SHA-256', salt: seed, info: utf8(`snapdom/pdf-writer/${info}`) },
+      ikm, bytes * 8
+    )
+    return new Uint8Array(bits)
+  }
+  const fileKey = await derive('filekey/v1', 32)
+  const uValidation = await derive('u-validation/v1', 8)
+  const uKeySalt = await derive('u-keysalt/v1', 8)
+  const oValidation = await derive('o-validation/v1', 8)
+  const oKeySalt = await derive('o-keysalt/v1', 8)
+
+  // Algorithm 8: /U proves a user password, /UE hands over the file key.
+  const uHash = await hash2B(user, uValidation, new Uint8Array(0))
+  const U = cat(uHash, uValidation, uKeySalt)
+  const UE = await aesNoPad(await hash2B(user, uKeySalt, new Uint8Array(0)), new Uint8Array(16), fileKey)
+
+  // Algorithm 9: the owner hashes are bound to /U, so /O cannot be lifted onto
+  // another document.
+  const oHash = await hash2B(owner, oValidation, U)
+  const O = cat(oHash, oValidation, oKeySalt)
+  const OE = await aesNoPad(await hash2B(owner, oKeySalt, U), new Uint8Array(16), fileKey)
+
+  // Algorithm 10: /Perms is the permission set encrypted under the file key, so
+  // a reader that HAS the key can tell whether the flags were tampered with.
+  // Bytes 12–15 are unused by the spec; zeros keep the file deterministic.
+  const perms = new Uint8Array(16)
+  new DataView(perms.buffer).setInt32(0, p, true)
+  perms.set([0xff, 0xff, 0xff, 0xff], 4)
+  perms[8] = 0x54 // 'T': the metadata stream is encrypted too
+  perms.set([0x61, 0x64, 0x62], 9) // 'adb'
+  const Perms = await aesNoPad(fileKey, new Uint8Array(16), perms)
+
+  const dict =
+    '/Filter /Standard /V 5 /R 6 /Length 256 ' +
+    '/CF << /StdCF << /CFM /AESV3 /AuthEvent /DocOpen /Length 32 >> >> ' +
+    '/StmF /StdCF /StrF /StdCF ' +
+    `/O <${hex(O)}> /U <${hex(U)}> /OE <${hex(OE)}> /UE <${hex(UE)}> ` +
+    `/Perms <${hex(Perms)}> /P ${p} /EncryptMetadata true`
+
+  return {
+    dict,
+    p,
+    /**
+     * Encrypt one stream payload or one string. Revision 6 uses the file key
+     * directly — the per-object key derivation of revisions 2–4 is gone — so an
+     * object number is not needed and cannot be got wrong.
+     *
+     * The IV is derived from the file key and the object it protects rather than
+     * drawn at random, for the same determinism reason as everything else, and
+     * it is distinct per object and per occurrence, which is what CBC requires.
+     */
+    async encrypt(bytes, nonce) {
+      const iv = (await sha(256, cat(fileKey, utf8(`iv/${nonce}`)))).subarray(0, 16)
+      return aesCbc(fileKey, iv, bytes)
+    },
+  }
+}
+
+/**
+ * The catalog entry that tells an ISO 32000-1 reader this file uses a feature
+ * from the next edition. `%PDF-1.7` stays in the header — the file structure IS
+ * 1.7 — and AES-256 arrived as Adobe extension level 3 before ISO 32000-2
+ * standardised it, which is the shape every reader in the field learned.
+ */
+export const AES256_EXTENSION =
+  '/Extensions << /ADBE << /BaseVersion /1.7 /ExtensionLevel 3 >> >>'