@corbet-labs/cink 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# @corbet-labs/cink
+
+Handwritten signature image rendering for formal correspondence. Pure port
+of the [cink](https://github.com/corbet-labs/cink) Rust crate: zero
+dependencies, zero Node APIs, synchronous, no I/O. Pixels, not
+signatures — no cryptography, no identity, no legal ceremony.
+
+```ts
+import { normalize, signatureSize, imageSnippet } from '@corbet-labs/cink';
+
+const img = normalize(dataUrl); // null when unusable
+const [w, h] = signatureSize(img, 31.5, 120);
+const snippet = imageSnippet('/signature.png', h, w === 31.5 ? undefined : w);
+```
+
+PNG and JPEG dimensions are read from headers, never decoded; SVG passes
+through dimension-less. WebP, GIF, corrupt, and empty inputs are rejected.
+Oversized rasters are reported (`exceedsLimits`, `scaleToFit`), never
+silently resampled.
+
+Run `bun ./scripts/conformance.mts` and `tsc --noEmit -p ./tsconfig.json`
+before pushing.
+
+## License
+
+FSL-1.1-ALv2. Each published version becomes available under Apache-2.0
+two years after publication.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@corbet-labs/cink",
+  "version": "0.1.0",
+  "description": "Handwritten signature image rendering for correspondence. Pixels, not signatures. Mirrors the cink Rust crate release line.",
+  "license": "FSL-1.1-ALv2",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/corbet-labs/cink.git",
+    "directory": "js/@corbet-labs/cink"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/**/*",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "bash ./scripts/sync-assets.sh",
+    "conformance": "bun ./scripts/conformance.mts",
+    "typecheck": "tsc --noEmit -p ./tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "25.8.0",
+    "typescript": "6.0.3"
+  }
+}

package/src/generated/tables.ts

@@ -0,0 +1,3 @@
+// GENERATED by scripts/sync-assets.sh — do not edit.
+export const PACKAGE_VERSION = "0.1.0";
+export const DEFAULTS = {"max_pixels": 1600, "formats": ["png", "jpeg", "svg"]};

package/src/index.ts

