@crabcrop/url 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Compute the signature segment for a remainder: the lowercase
+ * hex HMAC-SHA256 of `remainder` under `secret`. The remainder
+ * is everything after the signature segment in the URL,
+ * exactly as it will appear.
+ */
+export declare function sign(secret: string, remainder: string): string;
+/**
+ * The purge signature for a target path (the request
+ * remainder without its signature): HMAC-SHA256 of the
+ * path under a subkey derived from the secret (the raw
+ * HMAC of the secret over the label `crabcrop/purge-key`),
+ * so an image signature can never be replayed as a purge
+ * signature. This is the signature segment for
+ * `POST /purge/<signature>/<path>`.
+ */
+export declare function purgeSignature(secret: string, target: string): string;
+/**
+ * The purge-group signature for a cache group: HMAC-SHA256
+ * of the group name under a subkey derived from the secret
+ * (the raw HMAC of the secret over the label
+ * `crabcrop/purge-group-key`), its own domain beside the
+ * purge subkey, so a per-target purge signature can never
+ * be transplanted to the purge-group endpoint. The helper
+ * exists so nobody has to know the signed string. This is
+ * the signature segment for
+ * `POST /purge-group/<signature>/<group>`.
+ */
+export declare function purgeGroupSignature(secret: string, group: string): string;
+/**
+ * The upload signature for an object name: HMAC-SHA256 of
+ * the name under a subkey derived from the secret (the raw
+ * HMAC of the secret over the label `crabcrop/upload-key`),
+ * so neither an image signature nor a purge signature can
+ * ever be replayed as an upload signature. This is the
+ * signature segment for `PUT /upload/<signature>/<name>`.
+ *
+ * With `expires` (unix seconds), the signature covers
+ * `exp:<expires>/<name>` instead, and the request path is
+ * `PUT /upload/<signature>/exp:<expires>/<name>`: the
+ * expiry sits inside the signed string, so it can neither
+ * be stripped nor extended, and the server refuses the
+ * upload once that second is reached. Delegated upload
+ * tokens should always use the expiring form; without it
+ * a token replays until the secret rotates.
+ */
+export declare function uploadSignature(secret: string, name: string, expires?: number): string;
+export interface BuildOptions {
+    /** Unix-seconds expiry, emitted as a leading `exp:` segment. */
+    expires?: number;
+    /**
+     * Key ID to stamp on the signature segment (`<key-id>:<tag>`),
+     * for servers running a secret rotation: they verify a keyed
+     * segment against the named key only. Requires a non-null
+     * secret (an `unsafe` URL has no key to name).
+     */
+    keyId?: string;
+}
+/** Whether `id` is a well-formed key ID (1-32 of `[A-Za-z0-9_-]`). */
+export declare function isValidKeyId(id: string): boolean;
+/**
+ * The signature segment for a keyed signature: `<key-id>:`
+ * followed by the hex tag `sign` computes.
+ */
+export declare function signWithKeyId(secret: string, keyId: string, remainder: string): string;
+/**
+ * Assemble a signed (or `unsafe`) crabcrop URL. `operations`
+ * is the operation string verbatim (several `/`-separated
+ * segments and `preset:` references included). A null secret
+ * produces the literal `unsafe` signature segment, for servers
+ * running with unsafe or presets-only configurations.
+ */
+export declare function buildURL(base: string, secret: string | null, operations: string, source: string, options?: BuildOptions): string;
+/**
+ * Build an `srcset` attribute value: one `{width}x0` URL per
+ * width, entries formatted `{url} {width}w` and joined by
+ * `, `. An expiry, when given, applies to every entry.
+ */
+export declare function buildSrcSet(base: string, secret: string | null, source: string, widths: number[], options?: BuildOptions): string;
+export { explainUrl } from "./explain.ts";
+export { FILTER_DESCRIPTIONS } from "./explain.ts";
+export type { ExplainedSegment, Explanation, SegmentKind, SignatureKind } from "./explain.ts";
+export { filter, joinOps, ops } from "./operations.ts";
+export type { Anchor, BlendMode, CropAlign, CurveChannel, Dimension, ImageFormat, MaskShape, } from "./operations.ts";
+/**
+ * Verify a URL's signature locally. Returns true or false, or
+ * null when the URL is unsigned or malformed.
+ *
+ * With a single secret string, the key ID (when the URL
+ * carries one) is ignored: the question is whether this
+ * secret made the tag. With a keyring (a map of key ID to
+ * secret), the server's rotation semantics apply: a keyed
+ * URL consults exactly its named key (an unknown ID is
+ * false), and an unkeyed URL consults every key in the map.
+ */
+export declare function verifyUrlSignature(secret: string | Record<string, string>, input: string): boolean | null;

