Security

How Syphon ensures packages are authentic, credentials don't leak, and access is controlled.

Package signing

Every package published to Syphon is signed with an ed25519 key unique to the publisher's account. The signing key lives on the publisher's machine and never leaves it. The public half is registered with the registry when you run syphon login.

When you publish, the CLI:

1. Creates the tarball in memory.
2. Signs the raw bytes with your ed25519 private key, producing a 64-byte signature.
3. Encodes the signature as base64 and includes it in the upload payload alongside the tarball's SHA-256 checksum.

When you install, the CLI:

1. Downloads the tarball and the signature from the registry.
2. Fetches the author's public key from the registry.
3. Verifies the signature locally — if it doesn't match, install fails before anything is written to disk.

Managing your key

Your signing key is stored at ~/.syphon/keys/signing.key (a 32-byte hex seed). Back it up somewhere safe — if you lose it you'll need to rotate.

# login creates a local signing key and registers its public half
$ syphon login
# use syphon logout/login after rotating ~/.syphon/keys/signing.key

Verifying installs

Re-run signature verification on any installed package at any time:

$ syphon verify github-tools
# ✓ github-tools@1.0.0  signature valid  (Misbah · a3f8b2c1)

This reads the cached tarball from the install directory and checks it against the author's current public key in the registry. If the tarball was modified on disk after install, verification fails.

Secret scanning

Before packing or publishing, Syphon scans every file that would be included in the tarball for credentials. Hard-block patterns stop the operation immediately; soft-block patterns print a warning.

To exclude a file from scanning (and from the tarball), add it to .syphonignore.

API tokens

Interactive sessions use a bearer token saved by syphon login. For CI/CD, create a scoped API token instead:

$ syphon token create --name ci-deploy --expires 90 --scope publish
# syph_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Store this in your CI secrets — it will not be shown again.

Set the SYPHON_TOKEN environment variable to authenticate the CLI non-interactively. API tokens can be revoked at any time:

$ syphon token revoke tok_abc123

The registry stores only the SHA-256 hash of the token — the plain-text value is never persisted server-side.

Advisories

The registry maintains a security advisory database. Run syphon auditto check all installed packages:

$ syphon audit
# Checking 3 packages against advisory database…
# ✓ No vulnerabilities found
$ 
# or with a vulnerability:
# ✗ github-tools@1.0.0  CVE-2026-1234  HIGH
#   fix: syphon upgrade github-tools

Rate limits

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header (seconds until the window resets) and a X-RateLimit-Reset header (Unix timestamp).