@crewhaus/tool-money 0.7.0

package/dist/lib/tax.js

@@ -0,0 +1,139 @@
+/**
+ * Per-line tax from an operator's own rate tables.
+ *
+ * Money is integer minor units throughout — cents, pence, satoshi-free. A
+ * tax engine that computes in floating point produces totals that do not add
+ * up, and "off by a cent" in an invoice is not a rounding detail, it is a
+ * document that fails an audit.
+ *
+ * Two choices are the caller's and neither has a safe default, so both are
+ * explicit: whether listed prices already include tax, and whether rounding
+ * happens per line or once per invoice. Jurisdictions differ, the totals
+ * differ, and a tool that picked one silently would be wrong half the time.
+ */
+export const ROUNDING_MODES = ["half-up", "half-even", "down", "up"];
+export const ROUNDING_SCOPES = ["line", "invoice"];
+/** Round a rational to an integer, by the caller's rule. */
+export function roundMinor(numerator, denominator, mode) {
+    if (denominator === 0)
+        throw new Error("denominator must not be zero");
+    const negative = numerator < 0 !== denominator < 0;
+    const n = Math.abs(numerator);
+    const d = Math.abs(denominator);
+    const whole = Math.floor(n / d);
+    const remainder = n - whole * d;
+    let result;
+    switch (mode) {
+        case "down":
+            result = whole;
+            break;
+        case "up":
+            result = remainder > 0 ? whole + 1 : whole;
+            break;
+        case "half-even": {
+            const twice = remainder * 2;
+            if (twice > d)
+                result = whole + 1;
+            else if (twice < d)
+                result = whole;
+            // Exactly half: go to the even neighbour. Over many lines this is what
+            // keeps a total from drifting upward the way half-up does.
+            else
+                result = whole % 2 === 0 ? whole : whole + 1;
+            break;
+        }
+        default:
+            result = remainder * 2 >= d ? whole + 1 : whole;
+    }
+    return negative ? -result : result;
+}
+const BPS_DENOMINATOR = 10_000;
+export function calculateTax(lines, rates, options = {}) {
+    const mode = options.rounding ?? "half-up";
+    const scope = options.scope ?? "line";
+    const byCodeIndex = new Map(rates.map((r) => [r.code, r]));
+    for (const line of lines) {
+        for (const code of line.taxCodes) {
+            if (!byCodeIndex.has(code)) {
+                throw new Error(`line "${line.id}" uses tax code "${code}", which is not in the rate table — add it rather than letting the line go untaxed`);
+            }
+        }
+    }
+    if (!Number.isInteger(lines.reduce((s, l) => s + l.amountMinor, 0))) {
+        throw new Error("amounts must be integer minor units");
+    }
+    const tally = new Map();
+    const results = [];
+    // Exact totals kept as numerator over BPS_DENOMINATOR, so invoice-scope
+    // rounding rounds the true sum rather than a sum of rounded pieces.
+    let exactTaxNumerator = 0;
+    for (const line of lines) {
+        if (!Number.isInteger(line.amountMinor)) {
+            throw new Error(`line "${line.id}" has a non-integer amount; use minor units`);
+        }
+        const applied = line.exempt || options.reverseCharge ? [] : line.taxCodes;
+        const rateList = applied.map((code) => byCodeIndex.get(code));
+        // Net is the base everything is charged on. When listed prices already
+        // include tax it has to be recovered first: gross / (1 + total rate).
+        let netMinor;
+        if (options.pricesIncludeTax && rateList.length > 0) {
+            let multiplier = BPS_DENOMINATOR;
+            for (const rate of rateList) {
+                multiplier = rate.compound
+                    ? Math.round((multiplier * (BPS_DENOMINATOR + rate.bps)) / BPS_DENOMINATOR)
+                    : multiplier + rate.bps;
+            }
+            netMinor = roundMinor(line.amountMinor * BPS_DENOMINATOR, multiplier, mode);
+        }
+        else {
+            netMinor = line.amountMinor;
+        }
+        const breakdown = [];
+        let lineTax = 0;
+        for (const rate of rateList) {
+            // `compound` describes the base THIS rate is charged on — net plus the
+            // taxes already applied — not an effect on the rates after it. Adding
+            // to the base afterwards instead left the compound rate itself charged
+            // on the bare net, which is the whole thing the flag exists to change.
+            const base = rate.compound ? netMinor + lineTax : netMinor;
+            const numerator = base * rate.bps;
+            const taxMinor = roundMinor(numerator, BPS_DENOMINATOR, mode);
+            exactTaxNumerator += numerator;
+            breakdown.push({ code: rate.code, bps: rate.bps, taxMinor });
+            lineTax += taxMinor;
+            const seen = tally.get(rate.code) ?? { bps: rate.bps, taxMinor: 0, netMinor: 0 };
+            tally.set(rate.code, {
+                bps: rate.bps,
+                taxMinor: seen.taxMinor + taxMinor,
+                netMinor: seen.netMinor + netMinor,
+            });
+        }
+        results.push({
+            id: line.id,
+            netMinor,
+            taxMinor: lineTax,
+            grossMinor: netMinor + lineTax,
+            breakdown,
+            note: options.reverseCharge
+                ? "reverse charge: the customer accounts for the tax"
+                : line.exempt
+                    ? "exempt: outside the scope of tax, which is not a zero rate"
+                    : "",
+        });
+    }
+    const netMinor = results.reduce((s, r) => s + r.netMinor, 0);
+    const summedTax = results.reduce((s, r) => s + r.taxMinor, 0);
+    const taxMinor = scope === "invoice" ? roundMinor(exactTaxNumerator, BPS_DENOMINATOR, mode) : summedTax;
+    return {
+        lines: results,
+        netMinor,
+        taxMinor,
+        grossMinor: netMinor + taxMinor,
+        byCode: [...tally.entries()]
+            .map(([code, v]) => ({ code, ...v }))
+            .sort((a, b) => (a.code < b.code ? -1 : 1)),
+        reverseCharge: options.reverseCharge === true,
+        rounding: mode,
+        scope,
+    };
+}

