zas-agent

# zas-agent

An MCP server that lets a coding agent — Claude Code, Codex, or anything that
speaks MCP — send files and notes into your [Zas](https://zas.red) channels, and
read items back out of them.

[![npm](https://img.shields.io/npm/v/zas-agent)](https://www.npmjs.com/package/zas-agent)
[![CI](https://github.com/soke1556/zas-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/soke1556/zas-agent/actions/workflows/ci.yml)
[![CodeQL](https://github.com/soke1556/zas-agent/actions/workflows/codeql.yml/badge.svg)](https://github.com/soke1556/zas-agent/actions/workflows/codeql.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/soke1556/zas-agent/badge)](https://scorecard.dev/viewer/?uri=github.com/soke1556/zas-agent)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## What is Zas

[Zas](https://zas.red) moves things between your devices and the people you
choose: files, photos, text, code. You put something into a channel on one
device and use it on another. Whatever you do not pin leaves on its own after a
few days, so there is nothing to tidy up later. Everything is encrypted on the
device before it is uploaded: the database and the object storage receive
encrypted bytes, not filenames, content or previews.

This package is the piece that lets a coding agent use your channels the way
your other devices do, under an identity of its own that you approve, that you
scope to the channels you choose, and that you can revoke.

## What it does

Your coding agent gets thirteen tools. It can send a file or a note into a channel
you picked, send or receive a file live through Directo, list what is in that
channel, pull one item back onto disk, and change what it sent: an item's
title or text, or the bytes under a file, keeping the item id.
Everything it sends is encrypted on your machine before it leaves, lands in your
account, and is marked in the channel as sent by that agent. The agent has an
identity of its own and never holds your account key: pairing mints a key pair
here, you approve it from the web app, and from then on it signs a challenge to
get a short-lived session.

## Install

Install [Node.js LTS](https://nodejs.org/en/download) (22 or newer) and your
agent's command-line tool first. Reopen your terminal after installing.
Run these commands on the computer where you use the agent.

Choose your agent and pair it. On Windows (PowerShell or CMD):

**Codex**

```
npx.cmd -y zas-agent@latest pair --profile codex
```

**Claude Code**

```
npx.cmd -y zas-agent@latest pair --profile claude-code
```

Open the printed link, approve the channels, and enter the code in the terminal
if the page shows one. Leave the terminal open until pairing finishes.
Then run the matching registration command:

**Codex**

```
cmd /d /c codex mcp add zas "--" npx.cmd -y zas-agent@latest --profile codex
```

**Claude Code**

```
cmd /d /c claude mcp add zas "--" npx.cmd -y zas-agent@latest --profile claude-code
```

On macOS, Linux, or WSL, use `npx` in place of `npx.cmd` and omit
`cmd /d /c `. Pair and register in the same environment. Restart your agent
and ask it to send something to Zas.

If a command is not recognized, install Node.js or the named agent's CLI and
reopen the terminal. The first download needs internet access and may take a
few minutes. Use `@latest` as shown so npm requests the published package
instead of selecting an unbuilt local workspace.

### What pairing does

`zas-agent pair` mints the key pair, registers the public halves, opens the
approval page in your browser, and waits. The terminal shows:

```
Open this page signed in to your Zas account:
  https://zas.red/agents/pair?p=...#port=53211
Fingerprint: 1a2b 3c4d 5e6f 7a8b
Waiting for approval… (expires in 10 minutes)
```

Signed in, name the agent and tick the channels it may use — sending is the
default, reading is a separate switch — and approve. Approval creates
nothing by itself: the page hands a one-time claim code to this terminal
over `127.0.0.1` (the port in the link), and the agent exists only once the
terminal claims with that code and the secret it holds. A link that reached
somebody else is approved on their machine, where nothing listens, and
expires with nothing created.

If the browser cannot reach the terminal — the link was opened on a phone,
or the browser refused the local connection — the page shows the code and
the terminal asks for it. Type it there and nowhere else: with that code,
another terminal that started a pairing could claim it. Pass `--no-open` or
set `ZAS_NO_OPEN=1` to keep the browser closed; the link is printed either
way. The pairing is good for ten minutes before approval and five after;
past that, run the command again.

You can also start the flow from the coding agent with the `zas_pair` tool:
the first call hands back the URL, a later call says whether the approval
landed, and if the page shows a code, a call with `code` claims with it.

## Why you can trust it

Every line here is a fact. The ones about this package you can check in this
repository. Where a property is enforced by the Zas server, which is not open
source, the sentence says so.

- **The agent has an identity of its own.** `zas-agent pair` generates two key
  pairs on your machine — X25519 to receive channel keys, P-256 to sign
  sign-ins — and the private halves never leave it. The agent never holds your
  account key, and the key-derivation service refuses account-key derivation to
  an agent *(server-side)*.
- **You approve it, and you choose the channels.** Pairing never
  auto-approves. The approval page shows the harness, the host and the key
  fingerprint, and nothing exists until the terminal that started the
  pairing claims it with a code only the approving page received
  *(server-side)*. A pairing link sent to you by someone else creates
  nothing on your account.
- **It holds one key per granted channel, and no key for any other.** Each
  grant carries that channel's key sealed to the agent's X25519 public key. A
  channel you did not grant has no key here to decrypt with, and the server
  checks the live grant on every request *(server-side)*.
- **No password and no API key.** Signing in is a signed challenge traded for a
  one-hour token. There is no password, no API key and no refresh token on
  disk: the agent re-signs from its P-256 key when the token ages out.
- **Everything it sends is visible as its work.** Every item carries the `>_`
  agent mark and the agent's name, in the channel, on every device you read Zas
  from.
- **You can revoke it at any time.** Settings → Agents → the agent → Revoke.
  The session stops, its refresh tokens are revoked *(server-side)*, and the
  next tool call answers "the owner revoked this agent". What it already sent
  stays where it is. You can also drop a single channel and keep the rest.
- **Content is encrypted on your machine before it leaves, the same way the
  app does it.** The
  chunking, the manifest and the envelope formats under `src/shared/` are the
  same modules the Zas web app ships. The server stores ciphertext and never
  sees a channel key, a channel name or item plaintext *(server-side)*.
- **The source is here, and the releases are built from it.** Every npm release
  is published by the `release.yml` workflow in this repository, with npm
  provenance, so the tarball on npm can be traced back to a commit and a
  workflow run.

## What it cannot do

The package refuses some of these on its own, before a request is made. The
ones marked *(server-side)* are enforced by the Zas server.

- **No channel you did not grant.** Not by name, not by id.
- **No shared channel you merely joined, and no workspace channel.** Grants
  exist only on channels your account owns and that no organization manages
  *(server-side)*.
- **No reading unless the grant says so.** `read` is a separate switch from
  `send`; without it, `zas_list_items` and `zas_get_item` are refused.
- **No stored sending into a view-only channel, and none into a channel in
  Directo mode.** Both are refused before a byte is uploaded. A channel in
  Directo mode takes `zas_send_direct`, a live transfer that stores nothing.
- **No changing what it did not send.** `zas_edit_item` and `zas_replace_file`
  act only on items carrying this agent's mark; anything else is `not_yours`,
  and the server refuses it too *(server-side)*. A replace is for agents only:
  no web or mobile client gets one. An item with a public share is not
  replaced until the share is removed.
- **No receiving unless the grant says read.** Receiving through Directo
  writes a file onto this machine, so `zas_receive_direct` takes the same
  `read` switch as listing. And it only ever runs inside a tool call: the
  agent never watches your channels, so nothing arrives unasked.
- **Nothing outside its allowlist.** The API refuses an agent on every route
  that is not on a short, explicit list, and Firestore rules refuse it your
  account document, your devices, and any channel without an active read grant
  *(server-side)*.
- **Rate limited by the server**, on its own buckets, with the key-derivation
  budget charged to your account so ten agents are not ten times your own
  allowance *(server-side)*.
- **As many agents as your plan or your organization allows** *(server-side)*.
- **Files up to 5 GiB**, and in practice less: the agent reads a file into
  memory to hash it, so the machine's memory is the real ceiling.

### The error vocabulary

The agent answers in a closed set of codes. Anything a server route says that
is not in this set collapses to `upload_failed` or `network`, so no raw server
string ever reaches a terminal.

| Code | What it means |
| --- | --- |
| `not_paired` | This agent is not paired yet. |
| `identity_corrupt` | The identity file on disk is damaged. |
| `agent_revoked` | The owner revoked this agent. |
| `agent_forbidden` | Only the account owner can do that. |
| `grant_mis