@@ -0,0 +1,177 @@
+/**
+ * Handwritten signature image rendering for formal correspondence.
+ *
+ * Pure TypeScript port of the cink Rust crate: zero dependencies, zero
+ * Node APIs (base64 via global atob), synchronous, no I/O. Pixels, not
+ * signatures — no cryptography, no identity, no legal ceremony.
+ *
+ * Behavior is defined by `tables/defaults.json` plus the byte-level rules
+ * in `tables/README.md`; `tests/vectors/*.json` with fixtures in
+ * `tests/fixtures/` is the shared conformance suite.
+ */
+import { DEFAULTS } from './generated/tables.js';
+
+export interface Defaults {
+    max_pixels: number;
+    formats: string[];
+}
+
+const defaults = DEFAULTS as Defaults;
+
+export type ImageMime = 'png' | 'jpeg' | 'svg';
+
+export interface DecodedImage {
+    mime: ImageMime;
+    width: number | null;
+    height: number | null;
+    bytes: Uint8Array;
+}
+
+/** Default oversize threshold in pixels, from `tables/defaults.json`. */
+export function defaultMaxPixels(): number {
+    return defaults.max_pixels;
+}
+
+const PNG_MAGIC = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+function pngDimensions(bytes: Uint8Array): [number, number] | null {
+    if (bytes.length < 24) return null;
+    for (let i = 0; i < 8; i++) if (bytes[i] !== PNG_MAGIC[i]) return null;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint32(8) !== 13) return null;
+    if (view.getUint32(12) !== 0x49484452) return null;
+    const width = view.getUint32(16);
+    const height = view.getUint32(20);
+    if (width === 0 || height === 0) return null;
+    return [width, height];
+}
+
+const SOF_MARKERS = new Set([
+    0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
+]);
+
+function jpegDimensions(bytes: Uint8Array): [number, number] | null {
+    if (bytes.length < 2 || bytes[0] !== 0xff || bytes[1] !== 0xd8) return null;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let pos = 2;
+    while (pos < bytes.length) {
+        while (pos < bytes.length && bytes[pos] === 0xff) pos++;
+        if (pos >= bytes.length) return null;
+        const marker = bytes[pos];
+        pos++;
+        if (SOF_MARKERS.has(marker)) {
+            if (pos + 7 > bytes.length) return null;
+            const height = view.getUint16(pos + 3);
+            const width = view.getUint16(pos + 5);
+            if (width === 0 || height === 0) return null;
+            return [width, height];
+        }
+        if (marker === 0xd9 || marker === 0xda) return null;
+        if (marker === 0x00 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) continue;
+        if (pos + 2 > bytes.length) return null;
+        const len = view.getUint16(pos);
+        if (len < 2) return null;
+        pos += len;
+    }
+    return null;
+}
+
+function sniff(bytes: Uint8Array): DecodedImage | null {
+    if (bytes.length >= 8 && PNG_MAGIC.every((b, i) => bytes[i] === b)) {
+        const dims = pngDimensions(bytes);
+        if (dims === null) return null;
+        return { mime: 'png', width: dims[0], height: dims[1], bytes };
+    }
+    if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xd8) {
+        const dims = jpegDimensions(bytes);
+        if (dims === null) return null;
+        return { mime: 'jpeg', width: dims[0], height: dims[1], bytes };
+    }
+    let start = 0;
+    while (start < bytes.length && /\s/.test(String.fromCharCode(bytes[start]))) start++;
+    const head = String.fromCharCode(...bytes.slice(start, start + 4));
+    if (head === '<svg') return { mime: 'svg', width: null, height: null, bytes };
+    return null;
+}
+
+function decodeBase64(payload: string): Uint8Array | null {
+    if (payload === '') return null;
+    try {
+        const text = atob(payload);
+        const bytes = new Uint8Array(text.length);
+        for (let i = 0; i < text.length; i++) bytes[i] = text.charCodeAt(i);
+        return bytes.length > 0 ? bytes : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Validate a signature image given as a `data:` URL or raw base64.
+ * Returns `null` for empty, undecodable, corrupt, or unsupported inputs.
+ */
+export function normalize(input: string): DecodedImage | null {
+    let payload = input;
+    const comma = input.indexOf(',');
+    if (comma >= 0 && input.startsWith('data:')) {
+        const meta = input.slice(0, comma);
+        if (!meta.includes(';base64')) return null;
+        payload = input.slice(comma + 1);
+    }
+    const bytes = decodeBase64(payload);
+    if (bytes === null) return null;
+    return sniff(bytes);
+}
+
+/**
+ * Whether the raster exceeds a pixel budget. Dimension-less formats (SVG)
+ * scale without loss and never exceed.
+ */
+export function exceedsLimits(image: DecodedImage, maxPixels: number): boolean {
+    if (image.width === null || image.height === null) return false;
+    return image.width * image.height > maxPixels;
+}
+
+/**
+ * Linear scale factor that fits the image into a pixel budget, never
+ * above 1.0 (never upscales). The caller resamples and re-submits.
+ */
+export function scaleToFit(image: DecodedImage, maxPixels: number): number {
+    if (image.width === null || image.height === null) return 1.0;
+    const pixels = image.width * image.height;
+    if (pixels <= maxPixels) return 1.0;
+    return Math.sqrt(maxPixels / pixels);
+}
+
+/**
+ * Point size for a target height, preserving aspect ratio, clamped to an
+ * optional maximum width. Returns `null` when the image carries no
+ * dimensions: the caller must size it.
+ */
+export function signatureSize(
+    image: DecodedImage,
+    heightPt: number,
+    maxWidthPt?: number,
+): [number, number] | null {
+    if (image.width === null || image.height === null) return null;
+    const natural = (heightPt * image.width) / image.height;
+    if (maxWidthPt !== undefined && natural > maxWidthPt) {
+        const scale = maxWidthPt / natural;
+        return [maxWidthPt, heightPt * scale];
+    }
+    return [natural, heightPt];
+}
+
+function escapePath(path: string): string {
+    return path.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/**
+ * Typst `#image` call for a sized signature. Width is emitted only when a
+ * max-width clamp applied; layout and placement stay with the caller.
+ */
+export function imageSnippet(path: string, heightPt: number, widthPt?: number): string {
+    const safe = escapePath(path);
+    if (widthPt === undefined) return `#image("${safe}", height: ${heightPt}pt)`;
+    return `#image("${safe}", height: ${heightPt}pt, width: ${widthPt}pt)`;
+}