@zeph-to/cli 1.27.1 → 2.1.0

package/README.md

@@ -45,9 +45,11 @@ binary.
 
 Once installed, the hooks fire in **every** session of each configured
 agent — `zeph cc` is the phone-control bridge, not the notification
-switch. Turn the volume down without uninstalling: `/zeph-quiet --global`
-(blockers only, all projects), `/zeph-mute` (silence, current project),
-`/zeph-status` (what's in effect). See [Mute & push mode](#mute--push-mode).
+switch. In Claude Code the routine per-turn push starts off (`quiet` is
+the default); `/zeph-normal` turns it on for a project, `/zeph-loud`
+pushes on every turn, `/zeph-mute` silences a project entirely, and
+`/zeph-status` shows what's in effect. See
+[Mute & push mode](#mute--push-mode).
 
 `~/.zeph/config.json` is the single source of truth — the CLI, the MCP
 server, the plugin hooks, and the listener all read it. You never need
@@ -424,6 +426,7 @@ zeph notify --title "Hello" --json
 | `--device <id>` | Target device ID |
 | `--session <id>` | AI session ID so the push threads into that session's chat (or `ZEPH_SESSION_ID` env) |
 | `--auto` | Apply the push gate before sending — honors the `/zeph-quiet` / `/zeph-loud` push-mode dial, per project or machine-wide (`--global`); gated-out exits silently with code 0 |
+| `--pushmode-default <m>` | Mode `--auto` assumes when the project has no dial: `quiet` (built-in), `normal`, `loud`. A dial the user set always wins |
 | `--marker <m>` | Push Signal marker for `--auto`: `skip`, `push`, `high` |
 | `--tools <n>`, `--nonreadonly <n>` | Turn tool counts feeding `--auto`'s heuristic (defaults assume real work) |
 
@@ -491,13 +494,25 @@ this order — first hit wins:
 |-------|------|--------|
 | 1 | `$STATE_DIR/pushmode-<hash>` | `/zeph-quiet` · `/zeph-loud` · `/zeph-normal` |
 | 2 | `/tmp/zeph-pushmode-<hash>` | older versions (honored only when you own the file) |
-| 3 | `$STATE_DIR/pushmode-default` | `/zeph-quiet --global` — the machine-wide default |
-| 4 | *(none)* | `normal` |
-
-So `/zeph-quiet --global` quiets every project that has no dial of its
-own, and a per-project dial always overrides it. Mute has no `-default`
-form on purpose: it is keyed on presence, not content, so a global mute
-could never be lifted for a single project.
+| 3 | `$STATE_DIR/pushmode-default` | the `--global` form of any dial — the machine-wide default |
+| 4 | `--pushmode-default <mode>` | the calling hook (the installed ones pass `normal`) |
+| 5 | *(nothing above)* | `quiet` |
+
+**Row 5 changed**: an install with no dial anywhere used to be `normal`.
+It is now `quiet`, so upgrading turns the routine per-turn push off until
+you run `/zeph-normal`. Row 4 is why the hooks this CLI installs are
+unaffected: they name `normal` themselves, since a hook that supplies no
+turn counts also supplies no `high` marker, and `quiet` would make it
+permanently silent rather than merely quieter. Row 4 sits *below* the
+state files on purpose — the flag names a default, it does not override a
+dial the user set.
+
+A dial file that exists but reads empty resolves to `normal`, not to row
+5: an empty file is a failed write, and resolving breakage to silence
+leaves no symptom to debug.
+
+Mute has no `-default` form on purpose: it is keyed on presence, not
+content, so a global mute could never be lifted for a single project.
 
 Legacy `/tmp/zeph-muted-<hash>` files are still honored when owned by the
 current user (the state dir moved out of world-writable `/tmp`).
@@ -604,25 +619,40 @@ session.
 
 ## Encryption
 
-Push bodies are encrypted with AES-256-GCM. The wrapping key is derived
-via ECDH P-256 and synced across your own devices on first run so every
-device can read the same push. Toggle encryption in the Zeph app
-(Settings → Encryption); when disabled, the CLI sends plaintext. No
-configuration needed.
-
-**Threat model honesty:** keys are persisted on the Zeph backend to
-enable cross-device sync, so this is *device-shared* encryption — not
-true end-to-end. It protects push contents from passive network
-observers and from a leaked database snapshot taken without the key
-store, but it does **not** protect against the Zeph backend itself (it
-has the keys it serves to your devices). A true E2E mode (per-device
-keypairs, server stores only public keys, no key escrow) is on the
-roadmap.
-
-The `zeph listener` ignores `isEncrypted` pushes for now — it has no
-per-device key to decrypt them. Stop-hook auto-pushes and `zeph_ask`
-responses are not part of the `@<session>` injection path, so this
-doesn't affect normal use.
+Push bodies and long-body attachments are encrypted with AES-256-GCM.
+This host holds its own ECDH P-256 keypair in `~/.zeph/device-keys.json`
+— generated on first use, and the private half never leaves the machine.
+Each push is encrypted once, and its AES key is wrapped separately for
+every device on your account using ECDH against that device's public
+key.
+
+Toggle encryption in the Zeph app (Settings → Encryption); when it is
+off, the CLI sends plaintext. No configuration needed.
+
+**Threat model:** against a passive backend — a leaked snapshot, an
+operator reading the table — the stored ciphertext and wrapped keys are
+useless, so push contents stay private. Three limits worth knowing:
+
+- **No protection from an active malicious operator.** Recipient public
+  keys come from `GET /devices` on that same server, unsigned and
+  unpinned. A backend that injects a device record carrying its own key
+  gets the message key wrapped for it, and reads everything. Closing
+  this needs out-of-band device verification (ADR-0007 Phase 4, not
+  built).
+- **No forward secrecy.** The ECDH secret for a given sender/device pair
+  is static, so compromising either private key opens every past push
+  wrapped for that pair.
+- **`senderPublicKey` is unsigned**, so a swapped one makes a push
+  undecryptable — that direction fails closed rather than leaking.
+
+A device that has not registered a per-device public key cannot be sent
+to; it is skipped, and if no device qualifies the push goes out in the
+clear rather than arriving as something nothing can open.
+
+The `zeph listener` ignores `isEncrypted` pushes for now — it does not
+try to decrypt them. Stop-hook auto-pushes and `zeph_ask` responses are
+not part of the `@<session>` injection path, so this doesn't affect
+normal use.
 
 ## Requirements
 

package/dist/cli.js

@@ -96,6 +96,10 @@ Notify options:
   --session <id>     AI session ID (or set ZEPH_SESSION_ID env)
   --auto             Apply the push gate before sending (honors the
                      /zeph-quiet | /zeph-loud dial; silent exit when gated)
+  --pushmode-default <m>
+                     Mode --auto assumes when the project has no dial
+                     (quiet|normal|loud) [default: quiet]. A dial set with
+                     /zeph-quiet | /zeph-loud | /zeph-normal always wins
   --marker <m>       Push Signal marker for --auto (skip|push|high)
   --tools <n>        Turn tool count for --auto [default: assume real work]
   --nonreadonly <n>  Non-read-only tool count for --auto
@@ -254,13 +258,14 @@ const handleNotify = async (args) => {
     // GATE_DEFAULTS ("assume real work") so dumb hooks keep their historical
     // always-push behavior in normal mode, while the /zeph-quiet | /zeph-loud
     // dial now works for every hook-driven agent. Gated-out → silent success.
+    // With no dial the mode falls back to --pushmode-default, then to quiet.
     if (args.auto === true) {
         const verdict = (0, gate_js_1.decidePush)({
             toolCount: gateCount(args.tools, gate_js_1.GATE_DEFAULTS.toolCount),
             nonReadonlyCount: gateCount(args.nonreadonly, gate_js_1.GATE_DEFAULTS.nonReadonlyCount),
             alreadyAsked: gate_js_1.GATE_DEFAULTS.alreadyAsked,
             marker: (0, gate_js_1.normalizeMarker)(typeof args.marker === 'string' ? args.marker : undefined),
-            pushMode: (0, gate_js_1.readPushMode)(projectDir),
+            pushMode: (0, gate_js_1.autoPushMode)(projectDir, args[gate_js_1.PUSHMODE_DEFAULT_FLAG]),
         });
         if (!verdict.push)
             return 0;

package/dist/crypto.d.ts

@@ -1,31 +1,31 @@
 /**
- * Device-shared encryption for Hook SDK — self-contained ECDH P-256 +
+ * Per-device encryption for the Hook SDK — self-contained ECDH P-256 +
  * AES-256-GCM. Mirrors @zeph/crypto API but bundled inline (no external
  * dependency). Uses Web Crypto API via node:crypto webcrypto — Node.js 18+
  * (the `crypto` global only exists unflagged from Node 19, so we import it).
  *
- * Threat model honesty (do not call this "E2E" without a footnote):
+ * How it works (ADR-0007):
  *
- *   The Zeph backend persists the per-user private key in plaintext so it
- *   can be synced down to a fresh device (fetchServerKeys / uploadServerKeys
- *   below). That means the backend can decrypt any push body — this is NOT
- *   end-to-end in the standard sense. What it gives you is:
- *     • Protection against passive network observers
- *     • Protection against a leaked DB snapshot taken without the key store
- *     • Cross-device readability (all your devices share one keypair)
- *   What it does NOT give you:
- *     • Protection against the Zeph backend itself
- *     • Forward secrecy — encryptPushBodyForSelf / encryptFileForSelf do
- *       ECDH(self, self), which collapses to a static derived key. A single
- *       device compromise (since all your devices share the same keypair)
- *       lets the attacker decrypt every past push for which they have the
- *       ciphertext. The per-message AES key is random, but its wrap key is
- *       static, so wrapped keys are decryptable forever.
+ *   This host holds its own ECDH keypair in ~/.zeph/device-keys.json. The
+ *   private half is generated here and never leaves — the server only ever
+ *   sees public keys. A push is encrypted once with a random AES key, and
+ *   that key is wrapped separately for each of the user's registered devices
+ *   using ECDH(this host, that device). Same keypair the stream frames below
+ *   already used; push and file bodies now share it.
  *
- *   True E2E would require a per-device keypair (server stores only public
- *   keys; senders wrap the message key once per recipient device public
- *   key). That refactor is on the roadmap; until then, treat push bodies as
- *   sensitive-but-not-secret.
+ * What it does not give you:
+ *   • Forward secrecy — the ECDH secret for a given (sender, device) pair is
+ *     static, so a compromise of either private key retroactively opens every
+ *     push wrapped for that pair.
+ *   • Authenticity beyond the key pairing — nothing signs `senderPublicKey`.
+ *
+ * Superseded scheme: a single account-wide keypair whose private half the
+ * backend escrowed so it could sync to new devices. Key escrow was removed
+ * server-side (zeph@8a6d21b) and `GET /users/me/keys` has returned a public
+ * key only ever since. This client used to react by generating a fresh
+ * account keypair and PUTting it back — which overwrote the account public
+ * key and encrypted to a key no device held. Both that upload path and the
+ * account keypair are gone.
  */
 interface EncryptedPayload {
     ciphertext: string;
@@ -34,12 +34,40 @@ interface EncryptedPayload {
     keyIv: string;
 }
 /**
- * Initialize crypto: sync keys with server, then fallback to local/generate.
- * Server is source of truth for per-user key pair.
- * Safe to call concurrently — deduplicates to single init.
- * Returns the exported public key (Base64 SPKI).
+ * Initialize push/file encryption.
+ *
+ * Encryption turns on only when the account has explicitly opted in —
+ * `encryptionEnabled` from `GET /users/me/keys` is the single authoritative
+ * signal (ADR-0008). Server unreachable or flag off leaves it off and every
+ * send goes out in the clear.
+ *
+ * When it is on, this delegates to the per-device keypair: nothing is asked
+ * of the server but the flag, and nothing is ever uploaded.
+ *
+ * Safe to call concurrently — deduplicates to a single init.
+ * Returns this host's public key when encryption is active, '' otherwise.
  */
 export declare const initCrypto: (apiKey?: string, baseUrl?: string) => Promise<string>;
+/** One target device, as returned by `GET /devices`. */
+export interface DeviceRecipient {
+    deviceId: string;
+    /** Base64 SPKI of that device's per-device public key. */
+    publicKey: string;
+}
+/** deviceId → JSON `{ encryptedKey, keyIv }`, the wire shape the clients parse. */
+export type DeviceKeyMap = Record<string, string>;
+/**
+ * Keep only devices this host can actually encrypt for.
+ *
+ * A device without a public key has never run a build that registers one, and
+ * a device still advertising the account-wide key has not migrated to
+ * per-device E2E — wrapping for either produces a push it cannot open, which
+ * is worse than sending plaintext it can read.
+ */
+export declare const selectRecipients: (devices: {
+    deviceId: string;
+    publicKey?: string;
+}[]) => DeviceRecipient[];
 export declare const getKeyPair: () => CryptoKeyPair | null;
 export declare const getPublicKey: () => string | null;
 /**
@@ -55,48 +83,29 @@ export declare const getPublicKey: () => string | null;
  */
 export declare const disableCrypto: () => void;
 /**
- * Encrypt push body for a recipient.
- * Returns fields ready to merge into the sendPush payload.
- */
-export declare const encryptPushBody: (input: {
-    title?: string;
-    body?: string;
-    url?: string;
-}, recipientPublicKeyRaw: string) => Promise<{
-    body: string;
-    encryptedKey: string;
-    senderPublicKey: string;
-    isEncrypted: true;
-}>;
-/**
- * Encrypt push body for self (all own devices).
+ * Encrypt a push body for the given recipient devices.
+ *
+ * Returns the wire fields the API expects: `body` carries the ciphertext and
+ * IV, `deviceKeyMap` the per-device wrapped keys, `senderPublicKey` the half
+ * recipients need to derive the same secret back.
  */
-export declare const encryptPushBodyForSelf: (input: {
+export declare const encryptPushBodyForDevices: (input: {
     title?: string;
     body?: string;
     url?: string;
-}) => Promise<{
+}, recipients: DeviceRecipient[]) => Promise<{
     body: string;
-    encryptedKey: string;
+    deviceKeyMap: DeviceKeyMap;
     senderPublicKey: string;
     isEncrypted: true;
 }>;
 /**
- * Encrypt file content for a recipient.
- * Returns encrypted buffer + key material for file attachment metadata.
+ * Encrypt file content for the given recipient devices.
  */
-export declare const encryptFileForRecipient: (content: string, recipientPublicKeyRaw: string) => Promise<{
+export declare const encryptFileForDevices: (content: string | Buffer, recipients: DeviceRecipient[]) => Promise<{
     ciphertext: Buffer;
     iv: string;
-    encryptedKey: string;
-}>;
-/**
- * Encrypt file content for self (all own devices).
- */
-export declare const encryptFileForSelf: (content: string) => Promise<{
-    ciphertext: Buffer;
-    iv: string;
-    encryptedKey: string;
+    deviceKeyMap: DeviceKeyMap;
 }>;
 /**
  * Flat ephemeral envelope — field-for-field what the web's decrypt()
@@ -118,5 +127,21 @@ export declare const getDevicePublicKey: () => string | null;
  * device. Requires initDeviceCrypto() to have completed.
  */
 export declare const encryptEphemeral: (plaintext: string, recipientPublicKeyRaw: string) => Promise<EncryptedEphemeralPayload>;
+/**
+ * Open an ephemeral envelope addressed to this device — the exact inverse of
+ * encryptEphemeral, and of the web's `encrypt` from @zeph/crypto, which
+ * produces the same five fields.
+ *
+ * Rejects rather than returning null: AES-GCM is authenticated, so a throw
+ * here means the envelope was sealed for another key, tampered with, or is not
+ * an envelope at all. Callers must treat every rejection as a refusal — there
+ * is no partial result to fall back on. Requires initDeviceCrypto().
+ *
+ * Note that opening an envelope proves only that its sender holds the private
+ * half of `senderPublicKey`; nothing signs that field, so it authenticates the
+ * key pairing and not the sender. A caller that needs to know *which* peer
+ * sent this must compare `senderPublicKey` against a key it already trusts.
+ */
+export declare const decryptEphemeral: (payload: EncryptedEphemeralPayload) => Promise<string>;
 export {};
 //# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AA+EH,UAAU,gBAAgB;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AA6ED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAsE5E,CAAC;AA2CF,eAAO,MAAM,UAAU,QAAO,aAAa,GAAG,IAAqB,CAAC;AACpE,eAAO,MAAM,YAAY,QAAO,MAAM,GAAG,IAA+B,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,QAAO,IAIhC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,uBAAuB,MAAM,KAC5B,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAeA,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,KACrD,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAaA,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,EACf,uBAAuB,MAAM,KAC5B,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CASlE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,MAAM,KACd,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAQlE,CAAC;AAWF;;;;GAIG;AACH,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IACjE,eAAe,EAAE,MAAM,CAAC;CACzB;AAsBD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAO,OAAO,CAAC,MAAM,CAoBjD,CAAC;AAEF,eAAO,MAAM,kBAAkB,QAAO,MAAM,GAAG,IAA+B,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,WAAW,MAAM,EACjB,uBAAuB,MAAM,KAC5B,OAAO,CAAC,yBAAyB,CAKnC,CAAC"}
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AA+EH,UAAU,gBAAgB;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAsED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAyB5E,CAAC;AAsCF,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,mFAAmF;AACnF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElD;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAC3B,SAAS;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,KAClD,eAAe,EAG8C,CAAC;AA2CjE,eAAO,MAAM,UAAU,QAAO,aAAa,GAAG,IAAkD,CAAC;AACjG,eAAO,MAAM,YAAY,QAAO,MAAM,GAAG,IAA4D,CAAC;AAEtG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,QAAO,IAEhC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACpC,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,YAAY,eAAe,EAAE,KAC5B,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,YAAY,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAkBA,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAChC,SAAS,MAAM,GAAG,MAAM,EACxB,YAAY,eAAe,EAAE,KAC5B,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,YAAY,CAAA;CAAE,CAsBxE,CAAC;AAcF;;;;GAIG;AACH,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IACjE,eAAe,EAAE,MAAM,CAAC;CACzB;AAsBD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAO,OAAO,CAAC,MAAM,CAoBjD,CAAC;AAEF,eAAO,MAAM,kBAAkB,QAAO,MAAM,GAAG,IAA+B,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,WAAW,MAAM,EACjB,uBAAuB,MAAM,KAC5B,OAAO,CAAC,yBAAyB,CAKnC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,GAC3B,SAAS,yBAAyB,KACjC,OAAO,CAAC,MAAM,CAIhB,CAAC"}