package/dist/index.js

@@ -0,0 +1,202 @@
+/**
+ * Build and sign crabcrop URLs, per `spec/url-signing.md` in
+ * the crabcrop repository. Standard library only.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * Compute the signature segment for a remainder: the lowercase
+ * hex HMAC-SHA256 of `remainder` under `secret`. The remainder
+ * is everything after the signature segment in the URL,
+ * exactly as it will appear.
+ */
+export function sign(secret, remainder) {
+    return createHmac("sha256", secret).update(remainder, "utf8").digest("hex");
+}
+/**
+ * The purge signature for a target path (the request
+ * remainder without its signature): HMAC-SHA256 of the
+ * path under a subkey derived from the secret (the raw
+ * HMAC of the secret over the label `crabcrop/purge-key`),
+ * so an image signature can never be replayed as a purge
+ * signature. This is the signature segment for
+ * `POST /purge/<signature>/<path>`.
+ */
+export function purgeSignature(secret, target) {
+    const subkey = Buffer.from(sign(secret, "crabcrop/purge-key"), "hex");
+    return createHmac("sha256", subkey).update(target, "utf8").digest("hex");
+}
+/**
+ * The purge-group signature for a cache group: HMAC-SHA256
+ * of the group name under a subkey derived from the secret
+ * (the raw HMAC of the secret over the label
+ * `crabcrop/purge-group-key`), its own domain beside the
+ * purge subkey, so a per-target purge signature can never
+ * be transplanted to the purge-group endpoint. The helper
+ * exists so nobody has to know the signed string. This is
+ * the signature segment for
+ * `POST /purge-group/<signature>/<group>`.
+ */
+export function purgeGroupSignature(secret, group) {
+    const subkey = Buffer.from(sign(secret, "crabcrop/purge-group-key"), "hex");
+    return createHmac("sha256", subkey).update(group, "utf8").digest("hex");
+}
+/**
+ * The upload signature for an object name: HMAC-SHA256 of
+ * the name under a subkey derived from the secret (the raw
+ * HMAC of the secret over the label `crabcrop/upload-key`),
+ * so neither an image signature nor a purge signature can
+ * ever be replayed as an upload signature. This is the
+ * signature segment for `PUT /upload/<signature>/<name>`.
+ *
+ * With `expires` (unix seconds), the signature covers
+ * `exp:<expires>/<name>` instead, and the request path is
+ * `PUT /upload/<signature>/exp:<expires>/<name>`: the
+ * expiry sits inside the signed string, so it can neither
+ * be stripped nor extended, and the server refuses the
+ * upload once that second is reached. Delegated upload
+ * tokens should always use the expiring form; without it
+ * a token replays until the secret rotates.
+ */
+export function uploadSignature(secret, name, expires) {
+    const subkey = Buffer.from(sign(secret, "crabcrop/upload-key"), "hex");
+    const signed = expires === undefined ? name : `exp:${expires}/${name}`;
+    return createHmac("sha256", subkey).update(signed, "utf8").digest("hex");
+}
+/** Whether `id` is a well-formed key ID (1-32 of `[A-Za-z0-9_-]`). */
+export function isValidKeyId(id) {
+    return /^[A-Za-z0-9_-]{1,32}$/.test(id);
+}
+/**
+ * The signature segment for a keyed signature: `<key-id>:`
+ * followed by the hex tag `sign` computes.
+ */
+export function signWithKeyId(secret, keyId, remainder) {
+    if (!isValidKeyId(keyId)) {
+        throw new Error(`invalid key ID ${JSON.stringify(keyId)}: 1 to 32 characters of [A-Za-z0-9_-]`);
+    }
+    return `${keyId}:${sign(secret, remainder)}`;
+}
+/**
+ * Fail loudly on inputs that can never produce a verifiable URL
+ * (audit P-4, P-5): the remainder travels as a raw URL path, so
+ * `?`/`#` would truncate it and whitespace, control, and
+ * non-ASCII characters cannot be sent as-is; an expiry must be
+ * a non-negative integer the server's u64 parser accepts.
+ */
+function assertUrlText(text, what) {
+    for (const c of text) {
+        const code = c.codePointAt(0);
+        if (c === "?" || c === "#" || code <= 0x20 || code === 0x7f || code > 0x7e) {
+            throw new Error(`${what} contains a character that cannot appear in a crabcrop URL: ${JSON.stringify(c)}`);
+        }
+    }
+}
+function assertExpires(expires) {
+    if (!Number.isSafeInteger(expires) || expires < 0) {
+        throw new Error(`expires must be a non-negative integer number of unix seconds, got ${expires}`);
+    }
+}
+/**
+ * A srcset width becomes a `{width}x0` size segment, so it
+ * must satisfy the grammar's dimension rules: a positive
+ * integer within the server cap. Anything else mints a
+ * URL the server rejects (or worse, `-300` reads as a
+ * flip), so it throws here, at build time.
+ */
+function assertWidth(width) {
+    if (!Number.isSafeInteger(width) || width < 1 || width > 16383) {
+        throw new Error(`srcset width must be a positive integer no larger than 16383, got ${width}`);
+    }
+}
+/**
+ * Assemble a signed (or `unsafe`) crabcrop URL. `operations`
+ * is the operation string verbatim (several `/`-separated
+ * segments and `preset:` references included). A null secret
+ * produces the literal `unsafe` signature segment, for servers
+ * running with unsafe or presets-only configurations.
+ */
+export function buildURL(base, secret, operations, source, options = {}) {
+    if (options.expires !== undefined) {
+        assertExpires(options.expires);
+    }
+    assertUrlText(operations, "operations");
+    assertUrlText(source, "source");
+    const trimmedBase = base.replace(/\/+$/, "");
+    let remainder = "";
+    if (options.expires !== undefined) {
+        remainder += `exp:${options.expires}/`;
+    }
+    if (operations) {
+        remainder += `${operations}/`;
+    }
+    remainder += source;
+    let signature;
+    if (secret === null) {
+        if (options.keyId !== undefined) {
+            throw new Error("keyId requires a secret: an unsafe URL has no key to name");
+        }
+        signature = "unsafe";
+    }
+    else if (options.keyId !== undefined) {
+        signature = signWithKeyId(secret, options.keyId, remainder);
+    }
+    else {
+        signature = sign(secret, remainder);
+    }
+    return `${trimmedBase}/${signature}/${remainder}`;
+}
+/**
+ * Build an `srcset` attribute value: one `{width}x0` URL per
+ * width, entries formatted `{url} {width}w` and joined by
+ * `, `. An expiry, when given, applies to every entry.
+ */
+export function buildSrcSet(base, secret, source, widths, options = {}) {
+    for (const w of widths) {
+        assertWidth(w);
+    }
+    return widths
+        .map((w) => `${buildURL(base, secret, `${w}x0`, source, options)} ${w}w`)
+        .join(", ");
+}
+export { explainUrl } from "./explain.js";
+export { FILTER_DESCRIPTIONS } from "./explain.js";
+export { filter, joinOps, ops } from "./operations.js";
+import { explainUrl } from "./explain.js";
+/**
+ * Verify a URL's signature locally. Returns true or false, or
+ * null when the URL is unsigned or malformed.
+ *
+ * With a single secret string, the key ID (when the URL
+ * carries one) is ignored: the question is whether this
+ * secret made the tag. With a keyring (a map of key ID to
+ * secret), the server's rotation semantics apply: a keyed
+ * URL consults exactly its named key (an unknown ID is
+ * false), and an unkeyed URL consults every key in the map.
+ */
+export function verifyUrlSignature(secret, input) {
+    const { signature, remainder } = explainUrl(input);
+    if (!signature || signature.kind !== "hmac") {
+        return null;
+    }
+    // Constant-time, like the Rust and Python verifiers: a
+    // plain === leaks how much of the tag was right.
+    const given = Buffer.from(signature.value, "utf8");
+    const matches = (candidate) => {
+        const expected = Buffer.from(sign(candidate, remainder), "utf8");
+        return expected.length === given.length && timingSafeEqual(expected, given);
+    };
+    if (typeof secret === "string") {
+        return matches(secret);
+    }
+    if (signature.keyId !== undefined) {
+        // Own properties only: key IDs are attacker-shaped text
+        // (`constructor`, `toString`, `__proto__` are all legal
+        // IDs), and an inherited lookup would hand a non-string
+        // to the HMAC and throw instead of answering false.
+        const candidate = Object.hasOwn(secret, signature.keyId)
+            ? secret[signature.keyId]
+            : undefined;
+        return typeof candidate === "string" ? matches(candidate) : false;
+    }
+    return Object.values(secret).some(matches);
+}

