pirate-spaces-publisher

README

Pirate Spaces Publisher

Owner-side CLI for publishing native Spaces website records to Spaces Fabric.

What You Need

• Go 1.25 or newer.
• A local Spaces wallet export JSON file.
• The publish command generated by Pirate.

If go version prints command not found, install Go from https://go.dev/dl/ and reopen your terminal.

The wallet export produced by space-cli exportwallet contains private xprv material. Treat it like the wallet itself:

• Keep the wallet export on your own computer.
• Do not paste it into Pirate.
• Do not upload it to a server.
• Do not share screenshots that include the wallet export path if the path itself is sensitive.

Pirate Web Flow

The Pirate site should generate a command like this:

go run github.com/pirate-social-club/pirate-spaces-publisher@v0.1.5 publish '@your-space' \
  --wallet-export '/full/path/to/your-wallet-export.json' \
  --web 'https://pirate.sc/c/@your-space' \
  --freedom 'https://pirate.sc/c/@your-space' \
  --txt 'pirate-verify=pirate-space-verify=nvs_example:nonce' \
  --signed-message-out '/full/path/to/@your-space-sequence-1.fabric-message'

Paste it into a terminal on the computer that has the wallet export.

Tips for nontechnical users:

• The wallet export path must point to the real JSON file.
• If the path contains spaces, keep the quotes around it.
• On macOS, you can drag the JSON file into Terminal to paste its full path.
• The output JSON is okay to share. The wallet export file is not.

Manual Git Flow

Use this if you prefer to clone the repository:

git clone https://github.com/pirate-social-club/pirate-spaces-publisher.git
cd pirate-spaces-publisher

go run . publish '@your-space' \
  --wallet-export '/full/path/to/your-wallet-export.json' \
  --web 'https://pirate.sc/c/@your-space' \
  --freedom 'https://pirate.sc/c/@your-space' \
  --txt 'pirate-verify=pirate-space-verify=nvs_example:nonce' \
  --signed-message-out '/full/path/to/@your-space-sequence-1.fabric-message'

Dry run first if you want to verify the wallet match without publishing:

go run . publish '@your-space' \
  --wallet-export '/full/path/to/your-wallet-export.json' \
  --web 'https://pirate.sc/c/@your-space' \
  --txt 'pirate-verify=pirate-space-verify=nvs_example:nonce' \
  --dry-run

Records

• Txt("web", ["https://example.com/"]) is the canonical website target.
• Txt("freedom", ["https://example/"]) is the Freedom-native override.
• Txt("pirate-verify", ["pirate-space-verify=<session>:<nonce>"]) is the Pirate session challenge.

publish and clear now print signer metadata when using a wallet export:

• auth_mode
• matched_index
• matched_pubkey
• descriptor_path
• wallet_label
• wallet_blockheight

Advanced fallback:

• --secret-key expects the already tap-tweaked 32-byte BIP-340 secret key.
• It does not accept an xprv or untweaked child key.

Retention and rebroadcast

Use --signed-message-out on every non-dry-run publish or clear. The CLI creates the file exclusively with mode 0600 before attempting relay broadcast and refuses to overwrite an existing archive. The output reports the message SHA-256 so an operator can inventory immutable copies without inspecting their contents. If broadcast fails after signing, the archive remains available for retry.

The retained message contains the exact public, signed Fabric publication—not wallet private material. It can therefore be copied to a rebroadcast host without moving the wallet export:

spaces-publisher rebroadcast \
  --message-file '/full/path/to/@your-space-sequence-1.fabric-message' \
  --seeds 'https://relay-cosmos.spacesprotocol.org,https://relay-atlas.spacesprotocol.org'

rebroadcast rejects missing, non-regular, empty, oversized, or structurally invalid message files. Relays still perform signature and chain validation. Retain older sequences for audit, but schedule rebroadcast only for the currently intended sequence; replaying an old valid archive can reintroduce stale state on relays that lost the newer publication.

This repository vendors the small fabric-go compatibility patch needed by the current libveritas-go API.

License

Pirate Spaces Publisher is licensed under AGPL-3.0-or-later. The release archive includes the project license notice.

Release artifacts

The on-demand prebuild workflow publishes a Linux x64 archive and SHA256SUMS from an existing, immutable tag. It builds and executes the finished artifact inside separate digest-pinned Ubuntu 22.04 containers, matching the oldest supported VPS runtime. The workflow also uses a checksum-pinned Go toolchain, commit-pinned GitHub Actions, and a reproducible Go build. It refuses to replace an existing release. Consumers must pin both the release tag and archive digest, then verify the per-binary digest after extraction.