package/dist/lib/webhook.d.ts

@@ -0,0 +1,30 @@
+export type VerifyOptions = {
+    /** How old a signature may be, in seconds. Default 300, as Stripe's does. */
+    readonly toleranceSeconds?: number;
+    /** Epoch milliseconds. Supplied rather than read, so a replay is reproducible. */
+    readonly nowMs: number;
+    /** The signature scheme in the header. Default `v1`. */
+    readonly scheme?: string;
+};
+export type VerifyResult = {
+    readonly valid: boolean;
+    /** Empty when valid; otherwise exactly what failed. */
+    readonly reason: string;
+    readonly timestamp: number | null;
+    readonly ageSeconds: number | null;
+    /** How many candidate signatures the header carried. */
+    readonly signaturesTried: number;
+};
+/** Parse `t=1614556800,v1=abc,v1=def` into its parts. */
+export declare function parseSignatureHeader(header: string): {
+    timestamp: number | null;
+    signatures: Map<string, string[]>;
+};
+/**
+ * Verify a webhook signature.
+ *
+ * `body` must be the RAW bytes as received. Re-serializing parsed JSON
+ * changes key order and whitespace, and the signature is over the bytes —
+ * which is why this takes a string or a Buffer and never an object.
+ */
+export declare function verifyWebhookSignature(body: string | Uint8Array, header: string, secret: string, options: VerifyOptions): VerifyResult;

package/dist/lib/webhook.js

@@ -0,0 +1,116 @@
+/**
+ * Verify a signed webhook before believing a word of it.
+ *
+ * A payment webhook says money moved. Anyone who can reach the endpoint can
+ * post that claim, so the signature is the only thing separating an event
+ * from an assertion by a stranger — and a harness that acts on an unverified
+ * "payment succeeded" ships goods for free.
+ *
+ * The scheme implemented is Stripe's, which several providers copy: a header
+ * carrying a timestamp and one or more signatures, over `timestamp.body`,
+ * HMAC-SHA256, hex. The comparison is constant-time and the timestamp is
+ * checked, because a signature that never expires is a replay waiting to
+ * happen.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** Parse `t=1614556800,v1=abc,v1=def` into its parts. */
+export function parseSignatureHeader(header) {
+    const signatures = new Map();
+    let timestamp = null;
+    for (const piece of header.split(",")) {
+        const eq = piece.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = piece.slice(0, eq).trim();
+        const value = piece.slice(eq + 1).trim();
+        if (key === "t") {
+            const parsed = Number.parseInt(value, 10);
+            timestamp = Number.isNaN(parsed) ? null : parsed;
+            continue;
+        }
+        const list = signatures.get(key);
+        if (list)
+            list.push(value);
+        else
+            signatures.set(key, [value]);
+    }
+    return { timestamp, signatures };
+}
+/** Compare two hex digests without leaking where they first differ. */
+function constantTimeEqualHex(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let left;
+    let right;
+    try {
+        left = Buffer.from(a, "hex");
+        right = Buffer.from(b, "hex");
+    }
+    catch {
+        return false;
+    }
+    if (left.length !== right.length || left.length === 0)
+        return false;
+    return timingSafeEqual(left, right);
+}
+/**
+ * Verify a webhook signature.
+ *
+ * `body` must be the RAW bytes as received. Re-serializing parsed JSON
+ * changes key order and whitespace, and the signature is over the bytes —
+ * which is why this takes a string or a Buffer and never an object.
+ */
+export function verifyWebhookSignature(body, header, secret, options) {
+    const { timestamp, signatures } = parseSignatureHeader(header);
+    const scheme = options.scheme ?? "v1";
+    const candidates = signatures.get(scheme) ?? [];
+    if (timestamp === null) {
+        return {
+            valid: false,
+            reason: "the header carries no timestamp",
+            timestamp: null,
+            ageSeconds: null,
+            signaturesTried: 0,
+        };
+    }
+    if (candidates.length === 0) {
+        return {
+            valid: false,
+            reason: `the header carries no "${scheme}" signature`,
+            timestamp,
+            ageSeconds: null,
+            signaturesTried: 0,
+        };
+    }
+    const ageSeconds = Math.floor(options.nowMs / 1000) - timestamp;
+    const tolerance = options.toleranceSeconds ?? 300;
+    const payload = Buffer.concat([
+        Buffer.from(`${timestamp}.`, "utf8"),
+        typeof body === "string" ? Buffer.from(body, "utf8") : Buffer.from(body),
+    ]);
+    const expected = createHmac("sha256", secret).update(payload).digest("hex");
+    const matched = candidates.some((candidate) => constantTimeEqualHex(candidate, expected));
+    // The signature is checked first and the age second, so a forged request
+    // cannot learn anything from which complaint it gets back.
+    if (!matched) {
+        return {
+            valid: false,
+            reason: "no signature in the header matches the body",
+            timestamp,
+            ageSeconds,
+            signaturesTried: candidates.length,
+        };
+    }
+    if (Math.abs(ageSeconds) > tolerance) {
+        return {
+            valid: false,
+            reason: ageSeconds > 0
+                ? `the signature is ${ageSeconds}s old, past the ${tolerance}s tolerance — it may be a replay`
+                : `the signature is timestamped ${-ageSeconds}s in the future, past the ${tolerance}s tolerance`,
+            timestamp,
+            ageSeconds,
+            signaturesTried: candidates.length,
+        };
+    }
+    return { valid: true, reason: "", timestamp, ageSeconds, signaturesTried: candidates.length };
+}

