pushnow-sdk 0.1.0 → 0.1.1

package/README.md

@@ -26,47 +26,44 @@ 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.
+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
+## Authorize Once With an Account Token
 
 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.
+Use an account access token from your signed-in app or trusted dashboard session
+to create an account-bound sender authorization.
 
 ```ts
-import {beginLogin, finishLogin} from 'pushnow-sdk';
+import {beginAccountLogin, finishAccountLogin} 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,
+const pending = await beginAccountLogin('https://api.pushnow.dev', accountAccessToken, 'My automation', {
   signal: controller.signal,
 });
+// Open the signed-in trusted App to approve this sender.
+// pending.authorization.user_code and pending.fingerprint are safe to display.
+const config = await finishAccountLogin(pending, {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.
+The account-token flow asks `/v2/account-authorizations` for the account identity
+public key while using the token only as transport authorization. `finishAccountLogin`
+still verifies the encrypted grant, API origin, account binding, archive
+certificate, source certificate, sender private/public key match and recipient
+directory before returning the config. A bearer token alone cannot encrypt
+messages and is never a replacement for the returned sender config.
 
 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.
+a fresh authorization. `finishAccountLogin` checks origin, archive certificate,
+account identity, source certificate, sender private/public key match and device
+certificates before returning the config.
 
 ## Config and Account Binding
 
@@ -85,7 +82,7 @@ type AuthorizedConfig = {
 ```
 
 A bearer token alone cannot encrypt messages. It authorizes HTTP requests but
-does not contain the authenticated sender private key, pinned account identity
+does not contain the authenticated sender private key, verified account identity
 or certified archive public key. Only the receiving account devices have the
 archive private key used to decrypt messages.
 
@@ -144,7 +141,7 @@ 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
+of the encrypted content. Omit it to use the 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

package/README.zh-CN.md

@@ -21,19 +21,20 @@ npm run build
 npm pack
 ```
 
-## 授权
+## 使用账号 Token 授权
 
-SDK sender 需要先在已登录的 PushNow App 中审批。`pending.fingerprint` 是新 sender 的指纹，不是账号根指纹。`expectedIdentityFingerprint` 必须来自可信设备，不能从同一个未验证 grant 自动计算并接受。
+SDK sender 需要先在已登录的 PushNow App 中审批。默认推荐使用已登录 App 或可信 Dashboard 会话里的账号 access token 创建账号绑定授权。token 只用于请求授权接口，真正发送仍依赖返回的加密 sender config。
 
 ```ts
-import {beginLogin, finishLogin} from 'pushnow-sdk';
+import {beginAccountLogin, finishAccountLogin} from 'pushnow-sdk';
 
-const pending = await beginLogin('https://api.pushnow.dev', 'My automation');
-const config = await finishLogin(pending, {
-  expectedIdentityFingerprint: trustedAccountFingerprint,
-});
+const pending = await beginAccountLogin('https://api.pushnow.dev', accountAccessToken, 'My automation');
+// 在已登录的可信 App 中批准。user_code 和 fingerprint 可以展示。
+const config = await finishAccountLogin(pending);
 ```
 
+`finishAccountLogin` 会校验 grant、API origin、账号绑定、archive 证书、source 证书、sender 私钥/公钥匹配和设备目录。只有 bearer token 不能加密消息，也不能替代返回的 sender config。
+
 ## 发送通知
 
 ```ts

package/dist/auth.d.ts

@@ -1,6 +1,3 @@
-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. */
+import type { AuthorizedConfig, PendingAccountLogin, RequestOptions } from './types.js';
 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

@@ -3,20 +3,6 @@ import { generateAgreementKey, openSenderGrant, senderPublicKey, verifyArchive }
 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) => {
@@ -27,11 +13,9 @@ async function wait(ms, signal) {
             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))
+async function finishApprovedAccountLogin(input, options = {}) {
+    const expected = input.expectedIdentityFingerprint.toLowerCase();
+    if (!/^[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);
@@ -55,9 +39,7 @@ export async function finishLogin(input, options) {
                 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)
+            if (expected !== accountFingerprint)
                 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);
@@ -71,7 +53,6 @@ export async function finishLogin(input, options) {
     }
     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');
@@ -84,7 +65,7 @@ export async function beginAccountLogin(apiURL, accessToken, name, options = {})
     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 });
+    const config = await finishApprovedAccountLogin(input, options);
     if (config.user_id !== input.accountUserID)
         throw new Error('Authorization account changed');
     return config;

package/dist/browser.js

@@ -2399,26 +2399,6 @@ async function recipientsV2(input, options = {}) {
 }
 
 // src/auth.ts
-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) => {
@@ -2435,10 +2415,9 @@ async function wait(ms, signal) {
     if (signal?.aborted) abort();
   });
 }
