xnotif 0.1.0 → 0.2.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuta Kobayashi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# xnotif
+
+[![npm](https://img.shields.io/npm/v/xnotif)](https://www.npmjs.com/package/xnotif)
+[![CI](https://github.com/yutakobayashidev/xnotif/actions/workflows/ci.yml/badge.svg)](https://github.com/yutakobayashidev/xnotif/actions/workflows/ci.yml)
+
+Receive Twitter/X notifications in real-time. No API key, no scraping — just Web Push.
+
+```typescript
+import { createClient } from "xnotif";
+
+const client = createClient({
+  cookies: { auth_token: "...", ct0: "..." },
+});
+
+client.on("notification", (n) => {
+  console.log(`${n.title}: ${n.body}`);
+});
+
+await client.start();
+```
+
+## Install
+
+```bash
+npm install xnotif
+```
+
+> Requires Node.js >= 22.0.0
+
+## Notification Payload
+
+Each `notification` event delivers a `TwitterNotification` object:
+
+```jsonc
+{
+  "title": "@jack",
+  "body": "just setting up my twttr",
+  "icon": "https://pbs.twimg.com/profile_images/...",
+  "timestamp": 1142974214000,
+  "tag": "mention_12345",
+  "data": {
+    "type": "mention",
+    "uri": "https://x.com/i/web/status/20",
+    "title": "@jack",
+    "body": "just setting up my twttr",
+    "tag": "mention_12345",
+    "lang": "en",
+    "scribe_target": "mention",
+    "impression_id": "abc123",
+  },
+}
+```
+
+Top-level fields:
+
+| Field       | Type      | Description                                       |
+| ----------- | --------- | ------------------------------------------------- |
+| `title`     | `string`  | Who triggered the notification                    |
+| `body`      | `string`  | Human-readable description                        |
+| `icon`      | `string?` | Profile image URL                                 |
+| `timestamp` | `number?` | Unix epoch in milliseconds                        |
+| `tag`       | `string?` | Deduplication tag                                 |
+| `data`      | `object?` | Structured metadata (see `data.type` for routing) |
+
+## Getting Cookies
+
+1. Log in to [x.com](https://x.com)
+2. DevTools → Application → Cookies
+3. Copy `auth_token` and `ct0`
+
+## State Persistence
+
+Save the `ClientState` from the `connected` event to skip key generation on restart:
+
+```typescript
+import { createClient, type ClientState } from "xnotif";
+
+let state: ClientState | undefined = loadFromDisk(); // your persistence
+
+const client = createClient({ cookies: { auth_token: "...", ct0: "..." }, state });
+
+client.on("connected", (s) => saveToDisk(s));
+
+await client.start();
+```
+
+## API
+
+### `createClient(options)`
+
+| Option    | Type                                  | Required | Description            |
+| --------- | ------------------------------------- | -------- | ---------------------- |
+| `cookies` | `{ auth_token: string; ct0: string }` | Yes      | Session cookies        |
+| `state`   | `ClientState`                         | No       | Restore previous state |
+
+### Events
+
+| Event          | Payload               | Description                    |
+| -------------- | --------------------- | ------------------------------ |
+| `notification` | `TwitterNotification` | Decrypted notification         |
+| `connected`    | `ClientState`         | Connected — persist this state |
+| `error`        | `Error`               | Error (connection continues)   |
+| `disconnected` | —                     | WebSocket closed               |
+| `reconnecting` | `number`              | Reconnecting in N ms           |
+
+### Methods
+
+- **`client.start()`** — Connect and begin receiving notifications
+- **`client.stop()`** — Disconnect
+
+### Low-level Exports
+
+- `Decryptor` — AESGCM Web Push decryption (ECDH + HKDF + AES-128-GCM)
+- `AutopushClient` — Mozilla Autopush WebSocket client
+
+## How It Works
+
+```mermaid
+sequenceDiagram
+    participant App as xnotif
+    participant Autopush as Mozilla Autopush<br/>wss://push.services.mozilla.com
+    participant Twitter as Twitter/X
+
+    App->>App: Generate ECDH P-256 key pair + 16-byte auth secret
+    App->>Autopush: WebSocket connect (subprotocol: push-notification)
+    Autopush-->>App: hello ACK (uaid assigned)
+    App->>Autopush: Register channel with VAPID key
+    Autopush-->>App: Push Endpoint URL
+
+    App->>Twitter: POST /1.1/notifications/settings/login.json<br/>{ token: endpoint, encryption_key1: p256dh, encryption_key2: auth }
+    Twitter-->>App: 200 OK
+
+    loop Real-time notifications
+        Twitter->>Autopush: Web Push (AESGCM encrypted payload)
+        Autopush->>App: WebSocket message
+        App->>App: ECDH shared secret (256-bit)<br/>→ HKDF-SHA256 (IKM, CEK, nonce)<br/>→ AES-128-GCM decrypt<br/>→ Strip 2-byte padding
+        App-->>App: Emit "notification" event
+    end
+```
+
+1. **Key generation** — Generate an ECDH P-256 key pair and a 16-byte auth secret via `crypto.subtle` (skipped when restoring from saved `state`)
+2. **Autopush connection** — Open a WebSocket to `wss://push.services.mozilla.com` with the `push-notification` subprotocol, send a `hello` handshake, then register a channel to obtain a Push Endpoint URL
+3. **Twitter registration** — POST the Push Endpoint, base64url-encoded public key, and auth secret to Twitter's `/1.1/notifications/settings/login.json`, authenticated with your session cookies (`auth_token` / `ct0`)
+4. **Receive & decrypt** — When Twitter pushes an AESGCM-encrypted payload through Autopush, derive a shared secret via ECDH, expand it with HKDF-SHA256 into a 16-byte CEK and 12-byte nonce, then decrypt with AES-128-GCM
+5. **Emit** — Parse the decrypted JSON into a `TwitterNotification` and fire it as a `notification` event
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,114 @@
+import { EventEmitter } from "events";
+
+//#region src/types.d.ts
+interface AutopushNotification {
+  messageType: "notification";
+  channelID: string;
+  version: string;
+  data: string;
+  headers: {
+    crypto_key: string;
+    encryption: string;
+  };
+}
+interface TwitterNotification {
+  title: string;
+  body: string;
+  icon?: string;
+  timestamp?: number;
+  tag?: string;
+  data?: {
+    type?: string;
+    uri?: string;
+    title?: string;
+    body?: string;
+    tag?: string;
+    lang?: string;
+    bundle_text?: string;
+    scribe_target?: string;
+    impression_id?: string;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+interface ClientState {
+  uaid: string;
+  channelId: string;
+  endpoint: string;
+  remoteBroadcasts: Record<string, string>;
+  decryptor: {
+    jwk: JsonWebKey;
+    auth: string;
+  };
+}
+interface NotificationClientOptions {
+  cookies: {
+    auth_token: string;
+    ct0: string;
+    [key: string]: string;
+  };
+  state?: ClientState;
+}
+//#endregion
+//#region src/client.d.ts
+interface NotificationClientEvents {
+  notification: [notification: TwitterNotification];
+  connected: [state: ClientState];
+  error: [error: Error];
+  disconnected: [];
+  reconnecting: [delay: number];
+}
+declare class NotificationClient extends EventEmitter<NotificationClientEvents> {
+  private autopush;
+  private running;
+  private options;
+  constructor(options: NotificationClientOptions);
+  start(): Promise<void>;
+  stop(): void;
+}
+declare function createClient(options: NotificationClientOptions): NotificationClient;
+//#endregion
+//#region src/decrypt.d.ts
+declare class Decryptor {
+  private keyPair;
+  private publicKeyRaw;
+  private authSecret;
+  private jwk;
+  private constructor();
+  static create(jwk?: JsonWebKey, authBase64url?: string): Promise<Decryptor>;
+  getJwk(): JsonWebKey;
+  getAuthBase64url(): string;
+  getPublicKeyBase64url(): string;
+  decrypt(cryptoKeyHeader: string, encryptionHeader: string, payload: ArrayBuffer): Promise<string>;
+}
+//#endregion
+//#region src/autopush.d.ts
+interface AutopushOptions {
+  uaid?: string;
+  channelId: string;
+  vapidKey: string;
+  remoteBroadcasts?: Record<string, string>;
+  onNotification: (notification: AutopushNotification) => void;
+  onError?: (error: unknown) => void;
+  onDisconnected?: () => void;
+  onReconnecting?: (delay: number) => void;
+}
+declare class AutopushClient {
+  private options;
+  private ws;
+  private uaid;
+  private endpoint;
+  private reconnectDelay;
+  private closed;
+  private remoteBroadcasts;
+  constructor(options: AutopushOptions);
+  getUaid(): string;
+  getEndpoint(): string;
+  getRemoteBroadcasts(): Record<string, string>;
+  connect(): Promise<string>;
+  close(): void;
+  private send;
+  private reconnect;
+}
+//#endregion
+export { AutopushClient, type AutopushNotification, type AutopushOptions, type ClientState, Decryptor, NotificationClient, type NotificationClientOptions, type TwitterNotification, createClient };