zas-agent 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-10-12
+
+### Added
+
+- Automatic npm release checks and separately staged updates, enabled by default.
+  Verified releases take effect on the next launch without interrupting transfers
+  or changing pairing data. Add `update`, `updates [on|off]`, the
+  `ZAS_AGENT_AUTO_UPDATE` override, and update information in `zas_status`.
+  Source checkouts stay on their working code; offline or failed checks keep the
+  current agent running.
+
+### Security
+
+- Sanitize local filenames with the pinned web rules, enforce containment, and
+  publish downloads and Directo receives without overwriting competing files (#13).
+- Migrate private keys and pairing secrets to Windows DPAPI, macOS Keychain or
+  Linux Secret Service, with an owner-only headless fallback. Check POSIX secret
+  permissions and report the storage backend in status (#14).
+- Refuse unsafe HTTP bases and emulator credential mixing, revalidate saved
+  endpoints, and reject redirects on credential-bearing requests (#15).
+- Update compatible production dependencies to pass the high-severity audit.
+- Mirror zas.web `46d727a` shared codecs and vectors: reject invalid OPRF points,
+  read v2 envelopes while retaining v1 writes, and verify server-selected VOPRF
+  against configured public-key pins. CI checks pinned shared sources (#16).
+
+## [0.10.0] - 2026-09-28
+
+### Added
+
+- Transfer telemetry. File and note sends, item downloads, and Directo sends
+  and receives (live and reliable delivery) report `transfer.started`,
+  `transfer.stage_started`, `transfer.slow` (after 30 s),
+  `transfer.phase_timing` and `transfer.finished`. Each report carries the
+  item category, the transport, byte counts, a size bucket, stage durations and
+  the outcome (success, failure or cancellation), joined by a random
+  per-attempt ID. No file name, content, path or channel name. The same
+  opt-out as `agent.tool_call` covers it. The telemetry notice names the new
+  fields.
+
+- `plan_inactive`. A send, replace or Directo transfer in an organization
+  channel whose plan is inactive now says so, and names who can reactivate
+  it. It used to arrive as `upload_failed`, which told the agent to retry.
+
+### Changed
+
+- Reports never delay or fail a tool call. The `agent.tool_call` report is
+  sent after the answer, on a later tick. Transfer events are queued, at most
+  32 per batch, and sent in one request on a later tick. A report is one
+  request with a 2 s timeout and no retry. It is skipped when there is no
+  valid session, so it never starts or refreshes a sign-in.
+
 ## [0.9.0] - 2026-09-09
 
 ### Added
@@ -333,7 +384,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   two separate identities that cannot read each other's keys.
 - Install snippets for Claude Code and Codex, printed by `zas-agent pair`.
 
-[Unreleased]: https://github.com/soke1556/zas-agent/compare/v0.9.0...HEAD
+[Unreleased]: https://github.com/soke1556/zas-agent/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/soke1556/zas-agent/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/soke1556/zas-agent/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/soke1556/zas-agent/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/soke1556/zas-agent/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/soke1556/zas-agent/compare/v0.6.3...v0.7.0

package/README.md

@@ -112,6 +112,40 @@ 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.
 
+## Updates
+
+Automatic updates are on by default in published installations. While serving,
+the agent checks npm's `latest` stable release in the background, at most once
+per day. It installs newer releases in a separate directory and verifies that
+the installed executable reports the expected version. The next agent launch
+uses that release. Restart the MCP connection (or your coding agent) to apply it;
+running transfers are never restarted by the updater. Pairing and channel grants
+stay in place, and an offline or failed update leaves the current version usable.
+
+```sh
+zas-agent updates       # show the setting and any release ready to use
+zas-agent updates off   # disable automatic downloads and staged launch selection
+zas-agent updates on    # enable them again
+zas-agent update        # check and stage a release now
+```
+
+Use `npx -y zas-agent@latest` in place of `zas-agent` if you have no global
+installation. `zas_status` also reports the running version and staged update.
+`ZAS_AGENT_AUTO_UPDATE=0` disables the built-in updater; `1` enables it, overriding
+the saved setting. An explicit `update` command can still download a release while
+updates are off, but it will not be selected until updates are enabled again.
+For a pinned installation, use an exact version in the launch command and disable
+automatic updates. The documented `npx ...@latest` command still asks npm for the
+latest package even when the built-in updater is off.
+
+Updates require npm and install the official `zas-agent` package from
+`https://registry.npmjs.org`, including its normal dependency installation scripts
+and npm integrity checks. No administrator access is needed. Staged packages live
+under `~/.zas/agent/.updates` (or `ZAS_AGENT_HOME/.updates`); old installations are
+retained and can be removed with the agent stopped. Source checkouts and prerelease
+builds do not update themselves. Existing installations need to upgrade once to a
+release containing this updater before these controls are available.
+
 ## Why you can trust it
 
 Every line here is a fact. The ones about this package you can check in this
@@ -159,8 +193,13 @@ 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
+- **No shared channel you joined, unless its owner allows it.** You can grant
+  a channel you joined, but the grant stays `grant_pending` until that
+  channel's owner allows this agent in Zas. The plan also caps how many of
+  these channels one agent holds: 2 on Free *(server-side)*.
+- **No workspace channel, unless the organization allows agents.** A channel
+  an organization manages, or one you created inside its workspace, can be
+  granted only while the organization is active and an admin turned agents on
   *(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.
@@ -196,10 +235,16 @@ string ever reaches a terminal.
 | Code | What it means |
 | --- | --- |
 | `not_paired` | This agent is not paired yet. |
+| `unsafe_endpoint` | An endpoint or emulator configuration could expose credentials. |
+| `identity_permissions` | A secret file is not private to its owner. |
+| `secret_store_failed` | The OS secret store cannot save or open this profile. |
+| `invalid_voprf_configuration` | The server-selected encryption key has no valid local pin. |
+| `invalid_voprf_proof` | The encryption service response failed verification. |
 | `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_missing` | This agent has no access to that channel. |
+| `grant_pending` | That channel belongs to somebody else, and its owner has not allowed this agent yet. |
 | `send_forbidden` | This agent cannot send to that channel. |
 | `read_forbidden` | This agent cannot read that channel. |
 | `direct_mode` | That channel is in Directo mode. |
@@ -215,6 +260,7 @@ string ever reaches a terminal.
 | `fallback_unavailable` | Reliable delivery is not available right now. |
 | `key_stale` | The channel key changed; the owner refreshes it by opening Zas. |
 | `quota_exceeded` | The account reached its storage limit. |
+| `plan_inactive` | The organization's plan is inactive, so sending to its channels is paused; the owner or a billing admin reactivates it. |
 | `rate_limited` | Too many sends in a row. |
 | `file_too_big` | The file is over the plan limit. |
 | `duplicate` | That item is already in the channel. |
@@ -228,6 +274,12 @@ string ever reaches a terminal.
 | `write_failed` | The download destination could not be written. |
 | `pairing_expired` | The pairing expired; pair again. |
 | `pairing_cancelled` | The owner cancelled the pairing. |
+| `claim_mismatch` | The code does not match. |
+| `pairing_not_approved` | Nobody has approved this pairing yet. |
+| `pairing_claimed` | This pairing was already claimed; pair again. |
+| `agent_limit` | The account cannot take another agent; the owner deletes one from Settings → Agents. |
+| `grant_limit` | The plan allows fewer channels per agent than this pairing grants. |
+| `foreign_limit` | The plan allows this agent fewer channels of other people than this pairing asks for. |
 | `feature_disabled` | Agents are not enabled for this account yet. |
 | `upload_failed` | The upload failed. |
 | `oprf_failed` | Zas did not answer correctly while preparing the file. |
@@ -306,14 +358,16 @@ covers every profile on the machine; pairing again does not reset it.
 
 What one report carries, and nothing else: the tool that ran, whether it
 worked, the closed error code when it did not, which of four duration buckets
-it fell in, and the package version. No file name, no file contents, no path,
+it fell in, and the package version. Item transfers also report item category,
+transport, byte counts, stage durations, and success/failure/cancellation, joined
+by a random per-attempt ID. No file name, no file contents, no path,
 no channel name, no error message, no stack.
 
 Where it goes: to Zas, never to an analytics service directly. This package
 holds no analytics token and opens no connection to a third party, so no
 address of yours reaches one. The report is attributed to the Zas account the
 agent is paired with, which the server reads from the session — the request
-carries no identifier of its own. Nothing is reported before pairing, because
+carries no account or content identifier. Nothing is reported before pairing, because
 until then there is no account it could belong to.
 
 A report is never allowed to matter: it is sent after the answer, waited on
@@ -329,8 +383,8 @@ Codex agent side by side without either reading the other's keys:
 | macOS, Linux | `~/.zas/agent/<profile>/` |
 | Windows | `%USERPROFILE%\.zas\agent\<profile>\` |
 
-Four files in the profile directory, all written through a temporary file and
-renamed into place, so a crash mid-write cannot leave half a file behind:
+Profile metadata is written through temporary files and renamed into place,
+so a crash mid-write cannot leave half a file behind:
 
 - `identity.json` — the agent uid, the owner uid, the name, and the two key
   pairs. Back it up like a private key, or delete it and pair again.
@@ -349,11 +403,24 @@ One more file sits next to the profiles, in `~/.zas/agent/`:
   above was last printed. It belongs to the machine, not to a profile, so one
   decision covers every agent on it.
 
-On macOS and Linux the directory is created `0700` and every file `0600`. On
-Windows those bits have no effect: the files carry the permissions of the user
-profile they live in, and the package does not try to set any others.
-
-Deleting the directory makes this machine forget the agent. It does not revoke
+Private keys, polling secrets and legacy pairing codes migrate out of the old
+JSON files on the next start. The replacement metadata is committed only after
+storage succeeds. Windows uses current-user DPAPI and an owner-only directory
+ACL without inherited grants. macOS uses Keychain; Linux uses Secret Service
+through `secret-tool` when a desktop session and that tool are available. A
+locked or failing desktop store must be unlocked or repaired before retrying.
+Headless Linux uses a `0600` file in a `0700` directory. POSIX secret reads reject
+files owned by another user, symlinks, hard links, and group/world permissions;
+the error includes the `chmod 600` repair command. `zas_status` reports the store.
+
+Older agent versions cannot read the migrated secret references; keep the
+updated agent installed after migration. OS-protected profiles are not portable backups. Pair a new profile on another
+machine; do not copy its JSON files and expect them to sign in. OS protection
+does not prevent a process already running as your user from using your keys.
+
+Deleting the directory removes the local references. Keychain/Secret Service
+entries may remain under service `red.zas.agent`; remove those with the OS
+credential manager when discarding a profile. It does not revoke
 anything: the account side is closed from the web app, under
 Settings → Agents → Revoke.
 
@@ -386,12 +453,22 @@ agent: same keys, same channels, one row.
 | `ZAS_TOKEN_BASE` | `https://zas.red/anon-token` | The challenge and token routes. |
 | `ZAS_OPRF_BASE` | `https://zas.red/oprf` | The blind key-derivation service. |
 | `ZAS_FIREBASE_PROJECT` | `zas-me` | The project whose Firestore the read path queries. |
+| `ZAS_ALLOW_INSECURE_DEV` | unset | `1` permits HTTP only on `localhost`, `127.0.0.1`, or `::1`. |
+| `ZAS_VOPRF_PUBLIC_KEYS` | unset | Operator-provided JSON mapping key IDs to pinned base64 VOPRF public keys. Required when the server selects mode 1. |
 | `ZAS_FIREBASE_API_KEY` | the public web key | The key used to exchange a custom token for a session. |
 
 Only `--profile`, `ZAS_AGENT_HOME` and the two telemetry switches are worth
 setting by hand. The rest exist
 so the package can be pointed at a test deployment.
 
+Saved API/token/OPRF bases are validated on every load. Non-loopback HTTP is
+refused even with the dev flag. To run Firebase emulators, set both
+`FIREBASE_AUTH_EMULATOR_HOST` and `FIRESTORE_EMULATOR_HOST` to loopback hosts,
+all three Zas service bases to loopback, `ZAS_FIREBASE_PROJECT` to a `demo-*`
+project, and `ZAS_ALLOW_INSECURE_DEV=1`. Production profiles cannot use these
+emulators. Credential-bearing requests refuse redirects. Use a separate
+profile for development; repair unsafe saved bases before loading an old one.
+
 ## Development
 
 ```
@@ -407,7 +484,7 @@ node dist/cli.js --version
 This repository is the public mirror of the `agent/` package of Zas's private
 monorepo. It is produced by `scripts/export-public.mjs`, which builds the
 package with esbuild and uses the build's own metafile to decide what to copy:
-`src/`, `test/`, the package files, and the nine `src/shared/*` modules the
+`src/`, `test/`, the package files, and the `src/shared/*` modules the
 agent imports. Those shared modules are the client-side crypto and format code — the
 chunker, the manifest, the envelope, the key derivation — that the Zas web app
 also ships, which is why the encryption the agent performs is the encryption the
@@ -417,6 +494,19 @@ Pull requests are welcome against this repository. The maintainer applies
 accepted changes back into the monorepo, and the next export brings them here.
 See [CONTRIBUTING.md](CONTRIBUTING.md).
 
+`shared-source.json` pins the shared modules and interoperability fixtures to
+zas.web commit `46d727a870c64728b42b768950d55d7d7a575181`. CI runs
+`npm run check:shared` to detect drift using upstream Git blob IDs. Maintainers
+with the private checkout can verify the pin against the actual commit with
+`npm run check:shared -- --source ../zas.web`. Apply these agent changes back
+to the monorepo before the next export.
+
+This release follows the web reader phase: legacy/v1 and authenticated v2
+envelopes can be read; application writers still produce v1. VOPRF mode is
+selected by `GET /v1/agents/me`; mode 1 requires a local public-key pin and a
+valid batch proof, with no downgrade on failure. Enabling production v2 writes
+and coordinating VOPRF adoption across clients remain separate rollout work.
+
 ## Security
 
 Please report vulnerabilities privately. [SECURITY.md](SECURITY.md) says how,