-async function finishLogin(input, options) {
-  if (!options || options.expectedIdentityFingerprint === void 0 && typeof options.confirmIdentity !== "function") throw new Error("Explicit account identity verification is required");
-  const expected = options.expectedIdentityFingerprint?.toLowerCase();
-  if (expected !== void 0 && !/^[a-f0-9]{64}$/.test(expected)) throw new Error("Expected identity fingerprint must be 64 hexadecimal characters");
+async function finishApprovedAccountLogin(input, options = {}) {
+  const expected = input.expectedIdentityFingerprint.toLowerCase();
+  if (!/^[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");
@@ -2461,8 +2440,7 @@ async function finishLogin(input, options) {
       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 !== void 0 ? expected === accountFingerprint : await options.confirmIdentity?.({ fingerprint: accountFingerprint, userID: config.user_id });
-      if (confirmed !== true) throw new Error("Account identity not confirmed; discard this authorization");
+      if (expected !== accountFingerprint) throw new Error("Account identity not confirmed; discard this authorization");
       await recipientsV2(config, options);
       return config;
     }
@@ -2482,7 +2460,7 @@ async function beginAccountLogin(apiURL, accessToken, name, options = {}) {
   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) };
 }
 async function finishAccountLogin(input, options = {}) {
-  const config = await finishLogin(input, { ...options, expectedIdentityFingerprint: input.expectedIdentityFingerprint });
+  const config = await finishApprovedAccountLogin(input, options);
   if (config.user_id !== input.accountUserID) throw new Error("Authorization account changed");
   return config;
 }
@@ -2704,10 +2682,8 @@ async function sendNotification(input, notification, inputOptions = {}) {
 export {
   APIError,
   beginAccountLogin,
-  beginLogin,
   fingerprint,
   finishAccountLogin,
-  finishLogin,
   prepareMessageV2,
   recipientsV2,
   sendNotification,

package/dist/config.d.ts

@@ -1,5 +1,5 @@
 import type { Archive, AuthorizedConfig } from './types.js';
 export declare function validateAPIURL(value: string): string;
 export declare function validateArchive(value: unknown): Archive;
-/** Structural validation only. finishLogin pins identity; recipientsV2 verifies signed bindings. */
+/** Structural validation only. finishAccountLogin verifies identity; recipientsV2 verifies signed bindings. */
 export declare function validateConfig(value: unknown): AuthorizedConfig;

package/dist/config.js

@@ -14,7 +14,7 @@ export function validateArchive(value) {
     decode(archive.certificate, 64);
     return { id: archive.id, public_key: archive.public_key, certificate: archive.certificate };
 }
-/** Structural validation only. finishLogin pins identity; recipientsV2 verifies signed bindings. */
+/** Structural validation only. finishAccountLogin verifies identity; recipientsV2 verifies signed bindings. */
 export function validateConfig(value) {
     const config = object(value);
     for (const field of ['api_url', 'user_id', 'source_id', 'source_key', 'identity_public_key', 'sender_private_key']) {

package/dist/crypto.d.ts

@@ -1,10 +1,10 @@
 import { CipherSuite } from '@hpke/core';
-import type { Archive, AuthorizedConfig, Envelope, PendingLogin } from './types.js';
+import type { Archive, AuthorizedConfig, Envelope, PendingAccountLogin } from './types.js';
 export declare const suite: CipherSuite;
 export declare const v2AAD: (purpose: string, config: AuthorizedConfig, messageID: string, archiveID: string) => Uint8Array<ArrayBuffer>;
-export declare function generateAgreementKey(): Promise<PendingLogin['key']>;
+export declare function generateAgreementKey(): Promise<PendingAccountLogin['key']>;
 export declare function senderPublicKey(privateKey: string): Promise<string>;
 export declare function verifyCertificate(root: string, kind: 'source' | 'device' | 'archive', userID: string, id: string, publicKey: string, signature: string): Promise<boolean>;
 export declare function verifyArchive(config: AuthorizedConfig, value: unknown): Promise<Archive>;
 export declare function sealV2(config: AuthorizedConfig, archive: Archive, purpose: string, messageID: string, plaintext: unknown): Promise<Envelope>;
-export declare function openSenderGrant(pending: PendingLogin, grant: Envelope): Promise<unknown>;
+export declare function openSenderGrant(pending: PendingAccountLogin, grant: Envelope): Promise<unknown>;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { beginLogin, finishLogin, beginAccountLogin, finishAccountLogin } from './auth.js';
+export { beginAccountLogin, finishAccountLogin } from './auth.js';
 export { validateConfig } from './config.js';
 export { recipientsV2 } from './recipients.js';
 export { prepareMessageV2, submitMessageV2 } from './messages.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { beginLogin, finishLogin, beginAccountLogin, finishAccountLogin } from './auth.js';
+export { beginAccountLogin, finishAccountLogin } from './auth.js';
 export { validateConfig } from './config.js';
 export { recipientsV2 } from './recipients.js';
 export { prepareMessageV2, submitMessageV2 } from './messages.js';

package/dist/messages.js

@@ -96,7 +96,7 @@ export async function prepareMessageV2(input, inputDirectory, plaintext, inputOp
     const image = full.attachments.find(a => a.id === full.image_id);
     if (image && bytes(JSON.stringify(image)).length <= 600)
         previewData.image = image;
-    // Budget for the longest supported APNs filename, including legacy/default requests.
+    // Budget for the longest supported APNs filename, including default requests.
     const previewSize = (envelope) => bytes(JSON.stringify({ aps: { alert: { title: 'PushNow', body: 'You have a new encrypted reminder.' }, 'mutable-content': 1, sound: 'pushnow-chime.wav' },
         secure_v2: { message_id: messageID, user_id: config.user_id, source_id: config.source_id, archive_id: directory.archive.id,
             device_id: '00000000-0000-0000-0000-000000000000', ...envelope, source_public_key: directory.source_public_key,

package/dist/types.d.ts

@@ -13,7 +13,7 @@ export interface AuthorizedConfig {
     sender_private_key: string;
     archive: Archive;
 }
-export interface PendingLogin {
+export interface PendingAccountLogin {
     api_url: string;
     key: {
         privateKey: string;
@@ -28,6 +28,8 @@ export interface PendingLogin {
     };
     /** Sender fingerprint for comparison on the approving device, not the account fingerprint. */
     fingerprint: string;
+    accountUserID: string;
+    expectedIdentityFingerprint: string;
 }
 export interface RequestEvent {
     method: 'GET' | 'POST' | 'PUT';
@@ -42,17 +44,6 @@ export interface RequestOptions {
     fetcher?: typeof fetch;
     onRequest?: (event: Readonly<RequestEvent>) => void | Promise<void>;
 }
-export type IdentityVerification = {
-    expectedIdentityFingerprint: string;
-    confirmIdentity?: never;
-} | {
-    expectedIdentityFingerprint?: never;
-    confirmIdentity: (identity: {
-        fingerprint: string;
-        userID: string;
-    }) => boolean | Promise<boolean>;
-};
-export type FinishLoginOptions = RequestOptions & IdentityVerification;
 export interface RecipientDevice {
     id: string;
     user_id: string;
@@ -104,7 +95,7 @@ export interface MessageContent {
 }
 export type NotificationSound = 'default' | 'silent' | 'chime';
 export interface MessageOptions {
-    /** Public routing metadata; omitted keeps legacy default behavior. */
+    /** Public routing metadata; omitted keeps default behavior. */
     sound?: NotificationSound;
     deviceIds?: string[];
     inboxOnly?: boolean;
@@ -139,7 +130,3 @@ export interface SubmitResult {
     message_id: string;
     deduplicated: boolean;
 }
-export interface PendingAccountLogin extends PendingLogin {
-    accountUserID: string;
-    expectedIdentityFingerprint: string;
-}

package/package.json

@@ -1,11 +1,24 @@
 {
   "name": "pushnow-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Browser-compatible end-to-end encrypted PushNow v2 notification SDK",
-  "keywords": ["pushnow", "notifications", "e2ee", "hpke", "sdk", "automation", "ai-agents"],
+  "keywords": [
+    "pushnow",
+    "notifications",
+    "e2ee",
+    "hpke",
+    "sdk",
+    "automation",
+    "ai-agents"
+  ],
   "homepage": "https://github.com/pushnow-dev/pushnow-js#readme",
-  "bugs": { "url": "https://github.com/pushnow-dev/pushnow-js/issues" },
-  "repository": { "type": "git", "url": "git+https://github.com/pushnow-dev/pushnow-js.git" },
+  "bugs": {
+    "url": "https://github.com/pushnow-dev/pushnow-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pushnow-dev/pushnow-js.git"
+  },
   "license": "UNLICENSED",
   "type": "module",
   "sideEffects": false,
@@ -13,11 +26,22 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
-    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js", "default": "./dist/index.js" },
-    "./browser": { "types": "./dist/index.d.ts", "default": "./dist/browser.js" },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/browser.js"
+    },
     "./package.json": "./package.json"
   },
-  "files": ["dist", "README.md", "README.zh-CN.md"],
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh-CN.md"
+  ],
   "scripts": {
     "check": "tsc --noEmit",
     "build": "tsc && node scripts/build.mjs",
@@ -25,7 +49,15 @@
     "test:browser": "npm run build && node --test test/browser.test.mjs",
     "prepack": "npm run build"
   },
-  "dependencies": { "@hpke/core": "1.9.0" },
-  "devDependencies": { "typescript": "~5.9.2", "esbuild": "^0.28.2", "playwright": "^1.58.0" },
-  "engines": { "node": ">=22" }
+  "dependencies": {
+    "@hpke/core": "1.9.0"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.2",
+    "esbuild": "^0.28.2",
+    "playwright": "^1.58.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
 }