# Sharing trained adapters

Three ways to move a `.dlm.pack` between machines:

| Channel | When to use | Auth story |
|---|---|---|
| **HuggingFace Hub** | Sharing with the world; persistent discoverability | Needs an HF account + write token; personal namespaces need no approval |
| **Generic URL** | Uploading to your own server (S3, nginx, private bucket) | Optional `$DLM_SHARE_AUTH` header; you control the endpoint |
| **Peer LAN** | Sending to a teammate on the same network; air-gapped labs | HMAC token, expires in 15 min, no accounts |

All three produce the same artifact: a `.dlm.pack` the receiver
unpacks via `dlm pull`. Pick the channel that matches your threat model
and network.

## Channel 1 — HuggingFace Hub

```bash
# Personal namespace: no approval required.
dlm push mydoc.dlm --to hf:myusername/my-adapter

# Output:
# pushed: hf:myusername/my-adapter (45.32 MB)
# install: dlm pull hf:myusername/my-adapter
```

Behind the scenes `dlm push`:
1. Auto-packs `mydoc.dlm` → `mydoc.dlm.pack` in a temp dir.
2. Creates the HF repo (idempotent — existing repo is reused).
3. Uploads `adapter.dlm.pack` + autogenerated `README.md`.
4. Tags `library_name: dlm` so HF filters surface the repo.

**Auth:** HF Hub reads your token from `$HF_TOKEN` or
`~/.cache/huggingface/token`. Run `huggingface-cli login` once if you
haven't. The token is a write token from your own account — you're
pushing to YOUR namespace, not claiming membership in an organization.

**On the other machine:**
```bash
dlm pull hf:myusername/my-adapter
# pulled: hf:myusername/my-adapter → ./my-adapter.dlm (45.32 MB)
# unsigned (sha256 integrity still validated)

dlm prompt ./my-adapter.dlm "What's in this document?"
```

## Channel 2 — Generic URL endpoint

For anything that accepts an HTTPS POST with a binary body — S3
signed URL, your own nginx, an API gateway, whatever.

```bash
# Optional bearer auth:
export DLM_SHARE_AUTH="Bearer $MY_API_TOKEN"

dlm push mydoc.dlm --to https://uploads.example.com/mydoc.dlm.pack
```

The receiver:
```bash
dlm pull https://uploads.example.com/mydoc.dlm.pack
```

If your endpoint needs a different auth header (Basic, custom), set
`DLM_SHARE_AUTH` to the full header value — `dlm` copies it verbatim
into the `Authorization:` header on both push and pull.

`http://` (plaintext) works but logs a warning — use HTTPS when you
can.

## Channel 3 — Peer LAN

You want to hand a `.dlm.pack` to your coworker sitting across the
hallway, without going through the cloud.

**Machine A:**
```bash
dlm serve ~/mydoc.dlm

# serving: mydoc.dlm (dlm_id 01HZ...) on http://127.0.0.1:7337/01HZ...
# peer URL: peer://192.168.1.42:7337/01HZ...?token=pDzfz1QwRFVUq...
# token valid for 15 min. Ctrl-C to stop.
```

**Machine B:**
```bash
dlm pull peer://192.168.1.42:7337/01HZ...?token=pDzfz1QwRFVUq...
```

### Peer security posture

- **Bind default is `127.0.0.1`** (loopback only). Going LAN-public
  needs both `--public` AND `--i-know-this-is-public`:
  ```bash
  dlm serve mydoc.dlm --public --i-know-this-is-public
  ```
  Passing just `--public` without the confirmation flag logs a
  refusal and binds loopback — safer default.
- **HMAC tokens.** The token in the URL is `HMAC-SHA256(secret,
  dlm_id || expiry || nonce)` where `secret` lives only in the
  serving process's memory. Ctrl-C kills the process and every
  outstanding token becomes unverifiable instantly — no persistent
  key to revoke.
- **Rate limits.** Default caps: 4 concurrent connections, 30
  requests per minute per token. Violations return HTTP 429. Tune
  via `--max-concurrency` and `--rate-limit`.
- **Token lifetime.** Default 15 min. Tune via
  `--token-ttl-minutes` if your pack is large enough that the pull
  might cross the boundary.
- **Connection logs only.** Metadata (IP, timestamp, status) goes
  to stdout. Pack content bytes never hit the log stream.

**Never use `--public` on a coffee-shop wifi.** It binds `0.0.0.0`
and publishes your pack to every machine on that network until you
Ctrl-C the server. Use a LAN you control.

## Optional signing with minisign

If you have [`minisign`](https://jedisct1.github.io/minisign/)
installed (`brew install minisign` on macOS), you can sign packs so
receivers with your public key get a `verified` marker.

**One-time setup (sender):**
```bash
minisign -G -s ~/.dlm/minisign.key
# Generates a keypair at ~/.dlm/minisign.key (secret) and
# ~/.dlm/minisign.key.pub (public). Prompt for passphrase.
```

**Distribute your public key** (`~/.dlm/minisign.key.pub`) to
receivers by any trusted channel — email it, commit to a repo,
whatever. It's safe to share.

**Sender (every push):**
```bash
dlm push mydoc.dlm --to hf:myusername/my-adapter --sign
# minisign prompts for passphrase, produces <pack>.minisig sidecar,
# uploads both.
```

**Receiver (one-time setup):**
```bash
mkdir -p ~/.dlm/trusted-keys
cp /path/to/senders-key.pub ~/.dlm/trusted-keys/alice.pub
```

**Receiver (every pull):**
```bash
dlm pull hf:myusername/my-adapter
# pulled: hf:... → ./my-adapter.dlm (45.32 MB)
# verified: signature matches /Users/you/.dlm/trusted-keys/alice.pub
```

**What the trust states mean:**
- `verified` — signature present, matched a key in your trusted-keys
  dir. Strongest possible guarantee.
- `unverified` — signature present but no key matched (or no keys
  configured, or `minisign` not installed). Pack is still installed;
  sha256 checksums are still validated. Only the sender-identity
  claim is uncorroborated.
- `unsigned` — no signature. Fine for casual sharing. Rely on
  channel-level trust (HF account, URL TLS, peer LAN).

## Licensing and non-redistributable bases

`dlm push` refuses to upload a pack that bundles a non-redistributable
base model (Llama 3.2, etc.) unless you acknowledge you've accepted
the base's license in your target channel:

```bash
dlm push mydoc.dlm --to hf:myuser/my-llama-adapter \
    --include-base \
    --i-am-the-licensee https://huggingface.co/meta-llama/Llama-3.2-3B
```

If you didn't `--include-base`, the pack carries only the LoRA
adapter (a few MB) and the receiver supplies their own base — no
licensing friction on the share path. This is the default and
typically what you want.

## Pulling from a local path

If someone hands you a `.dlm.pack` on a USB drive:

```bash
dlm pull /Volumes/usb/mydoc.dlm.pack --out ~/Documents/
```

Same sha256 verification, same signature detection, zero network.