@prosopo/puzzle-assets 0.1.3 → 0.1.4

package/src/decoys.ts

@@ -0,0 +1,191 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { createNotchShape } from "./notch.js";
+import { coverageFromDistance } from "./notch.js";
+import type { Prng } from "./prng.js";
+import type { NotchPlacement, RgbaImage } from "./types.js";
+
+/**
+ * Decoys are rendered as shallow indented jigsaw silhouettes: a darker
+ * edge with a barely-lifted interior. Edge shading direction (darker at
+ * the rim) mirrors the real cutout's inner shadow, so at a glance decoys
+ * read as similar shapes and it's not immediately obvious which one is
+ * the real target. Edge/body amplitudes come from PuzzleRenderSettings
+ * so operators can tune the confusion level per-client from the portal.
+ *
+ * No drop shadow — a shadow ring picked up WebP artefacts and read as a
+ * visible halo around each decoy.
+ */
+
+/**
+ * Minimum centre-to-centre distance from the real notch, in notch-sizes.
+ * Zero: decoys may sit right up to (and over) the target region. The cut
+ * itself runs after decoy paint, so the darkened hole still wins visually.
+ */
+const NOTCH_CLEARANCE = 0;
+
+/** Placement retries per decoy before giving up on that slot. */
+const PLACEMENT_ATTEMPTS = 8;
+
+const clamp255 = (v: number): number => (v < 0 ? 0 : v > 255 ? 255 : v);
+
+const distanceSquared = (
+	cx: number,
+	cy: number,
+	other: { cx: number; cy: number },
+): number => {
+	const dx = cx - other.cx;
+	const dy = cy - other.cy;
+	return dx * dx + dy * dy;
+};
+
+/**
+ * Depth cue on decoys, mirroring `HOLE_INNER_SHADOW` in `compose.ts`.
+ * Smaller so decoys read as shallower cuts than the real hole.
+ */
+const DECOY_INNER_SHADOW = 0.35;
+
+/**
+ * Composite a jigsaw-shaped decoration onto `background`, centred on
+ * `(cx, cy)`. Mutates `background`. Runs the same signed-distance sampling
+ * as the real cut, so the silhouette reads as the same family of shapes.
+ */
+export const paintDecoyPiece = (
+	background: RgbaImage,
+	prng: Prng,
+	size: number,
+	cx: number,
+	cy: number,
+	edgeDarkness: number,
+	bodyBrightness: number,
+	holeDarken: number,
+): void => {
+	const shape = createNotchShape(prng, size);
+	const half = size / 2;
+	const left = Math.round(cx - half);
+	const top = Math.round(cy - half);
+
+	// Body only. No drop shadow — the shadow ring read as a halo around each
+	// decoy and picked up WebP artefacts on the background.
+	for (let ly = 0; ly < size; ly++) {
+		for (let lx = 0; lx < size; lx++) {
+			const x = left + lx;
+			const y = top + ly;
+			if (x < 0 || y < 0 || x >= background.width || y >= background.height) {
+				continue;
+			}
+			const d = shape.distance(lx, ly);
+			const coverage = coverageFromDistance(d);
+			if (coverage <= 0) continue;
+
+			const bi = (y * background.width + x) * 4;
+			const r = background.data[bi] ?? 0;
+			const g = background.data[bi + 1] ?? 0;
+			const b = background.data[bi + 2] ?? 0;
+
+			// Multiplicative darken with an inner shadow, matching the real
+			// cut's structure. Without this, decoys were just faint edge
+			// tints and the real hole stood out as the only deep region on
+			// the frame — trivially findable by eye or by luminance.
+			const edge = d > -3 ? DECOY_INNER_SHADOW * (1 + d / 3) : 0;
+			const factor = holeDarken * (1 - edge);
+			const dr = r * factor;
+			const dg = g * factor;
+			const db = b * factor;
+
+			// Existing additive tweak stays on top, so operators keep the
+			// same rim / body knobs — they now fine-tune the multiplicative
+			// base rather than being the sole depth cue.
+			const edgeDark = d > -3 ? edgeDarkness * (1 + d / 3) : 0;
+			const delta = bodyBrightness - edgeDark;
+
+			const mixR = r * (1 - coverage) + dr * coverage;
+			const mixG = g * (1 - coverage) + dg * coverage;
+			const mixB = b * (1 - coverage) + db * coverage;
+
+			background.data[bi] = clamp255(Math.round(mixR + delta * coverage));
+			background.data[bi + 1] = clamp255(Math.round(mixG + delta * coverage));
+			background.data[bi + 2] = clamp255(Math.round(mixB + delta * coverage));
+		}
+	}
+};
+
+/**
+ * Fractional jitter around the configured decoy count. ±30% means a
+ * configured 5 draws anywhere in [4, 6]; a configured 100 draws in [70,
+ * 130]. Randomising the count prevents a solver from keying on "exactly N
+ * jigsaw regions on the board" as a stable feature.
+ */
+const COUNT_JITTER = 0.3;
+
+/**
+ * Paint decoys onto `background`. The actual number placed varies per-
+ * challenge within ±COUNT_JITTER of `targetCount`, so a solver can't
+ * hard-code the expected count. Decoys avoid only the real notch
+ * placement (they may freely overlap each other). If a slot cannot be
+ * placed after `PLACEMENT_ATTEMPTS`, it is silently dropped — decoys are
+ * cosmetic, so an occasional miss is fine.
+ */
+export const paintDecoys = (
+	background: RgbaImage,
+	prng: Prng,
+	targetCount: number,
+	notchSize: number,
+	notch: NotchPlacement,
+	edgeDarkness: number,
+	bodyBrightness: number,
+	holeDarken: number,
+): void => {
+	if (targetCount <= 0) return;
+
+	// Draw an actual count near the target. Round to int, clamp to >=0.
+	const jitter = 1 + prng.range(-COUNT_JITTER, COUNT_JITTER);
+	const count = Math.max(0, Math.round(targetCount * jitter));
+	if (count === 0) return;
+
+	const notchClearanceSq = (notchSize * NOTCH_CLEARANCE) ** 2;
+	// Centre may sit anywhere on the frame; a decoy that overhangs the edge
+	// is clipped by `paintDecoyPiece`, matching the real piece's overhang
+	// behaviour. Without this, large pieces would render zero decoys because
+	// `notchSize/2` exceeds the frame dimensions.
+	const minX = 0;
+	const maxX = background.width;
+	const minY = 0;
+	const maxY = background.height;
+
+	for (let i = 0; i < count; i++) {
+		for (let attempt = 0; attempt < PLACEMENT_ATTEMPTS; attempt++) {
+			const cx = prng.range(minX, maxX);
+			const cy = prng.range(minY, maxY);
+			if (
+				distanceSquared(cx, cy, { cx: notch.targetX, cy: notch.targetY }) <
+				notchClearanceSq
+			) {
+				continue;
+			}
+			paintDecoyPiece(
+				background,
+				prng,
+				notchSize,
+				cx,
+				cy,
+				edgeDarkness,
+				bodyBrightness,
+				holeDarken,
+			);
+			break;
+		}
+	}
+};