package/dist/operations.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Typed builders for crabcrop operation strings (AP-24).
+ *
+ * `buildURL` takes operations verbatim, by design: the string
+ * is the spec. This module is the optional typed surface over
+ * it: each call validates its arguments against the server's
+ * grammar (the same bounds the explainer enforces) and returns
+ * the operation segment in its canonical spelling, so a typed
+ * pipeline and the equivalent hand-written string produce
+ * byte-identical URLs. Validation throws at build time, like
+ * `buildSrcSet` does for widths: a value the server would 400
+ * never gets signed.
+ */
+/** Output formats the `format(...)` filter accepts. */
+export type ImageFormat = "jpeg" | "jpg" | "png" | "webp" | "jxl" | "avif" | "gif" | "mp4" | "webm";
+/** Crop alignments; `center` is the bare `crop:WxH` spelling. */
+export type CropAlign = "center" | "smart" | "face" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+/** Text-overlay anchor points. */
+export type Anchor = "top-left" | "top-center" | "top-right" | "center-left" | "center" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right";
+/** Overlay blend modes. */
+export type BlendMode = "normal" | "multiply" | "screen" | "overlay";
+/** Mask shapes for the `mask(...)` filter. */
+export type MaskShape = "circle" | "ellipse";
+/** Channels the `curve(...)` filter remaps. */
+export type CurveChannel = "rgb" | "r" | "g" | "b";
+/**
+ * One side of a size: a pixel count (1..16383), 0 for
+ * proportional, a negative count to flip that axis, or
+ * `"orig"` for the source's own dimension.
+ */
+export type Dimension = number | "orig";
+/** Operation segments, one typed call per segment kind. */
+export declare const ops: {
+    /** `300x200`; each side a Dimension (0 proportional, negative flips). */
+    size(width: Dimension, height: Dimension): string;
+    /**
+     * `fit-in:300x200`; no flips (the server rejects them here).
+     * With `adaptive`, `fit-in:300x200:adaptive`: the box axes
+     * swap when the source orientation disagrees with the box's.
+     */
+    fitIn(width: Dimension, height: Dimension, adaptive?: boolean): string;
+    /** `crop:300x200` or `crop:300x200:smart`; an exact pixel box. */
+    crop(width: number, height: number, align?: CropAlign): string;
+    /** `crop-rect:10x20:110x220` (left x top : right x bottom). */
+    cropRect(left: number, top: number, right: number, bottom: number): string;
+    /** `focal:10x20:110x220` (left x top : right x bottom); steers the next crop. */
+    focal(left: number, top: number, right: number, bottom: number): string;
+    /** `pad:300x200`, optionally `:blur` or a RRGGBB fill color. */
+    pad(width: number, height: number, fill?: "blur" | string): string;
+    /** `preset:thumb`; expands server-side. */
+    preset(name: string): string;
+    /**
+     * `maxage:60`; this response's Cache-Control lifetime in
+     * seconds (0 to 31536000), overriding the default year for
+     * this request only. Header-only: it never enters the
+     * cache key, so spellings that differ only here share one
+     * stored image.
+     */
+    maxage(seconds: number): string;
+    /**
+     * `debug:focal`; the smart-crop debug view. Place it
+     * before the crop it annotates: the response is a
+     * diagnostic image of the focal decision (focal point,
+     * focal rectangle, crop window drawn on the crop's
+     * canvas), never the transform result, and it is never
+     * cached (served with Cache-Control: no-store).
+     */
+    debugFocal(): string;
+    /** Join filter calls into one `filters:` segment. */
+    filters(...calls: string[]): string;
+};
+/** Join operation segments into the operations string `buildURL` takes. */
+export declare function joinOps(...segments: string[]): string;
+/** Filter calls for `ops.filters(...)`; each returns its canonical spelling. */
+export declare const filter: {
+    grayscale(): string;
+    invert(): string;
+    noUpscale(): string;
+    equalize(): string;
+    removeBg(): string;
+    keepProfile(): string;
+    sepia(): string;
+    blurFaces(): string;
+    pixelateFaces(): string;
+    /** Gaussian blur by sigma (positive). */
+    blur(sigma: number): string;
+    /** Unsharp-mask strength (positive). */
+    sharpen(amount: number): string;
+    /** Add to every channel: -255..255. */
+    brighten(amount: number): string;
+    /** Percent contrast: -100..100 (0 unchanged, -100 flat). */
+    contrast(percent: number): string;
+    /** Rotate the hue by integer degrees. */
+    hueRotate(degrees: number): string;
+    /** Saturation factor: 0..255 (0 grayscale, 1 identity). */
+    saturation(factor: number): string;
+    /** Per-channel offsets, each -255..255. */
+    rgb(r: number, g: number, b: number): string;
+    /**
+     * Tone curve: remap the channel through 2 to 16 [x, y]
+     * control points, each coordinate 0..255 with x strictly
+     * increasing. Between points the server interpolates
+     * linearly; inputs outside the point range clamp to the
+     * nearest end value.
+     */
+    curve(channel: CurveChannel, points: [number, number][]): string;
+    /**
+     * Convolution: apply a caller-supplied kernel, 9 values
+     * (3x3) or 25 (5x5) in row-major order, each a plain
+     * decimal from -1024 to 1024. With normalize set the
+     * server scales the kernel by the sum of its entries
+     * first (a zero sum applies the kernel as written). The
+     * edges replicate. `normalize` is a boolean or the 0/1
+     * flag itself.
+     */
+    convolution(values: number[], normalize?: boolean | 0 | 1): string;
+    /**
+     * Film grain: one noise value per pixel, added equally
+     * to all three channels (alpha untouched), the value
+     * uniform in plus or minus the given percent of full
+     * scale. The field is deterministic, seeded from the
+     * image content and the amount, so the same request
+     * always renders the same bytes; 0 is a no-op.
+     */
+    noise(amount: number): string;
+    /**
+     * Rotate by an angle in degrees (decimals allowed, no
+     * exponent spelling); multiples of 90 are exact quarter
+     * turns on the server.
+     */
+    rotate(angle: number): string;
+    /** Trim uniform borders; tolerance 0..255, default 10. */
+    trim(tolerance?: number): string;
+    /** Encoding quality 1..100, or `"auto"` for perceptual targeting. */
+    quality(value: number | "auto"): string;
+    format(format: ImageFormat): string;
+    /** The background color other operations pad with (RRGGBB). */
+    fill(color: string): string;
+    /** How much a face crop expands around the face: 0..3. */
+    facePad(amount: number): string;
+    /** AI upscale by the given factor. */
+    upscale(factor: 2 | 4): string;
+    /** Device pixel ratio the sizes are multiplied by. */
+    dpr(factor: 1 | 1.5 | 2 | 3): string;
+    /** Cap the output bytes, lowering quality to fit: at least 1. */
+    maxBytes(bytes: number): string;
+    /** Round the corners: one radius for all, or [tl, tr, br, bl]. */
+    radius(value: number | [number, number, number, number]): string;
+    /** Paint an opaque border inside the frame (RRGGBB). */
+    border(width: number, color: string): string;
+    mask(shape: MaskShape): string;
+    duotone(shadow: string, highlight: string): string;
+    monochrome(color: string): string;
+    /** Mosaic block size in pixels: 1..16383. */
+    pixelate(blockSize: number): string;
+    flip(axis: "h" | "v"): string;
+    /** Overlay a watermark image at (x, y), opacity 0..100. */
+    watermark(url: string, x: number, y: number, alpha: number): string;
+    /**
+     * Composite another image over the result at (x, y) with
+     * opacity 0..100 and a blend mode; `widthPct` optionally
+     * scales it to that percent of the base width (1..400).
+     */
+    overlay(url: string, x: number, y: number, alpha: number, blend: BlendMode, widthPct?: number): string;
+    /**
+     * Draw a text overlay. Color is RRGGBB or RRGGBBAA; the
+     * canonical spelling is always eight lowercase hex digits.
+     */
+    text(content: string, size: number, color: string, anchor: Anchor): string;
+    /** Blur every detected object of the named class. */
+    blurClass(name: string): string;
+    /** Pixelate every detected object of the named class. */
+    pixelateClass(name: string): string;
+    /** Blur the rectangle (x, y, w, h) in pixels. */
+    blurRegion(x: number, y: number, w: number, h: number): string;
+    /** Pixelate the rectangle (x, y, w, h) in pixels. */
+    pixelateRegion(x: number, y: number, w: number, h: number): string;
+};