Skip to main content

Security and compliance

Mailwoman runs inside your infrastructure. The addresses you process stay there, because there is no step in a parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. or a geocode that would move them anywhere else. This page states that precisely enough to check, and points at the artifacts your review will ask for.

What the library sends over the network​

Nothing, during a parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. or a geocode. Those calls read model weightsmodel weightsThe learned parameters of the neural classifier, shipped as ONNX files in the @mailwoman/neural-weights-* packages. Weights are locale-specific bundles that include the model, tokenizer, and a model-card.json metadata file. and gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. files from local disk and return. There is no telemetry, no analytics, no crash reporting, no version check and no usage ping in any published package, and installing Mailwoman runs no lifecycle scripts of ours — npm install fetches tarballs and stops.

Four boundaries make that statement literally true rather than roughly true:

  • RemoteResolver is opt-in and you own the endpoint. It splits parser nodes from a gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. service inside your own network, throws unless you construct it with an endpoint URL, is never a default, and is not a service we operate.
  • Building datasets downloads datasets. mailwoman gazetteer build and its siblings fetch from the US Census, Geofabrik, adresse.data.gouv.fr and the FCC. These are commands you run deliberately, at build time, separate from parsingaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates..
  • Pulling reference data downloads reference data. mailwoman data pull fetches prebuilt gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture., POIpoint of interest (POI). A named place that is not strictly an address — landmark, transit stop, venue, amenity, or franchise. Mailwoman tags these as venue and resolves them through the gazetteer. and localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. bundlesevidence bundleThe pair of retrieval-augmented input channels (street-type + locality-surface) that feed lexicon membership as soft per-token evidence alongside the text. Shipped in 6.7.0; trained natively from step 0 in the from-scratch base line. from public.sister.software — a HEADattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads. request checks the remote size, then a GET streams the file to disk. It runs only when you invoke it, and the exchange is shown line by line in Your first ten minutes.
  • The browser runtime downloads its modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.'. @mailwoman/neural/web-loader fetches modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' and data artifacts from a URL your application supplies, once. The query text stays in the page. Our hosted demo is a deployment of that runtime, and it serves those artifacts from public.sister.software and calls tiles.sister.software for coarse map centring — both of which are properties of the demo, not of the library you install.

How it is licensed​

Two options, one codebase:

  • AGPL-3.0-only. The full text and the dual-license header are in LICENSE.md. Its one condition: distribute software built on Mailwoman, or run it as a network service others use, and those users are entitled to your corresponding source under the same license.
  • A commercial license, which releases you from that condition. The reference terms are in COMMERCIAL-LICENSE.md; that document is a template rather than a grant, and the executed agreement is what binds. Rates are on Pricing.

The code license and the data license are separate questions. Ours is the code — see Data provenance below for what the reference data carries.

Software bill of materials​

We publish an SBOM for the mailwoman package in both open standards — SPDX 2.3 and CycloneDX 1.5 — generated by the built-in npm sbom command with no third-party tooling in the trust path, from the published tarball rather than the working tree — so they describe what a consumer installs, with development-only dependencies excluded.

The files are served under /sbom/ and committed to the repository. Generation is a release-time step run on demand rather than a CI job, so the newest published SBOM can trail the newest release; check the version in the filename before you scan it.

Publishing itself uses npm Trusted Publishing over GitHub OIDC, so no long-lived registry tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. exists to leak. Packages do not currently carry a sigstore provenance attestation.

Data provenance​

Every source is recorded with its license at the point it enters the pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package., the legal notices ship as THIRD_PARTY_NOTICES.md in the source distribution, and each built data artifact carries its own ATTRIBUTION.json naming the source, release and license it was built from. The catalog of sources and their terms is data licensing and provenance.

Two itemsexpectation-maximizationAn iterative algorithm that estimates model parameters when some variables are unobserved. In Mailwoman's matcher, EM learns the Fellegi-Sunter m and u parameters from unlabeled data — no training labels needed. on that page matter to a review, and we would rather you heard them from us:

  • The OpenStreetMapOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. precisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1. tier is built but not enabled in any published artifact — not on npm, not in the demo. It is share-alike, and turning it on is gated on legal review. Nothing you install today carries an ODbL obligation from it.
  • One source's license is recorded inconsistently in our own files. Who's On FirstWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. appears as CC0 in the provenance catalog and as CC-BY 4.0 in the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. package's own notes. Until that is settled, attribute Who's On FirstWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations..

Reporting a vulnerability​

Privately, by email, not as a public issue. The policy, scope and what to include are in SECURITY.md.