package/src/encode.ts

@@ -0,0 +1,59 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import sharp from "sharp";
+import type { RgbaImage } from "./types.js";
+
+/**
+ * Background quality is deliberately high. WebP's chroma subsampling and
+ * ringing around the cut are exactly the kind of artefact an attacker could
+ * key on, *and* at q<95 the ringing becomes visually obvious around the
+ * decoy piece silhouettes we paint on top of the background — the mix of
+ * bright edge-rim and dark drop-shadow at the decoy edge is precisely the
+ * high-contrast local signal WebP butchers hardest. At 300x200 the extra few
+ * kilobytes of a higher quality setting are trivial.
+ */
+const BACKGROUND_QUALITY = 95;
+
+export const encodeBackground = (image: RgbaImage): Promise<Buffer> =>
+	sharp(image.data, {
+		raw: { width: image.width, height: image.height, channels: 4 },
+	})
+		.webp({ quality: BACKGROUND_QUALITY, alphaQuality: 100, effort: 4 })
+		.toBuffer();
+
+/**
+ * Lossless. The piece is a 44x44 sprite on transparency, and lossy WebP's
+ * ringing around the alpha edge is the dominant visual artefact — a subtle
+ * ripple that reads as wavy edges even at q=92. Lossless costs ~4 KB per
+ * piece instead of ~2 KB, which is nothing over the wire, and eliminates
+ * the ringing entirely.
+ */
+export const encodePiece = (image: RgbaImage): Promise<Buffer> =>
+	sharp(image.data, {
+		raw: { width: image.width, height: image.height, channels: 4 },
+	})
+		.webp({ lossless: true, alphaQuality: 100, effort: 4 })
+		.toBuffer();
+
+/** PNG, for the preview script only — lossless so artefacts are visible. */
+export const encodePng = (image: RgbaImage): Promise<Buffer> =>
+	sharp(image.data, {
+		raw: { width: image.width, height: image.height, channels: 4 },
+	})
+		.png()
+		.toBuffer();
+
+export const toDataUri = (webp: Buffer): string =>
+	`data:image/webp;base64,${webp.toString("base64")}`;