package/dist/paths.d.ts

@@ -0,0 +1,42 @@
+import { CrewhausError } from "@crewhaus/errors";
+/** Raised when a caller-supplied path resolves outside the workspace root. */
+export declare class ToolPermissionError extends CrewhausError {
+    readonly name = "ToolPermissionError";
+    readonly toolName: string;
+    readonly path: string;
+    constructor(toolName: string, attemptedPath: string);
+}
+/**
+ * A validated path, in both forms the tools need.
+ *
+ * `real` has every in-workspace symlink already resolved and is what I/O
+ * should use — operating on it closes most of the check-to-use window.
+ * `abs` is the lexical resolution, which is what a tool must use when the
+ * question is about the link ITSELF (`Stat` reporting a symlink target,
+ * `RemovePath` deleting a link rather than its destination).
+ */
+export type SafePath = {
+    readonly abs: string;
+    readonly real: string;
+    /** The path as the caller wrote it, for echoing back in results. */
+    readonly given: string;
+    /** Slash-separated path relative to the workspace root. */
+    readonly rel: string;
+};
+/** The workspace root, resolved. Every path is contained within it. */
+export declare function workspaceRoot(): string;
+export declare function resolveSafe(toolName: string, rel: string, root?: string): SafePath;
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export declare function toPosix(p: string): string;
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export declare function isInside(parent: string, candidate: string): boolean;
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export declare function archiveEntryEscapes(name: string): boolean;

package/dist/paths.js

