pushnow-sdk 0.1.0

package/README.md

@@ -0,0 +1,231 @@
+# PushNow TypeScript SDK
+
+[中文说明](README.zh-CN.md)
+
+Browser-compatible SDK for the existing PushNow v2 encrypted API. Uses
+`@hpke/core` 1.9.0 (P-256 / HKDF-SHA256 / AES-256-GCM) and native WebCrypto.
+No Node polyfills, persistence or analytics.
+
+## Local Package
+
+```sh
+cd sdk/typescript
+npm ci
+npm run build
+npm pack
+```
+
+Install from npm after publication:
+
+```sh
+npm install pushnow-sdk
+```
+
+For local development, install the resulting `pushnow-sdk-0.1.0.tgz` into a
+consuming project, or use a local `file:` dependency. Package name: `pushnow-sdk`.
+
+The ESM entry `dist/index.js` includes TypeScript declarations. For an unbundled
+browser, serve `dist/browser.js` and import it as an ES module. It includes the
+HPKE dependency and needs no import map. A bundler can use `@pushnow/sdk` directly;
+`@pushnow/sdk/browser` selects the standalone bundle. There is no CommonJS entry.
+Use HTTPS, or loopback HTTP for development, in a runtime with `crypto.subtle`,
+`fetch`, `AbortController`, and `structuredClone` (modern browsers or Node 22+).
+
+## Authorize Once
+
+First register, verify email and sign in to the App. Its encrypted account
+archive and approving device must already be initialized. SDK sender approval
+is separate from email/password login; the SDK does not implement account login.
+
+```ts
+import {beginLogin, finishLogin} from 'pushnow-sdk';
+
+const controller = new AbortController();
+const pending = await beginLogin('https://api.pushnow.dev', 'My automation', {
+  signal: controller.signal,
+});
+// Display pending.authorization.user_code and pending.fingerprint.
+// The user approves this sender in the signed-in App.
+// Obtain the ACCOUNT identity fingerprint from that trusted App separately.
+const config = await finishLogin(pending, {
+  expectedIdentityFingerprint: trustedAccountFingerprint,
+  signal: controller.signal,
+});
+```
+
+`pending.fingerprint` identifies the new sender. It is NOT the account identity
+fingerprint. `expectedIdentityFingerprint` must be the independently verified
+64-character SHA-256 hex fingerprint of the account identity public key. Never
+compute the expected value from the same untrusted grant and auto-accept it.
+Alternatively, supply `confirmIdentity: async ({fingerprint, userID}) => boolean`
+and require explicit user comparison with their trusted device. These options
+are mutually exclusive. Missing verification or a mismatch fails closed.
+
+Polling respects the server interval and handles HTTP 429; aborting cancels
+both polling requests and waiting. Authorization grants are single-use. If a
+grant is consumed but validation or a subsequent directory request fails, start
+a fresh authorization. `finishLogin` checks origin, archive certificate,
+account fingerprint, source certificate, sender private/public key match and
+device certificates before returning the config.
+
+## Config and Account Binding
+
+`AuthorizedConfig` uses the CLI-compatible fields:
+
+```ts
+type AuthorizedConfig = {
+  api_url: string;
+  user_id: string;
+  source_id: string;
+  source_key: string;
+  identity_public_key: string;
+  sender_private_key: string;
+  archive: {id: string; public_key: string; certificate: string};
+};
+```
+
+A bearer token alone cannot encrypt messages. It authorizes HTTP requests but
+does not contain the authenticated sender private key, pinned account identity
+or certified archive public key. Only the receiving account devices have the
+archive private key used to decrypt messages.
+
+`validateConfig(input)` synchronously checks structure and returns a clean copy;
+it does not prove ownership or independently confirm identity. For a signed-in
+Web dashboard importing a trusted config, keep it in memory, check
+`config.user_id === me.user.id` and `config.api_url === expectedAPIOrigin`, then
+call `recipientsV2(config)`. Replacing `source_key` is supported, but a token for
+another source/account fails directory binding checks. Never embed config in a
+public JS bundle, URL, log, or plaintext persistent browser storage. Clear all
+references on account logout/change. JavaScript cannot guarantee erasure of
+strings or protect secrets from scripts running in the same page.
+
+## Send
+
+```ts
+import {sendNotification} from 'pushnow-sdk';
+
+const result = await sendNotification(config, {
+  title: 'Build completed',
+  body: 'Version 1.2 is ready.',
+  links: ['https://example.com/build/42'],
+  files: [{data: new Blob(['build output']), name: 'build.txt', mime: 'text/plain'}],
+  // image: {data: imageFile, name: imageFile.name, mime: imageFile.type},
+  // icon: {data: iconFile, name: iconFile.name, mime: iconFile.type},
+}, {
+  // deviceIds: [selectedDeviceID], // omitted: all notification-enabled devices
+  // inboxOnly: true,              // account inbox only; no APNs request
+  // sound: 'chime',               // 'default' | 'silent' | 'chime'
+  // scheduledAt: new Date(Date.now() + 60_000).toISOString(),
+  // expiresAt: new Date(Date.now() + 3_600_000).toISOString(),
+});
+```
+
+`files`, `image`, `icon` accept `{data: Blob | Uint8Array | ArrayBuffer, name,
+mime?, id?}`. The SDK uploads AES-GCM ciphertext and embeds attachment descriptors
+inside the encrypted message. Names, MIME types, keys and clear content are not
+sent as plaintext metadata. The server sees attachment IDs, encrypted byte counts
+and read capabilities, plus routing/schedule metadata. It does not receive
+message text, filenames, or file encryption keys in plaintext.
+
+`MessageContent` supports `title`, `body`, `links`, `attachments`, `image_id`,
+`icon_id`. The last two refer to entries in `attachments`. High-level `image`
+and `icon` upload files and set these IDs automatically. Maximum 20 attachments;
+each encrypted file is at most 20 MiB, so plaintext is at most 20 MiB minus
+16 bytes. Full encrypted manifests are limited to 256 KiB. Preview text is
+UTF-8 bounded; a preview image is omitted when its descriptor cannot fit.
+
+`deviceIds: []` and `inboxOnly: true` both suppress notifications. Do not combine
+`inboxOnly: true` with `deviceIds`. Explicit targets must belong to the account;
+disabled devices are filtered. Inbox/history remains account-wide even when
+only one device is notified. Sending to a single device does not make content
+private from the other account devices.
+
+Schedules must be future ISO timestamps within 30 days. An expiry must follow
+the delivery time and be within 30 days. Offset timestamps are normalized to UTC.
+`MessageOptions.sound` accepts `'default'`, `'silent'`, or `'chime'`. It is public
+routing metadata on the prepared request, like `scheduled_at`, and is not part
+of the encrypted content. Omit it to preserve the legacy wire and default sound
+behavior. Invalid values are rejected before any HTTP request or file upload.
+`'silent'` omits APNs `aps.sound`; it does not suppress the visible notification
+(use `inboxOnly` for that). `'chime'` selects `pushnow-chime.wav`, bundled in the
+new App version; an older App without the file falls back to the default sound.
+Playback remains subject to iOS notification/sound permissions and Focus/Do Not
+Disturb settings. Interruption levels and critical alerts are not supported.
+Successful API acceptance is not proof of device-visible delivery or audible sound.
+
+## Low-Level Flow and Retries
+
+```ts
+import {recipientsV2, uploadAttachment, prepareMessageV2, submitMessageV2} from 'pushnow-sdk';
+
+const directory = await recipientsV2(config);
+const attachment = await uploadAttachment(config, file, {name: file.name});
+const prepared = await prepareMessageV2(config, directory, {
+  title: 'Report', body: 'Attached.', attachments: [attachment],
+}, {deviceIds: [directory.devices[0].id]});
+const result = await submitMessageV2(config, prepared);
+// For an uncertain HTTP result, retry submitMessageV2(config, prepared).
+```
+
+Preparation revalidates the entire directory, including account/source/private
+key binding, even if callers provide the directory themselves. It returns an
+immutable object with an in-memory account/source binding. Submission rejects a
+different account/source or a serialized/cloned object that lost that binding.
+Keep the original object for retries: retries send the exact original request
+bytes, including the selected sound or its omission. Do not change its sound or
+prepare again with the same message ID: fresh encryption yields different
+ciphertext and an idempotency conflict.
+Durable serialized outbox import is not provided by this SDK version.
+
+The high-level helper performs no automatic send retries. Use the low-level
+flow when you need to control retries. Cancelled/failed uploads may leave
+reserved or uploaded orphan blobs for the backend's existing cleanup process.
+
+## Request Options and Redacted Logging
+
+Every HTTP-producing export accepts `RequestOptions` as its final argument:
+
+```ts
+const options = {
+  signal: controller.signal,
+  fetcher: fetch,
+  onRequest(event) {
+    // {method, path, status, durationMs, outcome}
+    // path is e.g. /v2/attachments/:id, not a URL containing identifiers.
+    requestEvents.push(event);
+  },
+};
+```
+
+`prepareMessageV2` is local-only and accepts `MessageOptions` instead.
+`sendNotification` accepts the intersection of both option types. Logging fires
+once per HTTP attempt and contains no headers, payloads, tokens, keys or raw
+server errors. Throwing/rejecting logging callbacks does not change delivery.
+Custom `fetcher` implementations necessarily receive credentials and encrypted
+request bodies; they are trusted transport code, not a safe logging API.
+Requests omit browser cookies, reject redirects and time out after 30 seconds.
+`APIError.status` exposes HTTP failures without echoing response text.
+
+## Verification in This Workspace
+
+```sh
+npm test
+```
+
+The tests use existing CLI cryptography/fixtures, bundle the current backend,
+apply every D1 migration and use real Worker HTTP, D1 and R2. They do not contact
+production or APNs. Backend and CLI development dependencies must be installed
+in this monorepo. The browser test needs `npx playwright install chromium --only-shell`.
+
+The reusable parent-dashboard fixture is
+`test/helpers/backend-fixture.mjs`:
+
+```js
+const h = await startBackendFixture({corsOrigins: [dashboardOrigin]});
+// h.apiURL, h.config, h.session.{accessToken,userId,deviceId}
+// h.sessions, h.keyID, h.db, h.fixture, h.fetcher
+// Existing /v1/me, membership, /v2/keys, /v2/logs use h.session.accessToken.
+await h.close();
+```
+
+Crypto dependency reference: [hpke-js](https://github.com/dajiaji/hpke-js).

package/README.zh-CN.md

@@ -0,0 +1,59 @@
+# PushNow TypeScript SDK
+
+[English](README.md)
+
+这是 PushNow v2 加密 API 的浏览器与 Node.js SDK。它使用 `@hpke/core` 1.9.0、P-256、HKDF-SHA256、AES-256-GCM 和原生 WebCrypto。包格式是 ESM，包含 TypeScript declarations，没有 CommonJS 入口。
+
+## 安装
+
+发布到 npm 后：
+
+```sh
+npm install pushnow-sdk
+```
+
+本地开发：
+
+```sh
+cd sdk/typescript
+npm ci
+npm run build
+npm pack
+```
+
+## 授权
+
+SDK sender 需要先在已登录的 PushNow App 中审批。`pending.fingerprint` 是新 sender 的指纹，不是账号根指纹。`expectedIdentityFingerprint` 必须来自可信设备，不能从同一个未验证 grant 自动计算并接受。
+
+```ts
+import {beginLogin, finishLogin} from 'pushnow-sdk';
+
+const pending = await beginLogin('https://api.pushnow.dev', 'My automation');
+const config = await finishLogin(pending, {
+  expectedIdentityFingerprint: trustedAccountFingerprint,
+});
+```
+
+## 发送通知
+
+```ts
+import {sendNotification} from 'pushnow-sdk';
+
+await sendNotification(config, {
+  title: 'Build completed',
+  body: 'Version 1.2 is ready.',
+  links: ['https://example.com/build/42'],
+}, {
+  sound: 'chime',
+});
+```
+
+SDK 会在本地加密标题、正文、链接和附件。服务器只能看到路由、定时、附件密文字节数等必要元数据，看不到明文内容、文件名或附件密钥。
+
+## 测试
+
+```sh
+npm test
+```
+
+测试覆盖 Worker fixture、浏览器 bundle、授权、加密互通、附件、定时、声音路由和脱敏错误。测试不代表生产 APNs 设备可见送达。

package/dist/attachments.d.ts

@@ -0,0 +1,6 @@
+import type { AttachmentData, AttachmentDescriptor, AttachmentMetadata, AuthorizedConfig, RequestOptions } from './types.js';
+export declare const maxAttachmentSize: number;
+export declare function validateAttachmentMetadata(metadata: AttachmentMetadata): AttachmentMetadata;
+export declare function validateAttachmentData(data: AttachmentData): void;
+export declare function validateDescriptor(value: unknown): AttachmentDescriptor;
+export declare function uploadAttachment(input: AuthorizedConfig, data: AttachmentData, metadata: AttachmentMetadata, options?: RequestOptions): Promise<AttachmentDescriptor>;

package/dist/attachments.js

@@ -0,0 +1,57 @@
+import { validateConfig } from './config.js';
+import { base64, bytes, cryptoAPI, decode, object, sha256, uuid } from './encoding.js';
+import { authenticated } from './http.js';
+export const maxAttachmentSize = 20 * 1024 * 1024 - 16;
+export function validateAttachmentMetadata(metadata) {
+    if (!metadata || typeof metadata.name !== 'string' || !metadata.name.trim() || metadata.name.length > 255 || /[\x00-\x1f]/.test(metadata.name))
+        throw new Error('Invalid attachment name');
+    if (metadata.mime !== undefined && (typeof metadata.mime !== 'string' || !/^[\w!#$&^.+-]+\/[\w!#$&^.+-]+(?:;[^\r\n]*)?$/.test(metadata.mime) || metadata.mime.length > 255))
+        throw new Error('Invalid attachment MIME type');
+    if (metadata.id !== undefined)
+        uuid(metadata.id);
+    return { ...metadata };
+}
+export function validateAttachmentData(data) {
+    const size = typeof Blob !== 'undefined' && data instanceof Blob ? data.size :
+        data instanceof Uint8Array || data instanceof ArrayBuffer ? data.byteLength : NaN;
+    if (!Number.isFinite(size))
+        throw new Error('Attachment must be a Blob, Uint8Array or ArrayBuffer');
+    if (size > maxAttachmentSize)
+        throw new Error('Attachment exceeds the 20 MiB encrypted size limit');
+}
+export function validateDescriptor(value) {
+    const d = object(value);
+    uuid(d.id);
+    validateAttachmentMetadata({ id: d.id, name: d.name, mime: d.mime });
+    if (typeof d.mime !== 'string' || !Number.isSafeInteger(d.size) || d.size < 0 || d.size > maxAttachmentSize ||
+        typeof d.read_token !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(d.read_token) || typeof d.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(d.sha256))
+        throw new Error('Invalid attachment descriptor');
+    decode(d.key, 32);
+    decode(d.nonce, 12);
+    return { id: d.id, name: d.name, mime: d.mime, size: d.size, read_token: d.read_token,
+        key: d.key, nonce: d.nonce, sha256: d.sha256 };
+}
+export async function uploadAttachment(input, data, metadata, options = {}) {
+    const config = validateConfig(input), meta = validateAttachmentMetadata(metadata);
+    validateAttachmentData(data);
+    options.signal?.throwIfAborted();
+    const clear = typeof Blob !== 'undefined' && data instanceof Blob ? new Uint8Array(await data.arrayBuffer()) :
+        data instanceof Uint8Array ? new Uint8Array(data) : new Uint8Array(data.slice(0));
+    const key = cryptoAPI().getRandomValues(new Uint8Array(32)), nonce = cryptoAPI().getRandomValues(new Uint8Array(12));
+    const id = meta.id ?? cryptoAPI().randomUUID();
+    try {
+        const aes = await cryptoAPI().subtle.importKey('raw', key, 'AES-GCM', false, ['encrypt']);
+        const ciphertext = await cryptoAPI().subtle.encrypt({ name: 'AES-GCM', iv: nonce,
+            additionalData: bytes(JSON.stringify([2, 'attachment', config.user_id, config.source_id, id])) }, aes, clear);
+        const descriptor = { id, name: meta.name, mime: meta.mime ?? 'application/octet-stream', size: clear.length,
+            read_token: base64(cryptoAPI().getRandomValues(new Uint8Array(32))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''),
+            key: base64(key), nonce: base64(nonce), sha256: await sha256(clear) };
+        await authenticated(config, '/v2/attachments', { ...options, method: 'POST', body: { id, size: ciphertext.byteLength, read_token: descriptor.read_token } });
+        await authenticated(config, `/v2/attachments/${id}`, { ...options, method: 'PUT', binary: true, body: ciphertext });
+        return descriptor;
+    }
+    finally {
+        key.fill(0);
+        clear.fill(0);
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1,6 @@
+import type { AuthorizedConfig, FinishLoginOptions, PendingLogin, PendingAccountLogin, RequestOptions } from './types.js';
+export declare function beginLogin(apiURL: string, name: string, options?: RequestOptions): Promise<PendingLogin>;
+export declare function finishLogin(input: PendingLogin, options: FinishLoginOptions): Promise<AuthorizedConfig>;
+/** Account login delegates initial approval to an online trusted device. */
+export declare function beginAccountLogin(apiURL: string, accessToken: string, name: string, options?: RequestOptions): Promise<PendingAccountLogin>;
+export declare function finishAccountLogin(input: PendingAccountLogin, options?: RequestOptions): Promise<AuthorizedConfig>;

package/dist/auth.js

@@ -0,0 +1,91 @@
+import { validateAPIURL, validateConfig } from './config.js';
+import { generateAgreementKey, openSenderGrant, senderPublicKey, verifyArchive } from './crypto.js';
+import { fingerprint, object, uuid } from './encoding.js';
+import { APIError, request } from './http.js';
+import { recipientsV2 } from './recipients.js';
+export async function beginLogin(apiURL, name, options = {}) {
+    if (typeof name !== 'string' || !name.trim() || name.trim().length > 80)
+        throw new Error('Sender name must have 1 to 80 characters');
+    options.signal?.throwIfAborted();
+    const api_url = validateAPIURL(apiURL), key = await generateAgreementKey();
+    const value = object(await request(api_url, '/v2/authorizations', { ...options, method: 'POST', body: { name: name.trim(), public_key: key.publicKey } }));
+    uuid(value.id);
+    if (typeof value.device_code !== 'string' || typeof value.user_code !== 'string' || typeof value.expires_at !== 'string' ||
+        !Number.isFinite(Date.parse(value.expires_at)) || Date.parse(value.expires_at) <= Date.now())
+        throw new Error('Invalid authorization response');
+    return { api_url, key, authorization: { id: value.id, device_code: value.device_code, user_code: value.user_code,
+            expires_at: value.expires_at, interval: typeof value.interval === 'number' && Number.isFinite(value.interval) ? Math.max(3, value.interval) : 3 },
+        fingerprint: await fingerprint(key.publicKey) };
+}
+async function wait(ms, signal) {
+    signal?.throwIfAborted();
+    await new Promise((resolve, reject) => {
+        const abort = () => { clearTimeout(timer); signal?.removeEventListener('abort', abort); reject(new DOMException('Login aborted', 'AbortError')); };
+        const timer = setTimeout(() => { signal?.removeEventListener('abort', abort); resolve(); }, ms);
+        signal?.addEventListener('abort', abort, { once: true });
+        if (signal?.aborted)
+            abort();
+    });
+}
+export async function finishLogin(input, options) {
+    if (!options || (options.expectedIdentityFingerprint === undefined && typeof options.confirmIdentity !== 'function'))
+        throw new Error('Explicit account identity verification is required');
+    const expected = options.expectedIdentityFingerprint?.toLowerCase();
+    if (expected !== undefined && !/^[a-f0-9]{64}$/.test(expected))
+        throw new Error('Expected identity fingerprint must be 64 hexadecimal characters');
+    const pending = structuredClone(input), { authorization, key } = pending;
+    const api_url = validateAPIURL(pending.api_url);
+    if (await senderPublicKey(key.privateKey) !== key.publicKey)
+        throw new Error('Pending authorization key mismatch');
+    uuid(authorization.id);
+    while (Date.now() < Date.parse(authorization.expires_at)) {
+        options.signal?.throwIfAborted();
+        let response;
+        try {
+            response = object(await request(api_url, `/v2/authorizations/${encodeURIComponent(authorization.id)}/token`, { ...options, method: 'POST', body: { device_code: authorization.device_code } }));
+        }
+        catch (error) {
+            if (!(error instanceof APIError) || error.status !== 429)
+                throw error;
+        }
+        if (response?.status === 'approved') {
+            const grant = object(await openSenderGrant(pending, object(response.grant)));
+            const config = validateConfig({ ...grant, sender_private_key: key.privateKey });
+            if (config.api_url !== api_url)
+                throw new Error('Authorization API origin changed');
+            await verifyArchive(config, config.archive);
+            const accountFingerprint = await fingerprint(config.identity_public_key);
+            const confirmed = expected !== undefined ? expected === accountFingerprint :
+                await options.confirmIdentity?.({ fingerprint: accountFingerprint, userID: config.user_id });
+            if (confirmed !== true)
+                throw new Error('Account identity not confirmed; discard this authorization');
+            // The grant must bind this local private key to the claimed account/source before returning it.
+            await recipientsV2(config, options);
+            return config;
+        }
+        if (response && response.status !== 'pending')
+            throw new Error('Unexpected authorization state');
+        const remaining = Date.parse(authorization.expires_at) - Date.now();
+        if (remaining > 0)
+            await wait(Math.min(remaining, Math.max(3, Number(authorization.interval) || 3) * 1000), options.signal);
+    }
+    throw new Error('Authorization expired; start login again');
+}
+/** Account login delegates initial approval to an online trusted device. */
+export async function beginAccountLogin(apiURL, accessToken, name, options = {}) {
+    if (!name.trim() || name.trim().length > 80)
+        throw new Error('Invalid sender name');
+    const api_url = validateAPIURL(apiURL), key = await generateAgreementKey();
+    const value = object(await request(api_url, '/v2/account-authorizations', { ...options, token: accessToken, method: 'POST', body: { name: name.trim(), public_key: key.publicKey } }));
+    uuid(value.id);
+    uuid(value.user_id);
+    if (typeof value.device_code !== 'string' || typeof value.user_code !== 'string' || typeof value.expires_at !== 'string' || !Number.isFinite(Date.parse(value.expires_at)) || Date.parse(value.expires_at) <= Date.now() || typeof value.identity_public_key !== 'string')
+        throw new Error('Invalid account authorization');
+    return { api_url, key, authorization: { id: value.id, device_code: value.device_code, user_code: value.user_code, expires_at: value.expires_at, interval: 3 }, fingerprint: await fingerprint(key.publicKey), accountUserID: value.user_id, expectedIdentityFingerprint: await fingerprint(value.identity_public_key) };
+}
+export async function finishAccountLogin(input, options = {}) {
+    const config = await finishLogin(input, { ...options, expectedIdentityFingerprint: input.expectedIdentityFingerprint });
+    if (config.user_id !== input.accountUserID)
+        throw new Error('Authorization account changed');
+    return config;
+}