package/src/index.ts

@@ -0,0 +1,137 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { generateBackground } from "./background.js";
+import { cutNotch } from "./compose.js";
+import { paintDecoys } from "./decoys.js";
+import { encodeBackground, encodePiece } from "./encode.js";
+import { createNotchShape } from "./notch.js";
+import { createPrng, createSeed } from "./prng.js";
+import type {
+	NotchPlacement,
+	PuzzleGeometry,
+	PuzzleRenderSettings,
+	RenderedPuzzle,
+	RgbaImage,
+} from "./types.js";
+
+export { createPrng, createSeed, SEED_BYTES } from "./prng.js";
+export { generateBackground } from "./background.js";
+export { paintDecoys, paintDecoyPiece } from "./decoys.js";
+export {
+	encodeBackground,
+	encodePiece,
+	encodePng,
+	toDataUri,
+} from "./encode.js";
+export type {
+	NotchPlacement,
+	PuzzleGeometry,
+	PuzzleRenderSettings,
+	RenderedPuzzle,
+	RgbaImage,
+} from "./types.js";
+
+/**
+ * Matches the widget's container. Kept here so the generator and the provider
+ * agree on geometry without the provider having to restate it. Geometry is
+ * widget-coupled and not exposed to operators.
+ */
+export const DEFAULT_GEOMETRY: PuzzleGeometry = {
+	width: 300,
+	height: 200,
+	notchSize: 44,
+};
+
+/**
+ * Defaults for the per-render tunables. Operators can override any of these
+ * per-client (via `ClientSettingsSchema.puzzle`) or per-traffic-category
+ * (via `TrafficCategoryPolicySchema.puzzle`); the provider resolves an
+ * effective value and passes it to `renderPuzzle`.
+ */
+export const DEFAULT_RENDER_SETTINGS: PuzzleRenderSettings = {
+	decoyCount: 5,
+	decoyEdgeDarkness: 20,
+	decoyBodyBrightness: 4,
+	holeDarken: 0.55,
+	decoyHoleDarken: 0.7,
+};
+
+/**
+ * Generate a fresh background. Each one is single-use by contract: serving the
+ * same background twice with two different notch positions would let an
+ * attacker diff the two composites and read both targets straight off. The
+ * caller's buffer is responsible for enforcing consume-once.
+ */
+export const createBackground = (
+	geometry: PuzzleGeometry = DEFAULT_GEOMETRY,
+): RgbaImage =>
+	generateBackground(createPrng(createSeed()), geometry.width, geometry.height);
+
+/**
+ * Cut a notch at `placement` and encode both halves.
+ *
+ * The background is consumed (mutated) by this call.
+ */
+export const renderPuzzle = async (
+	background: RgbaImage,
+	placement: NotchPlacement,
+	geometry: PuzzleGeometry = DEFAULT_GEOMETRY,
+	settings: PuzzleRenderSettings = DEFAULT_RENDER_SETTINGS,
+): Promise<RenderedPuzzle> => {
+	const prng = createPrng(createSeed());
+	const pieceSize = geometry.pieceSize ?? geometry.notchSize;
+	// Decoys go on first so the real cut sits on top of any overlap and
+	// always reads as the deepest, darkest region on the board. Decoys use
+	// the same size as the real piece so a solver can't key on scale to
+	// disambiguate the target.
+	paintDecoys(
+		background,
+		prng,
+		settings.decoyCount,
+		pieceSize,
+		placement,
+		settings.decoyEdgeDarkness,
+		settings.decoyBodyBrightness,
+		settings.decoyHoleDarken,
+	);
+	const shape = createNotchShape(prng, pieceSize);
+	const { background: cut, piece } = cutNotch(
+		prng,
+		background,
+		shape,
+		pieceSize,
+		placement,
+		settings.holeDarken,
+	);
+
+	const [backgroundWebp, pieceWebp] = await Promise.all([
+		encodeBackground(cut),
+		encodePiece(piece),
+	]);
+
+	return {
+		background: backgroundWebp,
+		piece: pieceWebp,
+		pieceSize,
+	};
+};
+
+/** Convenience: generate, cut and encode in one call. */
+export const createPuzzle = async (
+	placement: NotchPlacement,
+	geometry: PuzzleGeometry = DEFAULT_GEOMETRY,
+	settings: PuzzleRenderSettings = DEFAULT_RENDER_SETTINGS,
+): Promise<RenderedPuzzle> =>
+	renderPuzzle(createBackground(geometry), placement, geometry, settings);

