@prosopo/puzzle-assets 0.1.4 → 0.2.1

package/src/decoys.ts

@@ -1,191 +0,0 @@
-// 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

@@ -1,59 +0,0 @@
-// 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

@@ -1,137 +0,0 @@
-// 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

@@ -1,223 +0,0 @@
-// 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);
-};