@@ -0,0 +1,158 @@
+/**
+ * Path containment — the gate every caller-supplied path in this package
+ * passes through before any syscall touches it.
+ *
+ * The approach is the one `@crewhaus/tool-fs` uses, and for the same reasons:
+ * a lexical check alone is fooled by a symlink that lives inside the
+ * workspace and points outside it (CWE-59), so the real path is checked too.
+ * The workspace root is `process.cwd()`, matching tool-fs, so a harness that
+ * trusts one tool's boundary gets the same boundary here.
+ */
+import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import * as path from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+/** Raised when a caller-supplied path resolves outside the workspace root. */
+export class ToolPermissionError extends CrewhausError {
+    name = "ToolPermissionError";
+    toolName;
+    path;
+    constructor(toolName, attemptedPath) {
+        super("tool", `tool "${toolName}" rejected path "${attemptedPath}": resolved location escapes the workspace root`);
+        this.toolName = toolName;
+        this.path = attemptedPath;
+    }
+}
+/** The workspace root, resolved. Every path is contained within it. */
+export function workspaceRoot() {
+    return path.resolve(process.cwd());
+}
+/**
+ * Resolve `rel` inside the workspace, or throw `ToolPermissionError`.
+ *
+ * The leaf is allowed not to exist — every tool here that creates something
+ * needs to validate a destination before it is made — so the deepest
+ * EXISTING ancestor is realpath'd and the missing tail re-appended. Any
+ * failure other than that walk fails closed.
+ */
+/**
+ * True when the NAME exists, whether or not it leads anywhere.
+ *
+ * `existsSync` FOLLOWS symlinks, so it answers false for a link whose target
+ * is missing — and that is exactly the case that matters: a dangling link is
+ * still a door, because `open(…, "w")` through `evil -> /outside/x` CREATES
+ * `/outside/x`. Probing with `lstat` keeps the link's name in the part of the
+ * path that gets resolved, rather than in the "does not exist yet" tail that
+ * is re-appended to the root verbatim and so passes the containment check.
+ */
+function nameExists(p) {
+    try {
+        lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where `target` would actually land, with every symlink on the way already
+ * followed — including one whose own target does not exist yet.
+ *
+ * `realpathSync` gives up with ENOENT on a dangling link, which would leave
+ * that link unresolved and let it stand in for a plain missing file. So the
+ * deepest ancestor that exists as a NAME is resolved, a dangling one is
+ * followed a hop by hand, and the components that do not exist are appended.
+ * The result is the path an `open` would create, which is the only path worth
+ * checking containment against.
+ */
+function resolveLocation(target, depth = 0) {
+    if (depth > 40)
+        throw new Error(`symlink chain at "${target}" is too long to resolve`);
+    let probe = target;
+    const tail = [];
+    while (!nameExists(probe)) {
+        tail.unshift(path.basename(probe));
+        const parent = path.dirname(probe);
+        if (parent === probe)
+            break; // reached the filesystem root
+        probe = parent;
+    }
+    let probeReal;
+    try {
+        probeReal = realpathSync(probe);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        // The name is there but `realpath` cannot finish it: a symlink with a
+        // missing target. `readlinkSync` throws EINVAL on anything else, which
+        // fails closed.
+        const link = readlinkSync(probe);
+        // A RELATIVE target resolves against the directory that actually CONTAINS
+        // the link, which is not the link's lexical parent when that parent is
+        // itself reached through a symlink. `<root>/dirlink/x -> ../y` with
+        // `dirlink` pointing out of the root really lands at `<elsewhere>/y`, but
+        // measured from the lexical parent it reads as `<root>/y` — an in-root
+        // path the caller's path does not lead to. So the parent is made real
+        // first. An absolute target ignores the base.
+        const base = realpathSync(path.dirname(probe));
+        probeReal = resolveLocation(path.resolve(base, link), depth + 1);
+    }
+    return tail.length > 0 ? path.join(probeReal, ...tail) : probeReal;
+}
+export function resolveSafe(toolName, rel, root = workspaceRoot()) {
+    const rootResolved = path.resolve(root);
+    const abs = path.resolve(rootResolved, rel);
+    // 1) Lexical containment — rejects `..` and absolute escapes. The trailing
+    //    separator avoids the `/root` vs `/root-sibling` prefix pitfall.
+    if (abs !== rootResolved && !abs.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new ToolPermissionError(toolName, rel);
+    }
+    let real;
+    try {
+        const rootReal = realpathSync(rootResolved);
+        real = resolveLocation(abs);
+        // 2) Symlink-aware containment. The real path must land inside the real
+        //    root, so an in-workspace symlink pointing at /etc is refused here.
+        if (real !== rootReal && !real.startsWith(`${rootReal}${path.sep}`)) {
+            throw new ToolPermissionError(toolName, rel);
+        }
+    }
+    catch (err) {
+        if (err instanceof ToolPermissionError)
+            throw err;
+        throw new ToolPermissionError(toolName, rel);
+    }
+    return {
+        abs,
+        real,
+        given: rel,
+        rel: toPosix(path.relative(rootResolved, abs)),
+    };
+}
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export function toPosix(p) {
+    return path.sep === "/" ? p : p.split(path.sep).join("/");
+}
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export function isInside(parent, candidate) {
+    const p = path.resolve(parent);
+    const c = path.resolve(candidate);
+    return c === p || c.startsWith(`${p}${path.sep}`);
+}
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export function archiveEntryEscapes(name) {
+    const normalized = name.replace(/\\/g, "/");
+    if (normalized.startsWith("/"))
+        return true;
+    if (/^[A-Za-z]:/.test(normalized))
+        return true;
+    return normalized.split("/").some((segment) => segment === "..");
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@crewhaus/tool-money",
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Deterministic money tools: payment identifier checksums, tax, refund allocation, three-way match, cost basis, spend controls and statement parsing",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.7.0",
+    "@crewhaus/tool-builder": "0.7.0",
+    "@crewhaus/tool-catalog": "0.7.0",
+    "@crewhaus/tool-schema": "0.7.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@crewhaus/tool-executor": "workspace:*"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-money"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-money#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+}