package/src/notch.ts

@@ -0,0 +1,223 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { Prng } from "./prng.js";
+
+/**
+ * The notch silhouette, as a signed distance field sampled per pixel.
+ *
+ * Distances (rather than a boolean mask) buy anti-aliased edges for free, which
+ * is most of what makes the cut look like a deliberate shape instead of a
+ * staircase. The shape varies per challenge — a rounded square with a knob on a
+ * random side, and sometimes a bite out of another — so the silhouette itself
+ * is not a fixed template an attacker can match against.
+ */
+export interface NotchShape {
+	/** Signed distance in px: negative inside the shape, positive outside. */
+	distance(lx: number, ly: number): number;
+}
+
+type Side = 0 | 1 | 2 | 3;
+
+const sideOffset = (
+	side: Side,
+	half: number,
+	distance: number,
+): [number, number] => {
+	switch (side) {
+		case 0:
+			return [0, -half - distance];
+		case 1:
+			return [half + distance, 0];
+		case 2:
+			return [0, half + distance];
+		default:
+			return [-half - distance, 0];
+	}
+};
+
+const roundedBoxDistance = (
+	px: number,
+	py: number,
+	half: number,
+	radius: number,
+): number => {
+	const qx = Math.abs(px) - half + radius;
+	const qy = Math.abs(py) - half + radius;
+	const outside = Math.hypot(Math.max(qx, 0), Math.max(qy, 0));
+	const inside = Math.min(Math.max(qx, qy), 0);
+	return outside + inside - radius;
+};
+
+const createJigsawShape = (prng: Prng, size: number): NotchShape => {
+	// The body is inset so the knob can protrude without leaving the bounding
+	// box — the caller places the box, not the body.
+	const knobRadius = size * prng.range(0.15, 0.19);
+	const bodyHalf = size / 2 - knobRadius * 0.9;
+	const cornerRadius = bodyHalf * prng.range(0.28, 0.42);
+
+	const knobSide = prng.int(0, 3) as Side;
+	// Sits mostly outside the body edge, so it reads as a tab.
+	const [knobX, knobY] = sideOffset(knobSide, bodyHalf, -knobRadius * 0.45);
+
+	const hasBite = prng.next() < 0.55;
+	const biteSide = ((knobSide + prng.int(1, 3)) % 4) as Side;
+	const biteRadius = size * prng.range(0.13, 0.17);
+	const [biteX, biteY] = sideOffset(biteSide, bodyHalf, -biteRadius * 0.55);
+
+	return {
+		distance(lx: number, ly: number): number {
+			// Local coordinates, origin at the centre of the bounding box.
+			const px = lx - size / 2;
+			const py = ly - size / 2;
+
+			const body = roundedBoxDistance(px, py, bodyHalf, cornerRadius);
+			const knob = Math.hypot(px - knobX, py - knobY) - knobRadius;
+			// Union of body and knob.
+			let d = Math.min(body, knob);
+
+			if (hasBite) {
+				const bite = Math.hypot(px - biteX, py - biteY) - biteRadius;
+				// Subtract the bite from the union.
+				d = Math.max(d, -bite);
+			}
+
+			return d;
+		},
+	};
+};
+
+const createCircleShape = (prng: Prng, size: number): NotchShape => {
+	const radius = (size / 2) * prng.range(0.85, 0.98);
+	const cx = size / 2;
+	const cy = size / 2;
+	return {
+		distance(lx: number, ly: number): number {
+			return Math.hypot(lx - cx, ly - cy) - radius;
+		},
+	};
+};
+
+const createRoundedRectShape = (prng: Prng, size: number): NotchShape => {
+	// One axis fills the box; the other is squashed by a random aspect ratio.
+	// Randomising which axis gets squashed avoids a landscape-only bias.
+	const aspect = prng.range(0.5, 1.0);
+	const halfMax = (size / 2) * prng.range(0.82, 0.98);
+	const [halfW, halfH] =
+		prng.next() < 0.5
+			? [halfMax, halfMax * aspect]
+			: [halfMax * aspect, halfMax];
+	const cornerRadius = Math.min(halfW, halfH) * prng.range(0.08, 0.5);
+	const cx = size / 2;
+	const cy = size / 2;
+	return {
+		distance(lx: number, ly: number): number {
+			const px = lx - cx;
+			const py = ly - cy;
+			const qx = Math.abs(px) - halfW + cornerRadius;
+			const qy = Math.abs(py) - halfH + cornerRadius;
+			const outside = Math.hypot(Math.max(qx, 0), Math.max(qy, 0));
+			const inside = Math.min(Math.max(qx, qy), 0);
+			return outside + inside - cornerRadius;
+		},
+	};
+};
+
+const createPolygonShape = (prng: Prng, size: number): NotchShape => {
+	// Random regular polygon (triangle through octagon), rotated arbitrarily.
+	// SDF is max-of-halfplanes: exact at the boundary and inside, slightly
+	// approximate for far-outside points — fine for the 1-pixel anti-aliased
+	// coverage band. Edge normals are precomputed so the per-pixel loop is a
+	// tight sum-and-max over a handful of values.
+	const n = prng.int(3, 8);
+	const radius = (size / 2) * prng.range(0.85, 0.98);
+	const inradius = radius * Math.cos(Math.PI / n);
+	const rotation = prng.next() * Math.PI * 2;
+	const normals: [number, number][] = [];
+	for (let i = 0; i < n; i++) {
+		// Start at the top and go around; edge i's outward normal points at
+		// angle (2πi/n − π/2) from the +x axis, rotated by `rotation`.
+		const angle = (2 * Math.PI * i) / n - Math.PI / 2 + rotation;
+		normals.push([Math.cos(angle), Math.sin(angle)]);
+	}
+	const cx = size / 2;
+	const cy = size / 2;
+	return {
+		distance(lx: number, ly: number): number {
+			const px = lx - cx;
+			const py = ly - cy;
+			let maxD = Number.NEGATIVE_INFINITY;
+			for (const [nx, ny] of normals) {
+				const d = px * nx + py * ny - inradius;
+				if (d > maxD) maxD = d;
+			}
+			return maxD;
+		},
+	};
+};
+
+const createFlowerShape = (prng: Prng, size: number): NotchShape => {
+	// Sinusoidal boundary: r(θ) = rAvg + rAmp·cos(nθ + φ). Reads as a soft
+	// flower / gear silhouette. Kept smooth (no sharp inner points) so the
+	// coverage sampler doesn't misread narrow petals.
+	const petals = prng.int(4, 8);
+	const rAvg = (size / 2) * prng.range(0.72, 0.88);
+	const rAmp = rAvg * prng.range(0.1, 0.22);
+	const phase = prng.next() * Math.PI * 2;
+	const cx = size / 2;
+	const cy = size / 2;
+	return {
+		distance(lx: number, ly: number): number {
+			const px = lx - cx;
+			const py = ly - cy;
+			const len = Math.hypot(px, py);
+			const angle = Math.atan2(py, px);
+			const r = rAvg + rAmp * Math.cos(petals * angle + phase);
+			return len - r;
+		},
+	};
+};
+
+/**
+ * Pick a random shape family per call. The real piece and its hole are cut
+ * from the same call so they match; decoys each call independently so they
+ * form a mixed field of silhouettes on the frame.
+ */
+export const createNotchShape = (prng: Prng, size: number): NotchShape => {
+	const family = prng.int(0, 4);
+	switch (family) {
+		case 0:
+			return createJigsawShape(prng, size);
+		case 1:
+			return createCircleShape(prng, size);
+		case 2:
+			return createRoundedRectShape(prng, size);
+		case 3:
+			return createPolygonShape(prng, size);
+		default:
+			return createFlowerShape(prng, size);
+	}
+};
+
+/**
+ * Anti-aliased coverage in [0, 1] for a signed distance, using a one-pixel
+ * transition band centred on the boundary.
+ */
+export const coverageFromDistance = (distance: number): number => {
+	const t = 0.5 - distance;
+	if (t <= 0) return 0;
+	if (t >= 1) return 1;
+	// smoothstep, so the edge ramp is not linear and reads softer.
+	return t * t * (3 - 2 * t);
+};