@mapmap/territory

Territory-in-a-file: list, fetch and cryptographically verify signed MapMap offline territory packages from an update channel: Snowdonia (or the whole UK) in signed files that are yours forever, verified on your machine.

Release status. The package is publish-ready and its release workflow (.github/workflows/publish-territory-cli.yml) is wired up, but nothing reaches npm until a territory-v* tag is pushed. Until then npx @mapmap/territory does not resolve, so run it from source instead: build once, then use node dist/cli.js list in place of every npx @mapmap/territory command below.

Every byte is authenticated on your machine, never trusted from the wire: the channel index and each package manifest carry detached ed25519 signatures, and every layer's content is checked against the BLAKE3 hashes inside the signed manifest. A hostile CDN, mirror or gateway can at worst refuse to serve you (see docs/TERRITORY-UPDATES.md in the MapMap repo for the full trust model).

Install

# No install: npx fetches it per run (needs Node 20+).
npx @mapmap/territory list

# Or keep it on PATH as `mapmap-territory`:
npm install -g @mapmap/territory
mapmap-territory list

Quickstart

# 1. A free API key, one call, no signup page (then click the emailed link,
#    territory downloads need a verified key):
curl -X POST https://api.mapmap.ai/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","accept_tos":true}'
export MAPMAP_KEY=snk_…

# 2. What territories does the channel carry?
npx @mapmap/territory list

# 3. Fetch one, verified end to end:
npx @mapmap/territory fetch uk --pubkey ./snfactory-public.hex
#   ✓ manifest signature valid
#   uk.pmtiles.tar.zst  1.1 GB downloaded
#   ✓ render/uk.pmtiles, BLAKE3 verified (1.2 GB)
#   ✓ signature valid: United Kingdom 2.0.0 is yours forever.

# 4. Any time later, fully offline:
npx @mapmap/territory verify ./uk-2.0.0 --pubkey ./snfactory-public.hex

Commands

| Command | Does | |---|---| | list | Fetches and (with --pubkey) verifies the signed channel index, then prints the territories, their latest versions and installed sizes. --json prints the raw index. | | fetch <id> | Downloads a territory's signed manifest and every layer blob with progress, then verifies: ed25519 manifest signature + BLAKE3 content hash of every layer. --out <dir> (default ./<id>-<version>), --version <v> (default latest). | | verify <path> | Offline re-verification. Point it at a fetched directory (full chain: signature + every hash) or at a single .tar.zst blob (--blake3 <hex> for the expected hash, or it reads the sibling manifest.json). |

Flags

| Flag | Env | Meaning | |---|---|---| | --key <snk_…> | MAPMAP_KEY | Gateway API key. list/fetch need one; verify is fully offline. | | --base-url <url> | MAPMAP_BASE_URL | Gateway origin. Default https://api.mapmap.ai. | | --pubkey <key> | MAPMAP_TERRITORY_PUBKEY | The publisher's ed25519 public key: 64 hex characters, an SPKI PEM, or a path to a file containing either. | | --out <dir> | | fetch output directory. | | --version <v> | | fetch a specific published version. | | --blake3 <hex> | | verify a lone blob against an explicit content hash. | | --json | | list as JSON. |

Where does the public key come from?

The publisher key is deployment-specific: each MapMap deployment signs its channel with its own factory key (snfactory keygen), and the public half is distributed out of band (a compile-time constant in apps, a value your operator hands you, never fetched from the same server that serves the data, which would defeat the purpose). Ask your operator for their 64-hex key or .pub file and pass it with --pubkey.

Without --pubkey the CLI still checks every BLAKE3 hash against the manifest and says, loudly, that the publisher signature was not checked.

Requirements

• Node 20+ to list, fetch and verify signatures and manifest hashes.
• Zstd, for full content verification. Layer blobs are zstd-compressed, so decompressing and hashing their contents needs one of: Node's built-in zstd (Node 22.15+, or 23.8+), or a zstd binary on PATH (brew install zstd / apt install zstd). With neither, the CLI refuses honestly instead of skipping verification; it never pretends a blob it could not read is verified. (The engines floor stays at Node 20 deliberately: everything except full-content verification works there, and a zstd binary covers the rest without a newer Node.)
• Territory layer downloads need a verified (free) key; provisional keys get a 403. Verified-free accounts include 8 GiB/month of offline downloads; plans raise it.

Run from source (before publish)

Until the package is on npm, build it and run the CLI directly:

npm install
npm run build             # tsup → dist/cli.js
node dist/cli.js list     # same CLI as `npx @mapmap/territory list`

Develop

npm install
npm run typecheck
npm test          # vitest; fixtures use a throwaway ed25519 key, plus a frozen signed index
npm run build     # tsup → dist/cli.js

# Opt-in smoke test against the real channel (needs a verified free key):
MAPMAP_KEY=snk_… npm run test:live

Licence

MIT © 2026 Mapmap AI Ltd. (The MapMap platform itself is separately licensed; this CLI only reads the public, signed channel format.)