agentic-notify 0.3.0 → 0.4.1

package/README.md

@@ -5,16 +5,15 @@
 
 Notifications for humans and agents: in-app inbox, email and webhook delivery, with a CLI, API, MCP server and SDK.
 
-**Status: 0.3.0.** Breaking for 0.1.0 code and databases, see the CHANGELOG upgrade steps. Works today: the notification model, preferences and mute, digest, a store port from agentic-identity with its memory and D1 adapters, signed webhook and email delivery through a dispatcher, an HTTP API in a Worker, an SDK, a CLI, MCP tools, per-recipient export and erase, and a retention sweep. Not done: a real email provider adapter, webhook endpoint management, and a web UI.
+**Status: 0.4.1.** Breaking for Worker auth, see "Migrating from `NOTIFY_TOKENS`" below. Breaking for 0.1.0 code and databases, see the CHANGELOG upgrade steps. Works today: the notification model, preferences and mute, digest, a store port from agentic-identity with its memory and D1 adapters, signed webhook and email delivery through a dispatcher, an HTTP API in a Worker, an SDK, a CLI, MCP tools, per-recipient export and erase, and a retention sweep. Not done: a real email provider adapter, webhook endpoint management, and a web UI.
 
 ## Live demo
 
-A demo Worker runs at https://agentic-notify-demo.hello-fd1.workers.dev. `GET /health` answers 200. The `/api/v1` routes need a bearer token, so without one they answer 401. The demo keeps its data in the EU and sweeps notifications after 7 days.
+A demo Worker runs at https://agentic-notify-demo.hello-fd1.workers.dev. `GET /health` answers 200. The `/api/v1` routes need a key, so without one they answer 401. The demo keeps its data in the EU and sweeps notifications after 7 days.
 
-Redeploy your own copy with `wrangler.demo.jsonc` (create the D1 database with `--location weur`, put its id in the file, set the `NOTIFY_TOKENS` secret):
+Redeploy your own copy with `wrangler.demo.jsonc` (create the D1 database with `--location weur`, put its id in the file, then add principals and keys, see Identity):
 
 ```sh
-npx wrangler secret put NOTIFY_TOKENS --config wrangler.demo.jsonc
 WRANGLER_SEND_METRICS=false npm run deploy:demo
 ```
 
@@ -42,16 +41,16 @@ await notifier.send({
 const { items } = await notifier.list({ kind: "agent", id: "helper" });
 ```
 
-Worker (D1 binding `DB`, secret `NOTIFY_TOKENS`):
+Worker (D1 binding `DB`):
 
 ```sh
 # Create the database first: npx wrangler d1 create agentic-notify --location weur
-# NOTIFY_TOKENS is JSON: { "<token of 32+ bytes>": { "kind": "human", "id": "ana", "canSend": true } }
-npx wrangler secret put NOTIFY_TOKENS
 npx wrangler deploy
 ```
 
-Without a D1 binding or `NOTIFY_TOKENS`, every `/api/v1` call answers 503. Nobody gets in by default.
+The Worker reads keys and principals from the same D1 database, with `agentic-identity`. Issue a key for each caller with `agentic-identity` (for example `issueCredential`, or its Worker), into this database. See Identity below.
+
+Without a D1 binding, every `/api/v1` call answers 503. A request without a valid key answers 401, on unknown paths too. Nobody gets in by default.
 
 CLI, SDK and MCP talk to that Worker:
 
@@ -64,7 +63,9 @@ npx agentic-notify mcp      # tools: ping, list_notifications, read_notification
                             # export_data, erase_data, send_notification
 ```
 
-The MCP server needs `NOTIFY_URL` and `NOTIFY_TOKEN`. Without them only `ping` works. `erase_data` needs `confirm: true`.
+`npx agentic-notify mcp --help` (or `-h`) prints the usage and exits 0. `npx agentic-notify mcp --version` (or `-V` or `-v`) prints the version and exits 0. Neither starts the server.
+
+The MCP server needs `NOTIFY_URL` and `NOTIFY_TOKEN`. Without them only `ping` works. `erase_data` needs `confirm: true` and a key with `notify:admin`. `send_notification` needs `notify-send:write`. A tool that lacks its scope reports 403.
 
 ```ts
 import { createClient } from "agentic-notify/sdk";
@@ -74,7 +75,16 @@ console.log(await client.unreadCount());
 
 ## HTTP API
 
-All routes sit under `/api/v1` and need `Authorization: Bearer <token>`. `GET /health` is open.
+All routes sit under `/api/v1` and need `Authorization: Bearer <key>`. `GET /health` is open. A missing or bad key answers 401. A good key without the scope of the route answers 403. Each route needs one scope:
+
+| Scope | Routes |
+| --- | --- |
+| `notify:read` | `GET /notifications`, `GET /notifications/:id`, `GET /unread-count`, `GET /digest`, `GET /preferences`, `GET /me/export` |
+| `notify:write` | `POST /notifications/:id/read`, `POST /notifications/read-all`, `PUT /preferences` |
+| `notify-send:write` | `POST /notifications` |
+| `notify:admin` | `DELETE /me` |
+
+A scope with a higher action covers the lower ones, so `notify:admin` covers `notify:write` and `notify:read`. `*:admin` covers all. `notify-send` is a separate resource, so a key that can only send cannot read.
 
 | Route | Use |
 | --- | --- |
@@ -87,7 +97,22 @@ All routes sit under `/api/v1` and need `Authorization: Bearer <token>`. `GET /h
 
 ## Identity
 
-Auth is a port: `PrincipalResolver` turns a request into `{ kind: "human" | "agent", id }` or null. `createStaticTokenResolver` is a small example. To use another identity system, call `createWorker({ resolver })` with your own resolver. A caller reads and changes only its own notifications.
+The Worker authenticates with `agentic-identity`. `requirePrincipal` from `agentic-identity/http` reads the credential, and the `Auth` port checks that it is not expired or revoked. The default `Auth` takes a bearer key, and also a `session` cookie that `agentic-identity` sets. A write with a cookie is refused, because no origin is allowed here. Pass your own `Auth` to accept bearer keys only. The default `Auth` is `createStoreAuth` over the same D1 store. Each route checks one scope (see HTTP API). A delegated agent holds only the scopes that its person also holds.
+
+A person, and a `user_token` of that person, use the inbox of the person. An agent (`agent`, `agent_of_human` or `agent_of_agent`) uses the inbox of its own id. A caller reads and changes only its own notifications.
+
+To use another identity system, call `createWorker({ auth: (env, store) => myAuth })`, where `auth` builds your own `Auth` from the Worker env and the store. Import `createWorker` from `agentic-notify/worker`.
+
+### Migrating from `NOTIFY_TOKENS`
+
+Before 0.4.0, the Worker read a static `NOTIFY_TOKENS` secret: a map of token to `{ kind, id, canSend }`. The tokens had no scopes. The Worker no longer reads it. Steps:
+
+1. Delete the `NOTIFY_TOKENS` secret (`npx wrangler secret delete NOTIFY_TOKENS`).
+2. Make each caller a principal in the D1 database, and issue it a key with `agentic-identity`. The old `{ "kind": "human" }` becomes kind `human`, and `{ "kind": "agent" }` becomes kind `agent`.
+3. Give each principal scopes. An old token could read, change and erase its own inbox. To keep that, use `notify:admin`. For less, use `notify:write` (it covers `notify:read`) or `notify:read`. For the old `canSend: true`, add `notify-send:write`. It is a separate resource, so it does not cover `notify:read`: a caller that sends and reads needs both.
+4. Give the new key to the CLI, SDK and MCP server as `NOTIFY_TOKEN`.
+
+Library users: `createWorker` takes `auth` in place of `resolver`. `authorizeSend` still works as an extra check after the scope. Its first argument is now a `PrincipalContext` (`principalId` in place of `id`, no `canSend`). Its default changed: it was "only `canSend: true`", and now every caller with `notify-send:write` may send unless you pass your own.
 
 ## Privacy
 
@@ -97,6 +122,24 @@ Auth is a port: `PrincipalResolver` turns a request into `{ kind: "human" | "age
 - Logs hold ids, channel names and error names only. They never hold bodies or addresses.
 - Erase removes a recipient's own notifications and preferences. Notifications that name the person only as actor stay with their recipients.
 
+## Testing
+
+`agentic-notify/testing` helps you test a store adapter and your own code.
+
+`runStoreContract(make)` runs the store contract suite. Call it at the top level of a vitest test
+file, and install `vitest` 3 or later. The factory makes a new store for each call. A store made
+without `shared` must start empty. Stores made with the same `shared` value must see the same data.
+So the factory passes `options` to the store:
+
+```ts
+import { createMemoryStore } from "agentic-notify";
+import { runStoreContract } from "agentic-notify/testing";
+
+runStoreContract((options) => createMemoryStore(options));
+```
+
+`TestEmailAdapter` records each message in memory and can fail a set number of sends.
+
 ## Limits
 
 - The default Worker serves the inbox. To fan out to webhook and email, compose `createApp` with `createDispatcher` in your own Worker.

package/dist/{chunk-O574VONP.js → chunk-O2W4ELN4.js}

@@ -1,7 +1,7 @@
 // package.json
 var package_default = {
   name: "agentic-notify",
-  version: "0.3.0",
+  version: "0.4.1",
   description: "Notifications for humans and agents: in-app inbox, webhook and email delivery, with SDK, CLI, MCP server and Worker API.",
   keywords: [
     "notifications",
@@ -66,10 +66,10 @@ var package_default = {
     "check:worker": "esbuild src/worker.ts --bundle --platform=neutral --format=esm --log-level=warning --outfile=node_modules/.cache/worker-check.js"
   },
   dependencies: {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "agentic-identity": "^0.4.0",
+    "@modelcontextprotocol/sdk": "^1.23.0",
+    "agentic-identity": "^0.7.0",
     hono: "^4.13.14",
-    zod: "^3.25.0"
+    zod: "^4.6.7"
   },
   devDependencies: {
     "@types/node": "^22.0.0",

package/dist/cli.js

@@ -10,7 +10,7 @@ import "./chunk-KJKM56FT.js";
 import "./chunk-ARL7FN6Y.js";
 import {
   VERSION
-} from "./chunk-O574VONP.js";
+} from "./chunk-O2W4ELN4.js";
 
 // src/cli.ts
 import { realpathSync } from "fs";
@@ -43,7 +43,7 @@ function helpText() {
     "  mcp                                            Start the MCP server on stdio.",
     "",
     "Environment: NOTIFY_URL (server base url), NOTIFY_TOKEN (bearer token).",
-    "Flags: --help, -h; --version, -V."
+    "Flags: --help, -h; --version, -V. mcp also takes -v for --version."
   ].join("\n");
 }
 function flags(args, known) {
@@ -84,6 +84,14 @@ async function runCli(argv, io = defaultIo()) {
     io.out(VERSION);
     return 0;
   }
+  if (cmd === "mcp" && args.some((a) => a === "--help" || a === "-h")) {
+    io.out(helpText());
+    return 0;
+  }
+  if (cmd === "mcp" && args.some((a) => a === "--version" || a === "-V" || a === "-v")) {
+    io.out(VERSION);
+    return 0;
+  }
   try {
     if (cmd === "mcp") {
       const { startMcp } = await import("./mcp.js");

package/dist/{dispatch-LBnkLOQg.d.ts → dispatch-CH4Ju-_1.d.ts}

@@ -1,7 +1,7 @@
-import { R as RecipientExport } from './gdpr-CUq5MUwo.js';
+import { R as RecipientExport } from './gdpr-C3YxbZp-.js';
 import { Store } from 'agentic-identity';
-import { S as SendInput, N as Notification, C as Channel, R as Recipient, D as Digest, P as Preferences } from './types-C842YAMe.js';
-import { D as DeliveryChannel, L as Logger } from './types-DONKNIOo.js';
+import { S as SendInput, N as Notification, C as Channel, R as Recipient, D as Digest, P as Preferences } from './types-BAG4ZSoy.js';
+import { D as DeliveryChannel, L as Logger } from './types-DhgcIImw.js';
 
 interface NotifierOptions {
     store: Store;
@@ -74,4 +74,4 @@ declare function createDispatcher(options: DispatcherOptions): {
     notify(input: SendInput): Promise<DispatchResult>;
 };
 
-export { type DispatchResult as D, type ListOptions as L, NotFoundError as N, type SendResult as S, type DispatcherOptions as a, type ListResult as b, type Notifier as c, type NotifierOptions as d, createDispatcher as e, createNotifier as f };
+export { type DispatchResult as D, type ListOptions as L, type Notifier as N, type SendResult as S, type DispatcherOptions as a, type ListResult as b, createDispatcher as c, NotFoundError as d, type NotifierOptions as e, createNotifier as f };

package/dist/{gdpr-CUq5MUwo.d.ts → gdpr-C3YxbZp-.d.ts}

@@ -1,4 +1,4 @@
-import { R as Recipient, P as Preferences, N as Notification } from './types-C842YAMe.js';
+import { R as Recipient, P as Preferences, N as Notification } from './types-BAG4ZSoy.js';
 
 interface RecipientExport {
     recipient: Recipient;

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-export { D as DispatchResult, a as DispatcherOptions, L as ListOptions, b as ListResult, N as NotFoundError, c as Notifier, d as NotifierOptions, S as SendResult, e as createDispatcher, f as createNotifier } from './dispatch-LBnkLOQg.js';
+export { D as DispatchResult, a as DispatcherOptions, L as ListOptions, b as ListResult, d as NotFoundError, N as Notifier, e as NotifierOptions, S as SendResult, c as createDispatcher, f as createNotifier } from './dispatch-CH4Ju-_1.js';
 export { Doc, Page, Query, Scalar, Store, StoreOps, createMemoryStore } from 'agentic-identity';
-import { R as Recipient } from './types-C842YAMe.js';
-export { A as Actor, b as CHANNELS, C as Channel, c as DEFAULT_CHANNELS, D as Digest, d as DigestGroup, N as Notification, P as Preferences, a as ResourceRef, S as SendInput, e as defaultPreferences, r as recipientKey } from './types-C842YAMe.js';
-import { D as DeliveryChannel } from './types-DONKNIOo.js';
-export { a as DeliveryError, L as Logger } from './types-DONKNIOo.js';
-export { E as EmailChannelOptions, a as EmailMessage, b as EmailPort, c as createEmailChannel } from './testing-B5slvYDV.js';
+import { R as Recipient } from './types-BAG4ZSoy.js';
+export { A as Actor, b as CHANNELS, C as Channel, c as DEFAULT_CHANNELS, D as Digest, d as DigestGroup, N as Notification, P as Preferences, a as ResourceRef, S as SendInput, e as defaultPreferences, r as recipientKey } from './types-BAG4ZSoy.js';
+import { D as DeliveryChannel } from './types-DhgcIImw.js';
+export { a as DeliveryError, L as Logger } from './types-DhgcIImw.js';
+export { E as EmailChannelOptions, a as EmailMessage, b as EmailPort, c as createEmailChannel } from './testing-DEBqTQFK.js';
 export { D1Like, D1_SCHEMA, createD1Store } from 'agentic-identity/cloudflare';
-export { R as RecipientExport } from './gdpr-CUq5MUwo.js';
+export { R as RecipientExport } from './gdpr-C3YxbZp-.js';
 import 'zod';
 import 'agentic-identity/testing';
 

package/dist/index.js

@@ -23,7 +23,7 @@ import {
 } from "./chunk-ARL7FN6Y.js";
 import {
   VERSION
-} from "./chunk-O574VONP.js";
+} from "./chunk-O2W4ELN4.js";
 export {
   CHANNELS,
   D1_SCHEMA,

package/dist/mcp-bin.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import {
   VERSION
-} from "./chunk-O574VONP.js";
+} from "./chunk-O2W4ELN4.js";
 
 // src/mcp-bin.ts
 var HELP = `agentic-notify-mcp ${VERSION}
-Usage: agentic-notify-mcp [--help | --version]
+Usage: agentic-notify-mcp [--help | -h | --version | -V]
 
 Runs the MCP server on stdio. An MCP client starts it.
 `;

package/dist/mcp.d.ts

@@ -1,8 +1,8 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Client } from './sdk.js';
-import './types-C842YAMe.js';
+import './types-BAG4ZSoy.js';
 import 'zod';
-import './gdpr-CUq5MUwo.js';
+import './gdpr-C3YxbZp-.js';
 
 /** Without a client, only `ping` works and the other tools report that setup is missing. */
 declare function createMcpServer(client?: Client): McpServer;

package/dist/mcp.js

@@ -13,7 +13,7 @@ import {
 } from "./chunk-ARL7FN6Y.js";
 import {
   VERSION
-} from "./chunk-O574VONP.js";
+} from "./chunk-O2W4ELN4.js";
 
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/dist/sdk.d.ts

@@ -1,5 +1,5 @@
-import { N as Notification, D as Digest, P as Preferences, R as Recipient, a as ResourceRef } from './types-C842YAMe.js';
-import { R as RecipientExport } from './gdpr-CUq5MUwo.js';
+import { N as Notification, D as Digest, P as Preferences, R as Recipient, a as ResourceRef } from './types-BAG4ZSoy.js';
+import { R as RecipientExport } from './gdpr-C3YxbZp-.js';
 import 'zod';
 
 declare class ApiError extends Error {
@@ -43,40 +43,40 @@ declare function createClient(options: ClientOptions): {
         cursor?: string;
     }) => Promise<NotificationPage>;
     get: (id: string) => Promise<{
-        type: string;
         id: string;
         recipient: {
-            id: string;
             kind: "human" | "agent";
+            id: string;
         };
+        type: string;
         resource: {
-            id: string;
             kind: string;
+            id: string;
             url?: string | undefined;
         };
         actor: {
-            id: string;
             kind: "human" | "agent";
+            id: string;
         };
         body: string;
         createdAt: number;
         readAt: number | null;
     }>;
     markRead: (id: string) => Promise<{
-        type: string;
         id: string;
         recipient: {
-            id: string;
             kind: "human" | "agent";
+            id: string;
         };
+        type: string;
         resource: {
-            id: string;
             kind: string;
+            id: string;
             url?: string | undefined;
         };
         actor: {
-            id: string;
             kind: "human" | "agent";
+            id: string;
         };
         body: string;
         createdAt: number;

package/dist/{testing-B5slvYDV.d.ts → testing-DEBqTQFK.d.ts}

@@ -1,6 +1,6 @@
 import 'agentic-identity/testing';
-import { R as Recipient } from './types-C842YAMe.js';
-import { D as DeliveryChannel } from './types-DONKNIOo.js';
+import { R as Recipient } from './types-BAG4ZSoy.js';
+import { D as DeliveryChannel } from './types-DhgcIImw.js';
 
 interface EmailMessage {
     to: string;

package/dist/testing.d.ts

@@ -1,5 +1,5 @@
 export { runStoreContract } from 'agentic-identity/testing';
-export { T as TestEmailAdapter } from './testing-B5slvYDV.js';
-import './types-C842YAMe.js';
+export { T as TestEmailAdapter } from './testing-DEBqTQFK.js';
+import './types-BAG4ZSoy.js';
 import 'zod';
-import './types-DONKNIOo.js';
+import './types-DhgcIImw.js';

package/dist/types-BAG4ZSoy.d.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+
+declare const CHANNELS: readonly ["inbox", "webhook", "email"];
+type Channel = (typeof CHANNELS)[number];
+declare const recipientSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        human: "human";
+        agent: "agent";
+    }>;
+    id: z.ZodString;
+}, z.core.$strict>;
+type Recipient = z.infer<typeof recipientSchema>;
+declare const resourceRefSchema: z.ZodObject<{
+    kind: z.ZodString;
+    id: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type ResourceRef = z.infer<typeof resourceRefSchema>;
+declare const actorSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        human: "human";
+        agent: "agent";
+    }>;
+    id: z.ZodString;
+}, z.core.$strict>;
+type Actor = z.infer<typeof actorSchema>;
+declare const notificationSchema: z.ZodObject<{
+    id: z.ZodString;
+    recipient: z.ZodObject<{
+        kind: z.ZodEnum<{
+            human: "human";
+            agent: "agent";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    type: z.ZodString;
+    resource: z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    actor: z.ZodObject<{
+        kind: z.ZodEnum<{
+            human: "human";
+            agent: "agent";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    body: z.ZodString;
+    createdAt: z.ZodNumber;
+    readAt: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>;
+type Notification = z.infer<typeof notificationSchema>;
+declare const sendInputSchema: z.ZodObject<{
+    recipient: z.ZodObject<{
+        kind: z.ZodEnum<{
+            human: "human";
+            agent: "agent";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    type: z.ZodString;
+    resource: z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    actor: z.ZodObject<{
+        kind: z.ZodEnum<{
+            human: "human";
+            agent: "agent";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    body: z.ZodString;
+}, z.core.$strict>;
+type SendInput = z.infer<typeof sendInputSchema>;
+declare const preferencesSchema: z.ZodObject<{
+    channels: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodEnum<{
+        inbox: "inbox";
+        webhook: "webhook";
+        email: "email";
+    }>>>;
+    muted: z.ZodBoolean;
+    mutedTypes: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+type Preferences = z.infer<typeof preferencesSchema>;
+declare const DEFAULT_CHANNELS: readonly Channel[];
+declare function defaultPreferences(): Preferences;
+declare function recipientKey(recipient: Recipient): string;
+interface DigestGroup {
+    type: string;
+    count: number;
+    latest: Notification;
+}
+interface Digest {
+    total: number;
+    groups: DigestGroup[];
+}
+
+export { type Actor as A, type Channel as C, type Digest as D, type Notification as N, type Preferences as P, type Recipient as R, type SendInput as S, type ResourceRef as a, CHANNELS as b, DEFAULT_CHANNELS as c, type DigestGroup as d, defaultPreferences as e, recipientKey as r };

package/dist/{types-DONKNIOo.d.ts → types-DhgcIImw.d.ts}

@@ -1,4 +1,4 @@
-import { N as Notification } from './types-C842YAMe.js';
+import { N as Notification } from './types-BAG4ZSoy.js';
 
 /** A delivery channel other than the inbox. */
 interface DeliveryChannel {

package/dist/worker.d.ts

@@ -1,56 +1,39 @@
-import { z } from 'zod';
-import { c as Notifier, e as createDispatcher } from './dispatch-LBnkLOQg.js';
-import { R as Recipient } from './types-C842YAMe.js';
+import { Auth, PrincipalContext, Store } from 'agentic-identity';
+import { N as Notifier, c as createDispatcher } from './dispatch-CH4Ju-_1.js';
+import { R as Recipient } from './types-BAG4ZSoy.js';
 import { D1Like } from 'agentic-identity/cloudflare';
-import './gdpr-CUq5MUwo.js';
-import 'agentic-identity';
-import './types-DONKNIOo.js';
-
-/** Who is calling. `kind` has no default: a missing kind is an error. */
-declare const principalSchema: z.ZodObject<{
-    kind: z.ZodEnum<["human", "agent"]>;
-    id: z.ZodString;
-    /** Allowed to send notifications to others. */
-    canSend: z.ZodOptional<z.ZodBoolean>;
-}, "strict", z.ZodTypeAny, {
-    kind: "human" | "agent";
-    id: string;
-    canSend?: boolean | undefined;
-}, {
-    kind: "human" | "agent";
-    id: string;
-    canSend?: boolean | undefined;
-}>;
-type Principal = z.infer<typeof principalSchema>;
-/** Port: turn a request into a principal, or null for "not signed in". Plug in any identity system. */
-type PrincipalResolver = (request: Request) => Promise<Principal | null> | Principal | null;
+import './gdpr-C3YxbZp-.js';
+import './types-DhgcIImw.js';
+import 'zod';
 
 interface AppOptions {
     notifier: Notifier;
     /** When set, sends also go to webhook and email channels. */
     dispatcher?: ReturnType<typeof createDispatcher>;
-    resolvePrincipal: PrincipalResolver;
-    /** May this principal send to this recipient? Default: only principals with `canSend: true`. */
-    authorizeSend?: (principal: Principal, recipient: Recipient) => Promise<boolean> | boolean;
+    /** Reads the credential on a request. Each route then checks one scope. */
+    auth: Auth;
+    /** Extra check on a send, after the `notify-send:write` scope. Default: allow. */
+    authorizeSend?: (principal: PrincipalContext, recipient: Recipient) => Promise<boolean> | boolean;
 }
 
 interface WorkerEnv {
     NOTIFY_NAME?: string;
     /** D1 binding. */
     DB?: D1Like;
-    /** Secret. JSON map of bearer token (32 bytes or more) to principal. */
-    NOTIFY_TOKENS?: string;
     /** Data region of the store: "eu", "us" or "unknown". Default "eu". */
     NOTIFY_REGION?: string;
     /** Retention window in days. Unset keeps notifications. */
     NOTIFY_RETENTION_DAYS?: string;
 }
 interface WorkerConfig {
-    /** Build the principal resolver from the environment. Null means not configured. */
-    resolver(env: WorkerEnv): Promise<PrincipalResolver | null>;
+    /**
+     * Build the `Auth` port. Default: `createStoreAuth` over the same store, so keys that
+     * agentic-identity issues into the database work here. Each route checks a scope.
+     */
+    auth?(env: WorkerEnv, store: Store): Auth;
     authorizeSend?: AppOptions["authorizeSend"];
 }
-/** Compose the Worker. Bring your own identity system through `resolver`. */
+/** Compose the Worker. Bring your own identity system through `auth`. */
 declare function createWorker(config: WorkerConfig): {
     fetch(request: Request, env: WorkerEnv): Promise<Response>;
     /** Delete notifications past the retention window. Wire to a cron trigger. */

package/dist/worker.js

@@ -9,76 +9,81 @@ import {
 } from "./chunk-ARL7FN6Y.js";
 import {
   VERSION
-} from "./chunk-O574VONP.js";
+} from "./chunk-O2W4ELN4.js";
 
 // src/api.ts
 import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
-import { ZodError, z as z2 } from "zod";
+import { ZodError, z } from "zod";
+import { requirePrincipal } from "agentic-identity/http";
 
 // src/auth.ts
-import { z } from "zod";
-var principalSchema = z.object({
-  kind: z.enum(["human", "agent"]),
-  id: z.string().min(1).max(200),
-  /** Allowed to send notifications to others. */
-  canSend: z.boolean().optional()
-}).strict();
-var MIN_TOKEN_BYTES = 32;
-var enc = new TextEncoder();
-async function digest(token) {
-  const d = await crypto.subtle.digest("SHA-256", enc.encode(token));
-  return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join("");
-}
-async function createStaticTokenResolver(tokens) {
-  const byDigest = /* @__PURE__ */ new Map();
-  for (const [token, principal] of Object.entries(tokens)) {
-    if (enc.encode(token).length < MIN_TOKEN_BYTES) throw new Error(`tokens must hold at least ${MIN_TOKEN_BYTES} bytes`);
-    byDigest.set(await digest(token), principalSchema.parse(principal));
+var SCOPES = {
+  /** List, read, count, digest, read preferences, export. */
+  read: "notify:read",
+  /** Mark read, change preferences. */
+  write: "notify:write",
+  /** Erase all data held about the caller. */
+  erase: "notify:admin",
+  /** Notify someone else. */
+  send: "notify-send:write"
+};
+function recipientOf(context) {
+  switch (context.kind) {
+    case "human":
+      return { kind: "human", id: context.principalId };
+    case "user_token": {
+      const root = context.chain[0];
+      if (!root || root.kind !== "human") throw new RangeError("a user token needs a person at the root of its chain");
+      return { kind: "human", id: root.id };
+    }
+    case "agent":
+    case "agent_of_human":
+    case "agent_of_agent":
+      return { kind: "agent", id: context.principalId };
+    default:
+      throw new RangeError("unknown principal kind");
   }
-  if (byDigest.size === 0) throw new Error("no tokens configured");
-  return async (request) => {
-    const m = /^Bearer ([^\s]+)$/.exec(request.headers.get("authorization") ?? "");
-    return m ? byDigest.get(await digest(m[1])) ?? null : null;
-  };
 }
 
 // src/api.ts
-var sendBody = z2.object({ recipient: recipientSchema, type: typeNameSchema, resource: resourceRefSchema, body: z2.string().max(2e3) }).strict();
-var num = z2.coerce.number().int().nonnegative();
+function invalidInput(path, message) {
+  return z.string().refine(() => false, { message, path }).safeParse("").error;
+}
+var sendBody = z.object({ recipient: recipientSchema, type: typeNameSchema, resource: resourceRefSchema, body: z.string().max(2e3) }).strict();
+var num = z.coerce.number().int().nonnegative();
 function createApp(options) {
   const { notifier } = options;
-  const authorizeSend = options.authorizeSend ?? ((p) => p.canSend === true);
+  const authorizeSend = options.authorizeSend ?? (() => true);
   const app = new Hono();
   app.get("/health", (c) => c.json({ ok: true }));
   const api = new Hono();
   api.use("*", bodyLimit({ maxSize: 64 * 1024, onError: (c) => c.json({ error: "too_large" }, 413) }));
-  api.use("*", async (c, next) => {
-    const raw = await options.resolvePrincipal(c.req.raw);
-    const parsed = principalSchema.safeParse(raw);
-    if (!parsed.success) return c.json({ error: "unauthorized" }, 401);
-    c.set("principal", parsed.data);
-    c.set("me", { kind: parsed.data.kind, id: parsed.data.id });
+  const guard = (scope) => async (c, next) => {
+    const who = await requirePrincipal(c.req.raw, options.auth, { scope });
+    if (who instanceof Response) return who;
+    c.set("principal", who);
+    c.set("me", recipientOf(who));
     await next();
-  });
+  };
   async function json2(c) {
     try {
       return await c.req.json();
     } catch {
-      throw new ZodError([{ code: "custom", path: [], message: "body must be JSON" }]);
+      throw invalidInput([], "body must be JSON");
     }
   }
-  api.get("/notifications", async (c) => {
+  api.get("/notifications", guard(SCOPES.read), async (c) => {
     const q = c.req.query();
-    const limit = q.limit === void 0 ? void 0 : z2.coerce.number().int().min(1).parse(q.limit);
+    const limit = q.limit === void 0 ? void 0 : z.coerce.number().int().min(1).parse(q.limit);
     try {
       return c.json(await notifier.list(c.var.me, { unreadOnly: q.unread === "1" || q.unread === "true", limit, cursor: q.cursor }));
     } catch (error) {
-      if (error instanceof RangeError) throw new ZodError([{ code: "custom", path: ["cursor"], message: "bad cursor" }]);
+      if (error instanceof RangeError) throw invalidInput(["cursor"], "bad cursor");
       throw error;
     }
   });
-  api.post("/notifications", async (c) => {
+  api.post("/notifications", guard(SCOPES.send), async (c) => {
     const input = sendBody.parse(await json2(c));
     if (!await authorizeSend(c.var.principal, input.recipient)) return c.json({ error: "forbidden" }, 403);
     const full = { ...input, actor: c.var.me };
@@ -87,18 +92,22 @@ function createApp(options) {
     const deliveries = sent.channels.filter((channel) => channel !== "inbox").map((channel) => ({ channel, ok: false, skipped: "no_channel" }));
     return c.json({ ...sent, deliveries }, 201);
   });
-  api.post("/notifications/read-all", async (c) => c.json({ marked: await notifier.markAllRead(c.var.me) }));
-  api.get("/notifications/:id", async (c) => c.json(await notifier.get(c.var.me, c.req.param("id"))));
-  api.post("/notifications/:id/read", async (c) => c.json(await notifier.markRead(c.var.me, c.req.param("id"))));
-  api.get("/unread-count", async (c) => c.json({ count: await notifier.unreadCount(c.var.me) }));
-  api.get("/digest", async (c) => {
+  api.post("/notifications/read-all", guard(SCOPES.write), async (c) => c.json({ marked: await notifier.markAllRead(c.var.me) }));
+  api.get("/notifications/:id", guard(SCOPES.read), async (c) => c.json(await notifier.get(c.var.me, c.req.param("id"))));
+  api.post("/notifications/:id/read", guard(SCOPES.write), async (c) => c.json(await notifier.markRead(c.var.me, c.req.param("id"))));
+  api.get("/unread-count", guard(SCOPES.read), async (c) => c.json({ count: await notifier.unreadCount(c.var.me) }));
+  api.get("/digest", guard(SCOPES.read), async (c) => {
     const since = c.req.query("since");
     return c.json(await notifier.digest(c.var.me, since === void 0 ? 0 : num.parse(since)));
   });
-  api.get("/preferences", async (c) => c.json(await notifier.getPreferences(c.var.me)));
-  api.put("/preferences", async (c) => c.json(await notifier.setPreferences(c.var.me, preferencesSchema.parse(await json2(c)))));
-  api.get("/me/export", async (c) => c.json(await notifier.exportData(c.var.me)));
-  api.delete("/me", async (c) => c.json(await notifier.erase(c.var.me)));
+  api.get("/preferences", guard(SCOPES.read), async (c) => c.json(await notifier.getPreferences(c.var.me)));
+  api.put("/preferences", guard(SCOPES.write), async (c) => c.json(await notifier.setPreferences(c.var.me, preferencesSchema.parse(await json2(c)))));
+  api.get("/me/export", guard(SCOPES.read), async (c) => c.json(await notifier.exportData(c.var.me)));
+  api.delete("/me", guard(SCOPES.erase), async (c) => c.json(await notifier.erase(c.var.me)));
+  api.all("*", async (c) => {
+    const who = await requirePrincipal(c.req.raw, options.auth);
+    return who instanceof Response ? who : c.json({ error: "not_found" }, 404);
+  });
   app.route("/api/v1", api);
   app.notFound((c) => c.json({ error: "not_found" }, 404));
   app.onError((error, c) => {
@@ -113,7 +122,7 @@ function createApp(options) {
 }
 
 // src/worker.ts
-import { parseRegion } from "agentic-identity";
+import { createStoreAuth, parseRegion } from "agentic-identity";
 import { createD1Store, D1_SCHEMA } from "agentic-identity/cloudflare";
 function json(value, status = 200) {
   return new Response(JSON.stringify(value), { status, headers: { "content-type": "application/json" } });
@@ -132,16 +141,17 @@ function createWorker(config) {
     const days = env.NOTIFY_RETENTION_DAYS === void 0 ? void 0 : Number(env.NOTIFY_RETENTION_DAYS);
     const store = createD1Store(env.DB, { region: parseRegion(env.NOTIFY_REGION ?? "eu") });
     await store.query(NOTES, { limit: 1 });
-    return createNotifier({
+    const notifier = createNotifier({
       store,
       retentionMs: days === void 0 ? void 0 : days * 864e5
     });
+    return { notifier, store };
   }
   async function build(env) {
-    const resolvePrincipal = await config.resolver(env);
-    const notifier = resolvePrincipal ? await buildNotifier(env) : null;
-    if (!resolvePrincipal || !notifier) return null;
-    return createApp({ notifier, resolvePrincipal, authorizeSend: config.authorizeSend });
+    const built = await buildNotifier(env);
+    if (!built) return null;
+    const auth = config.auth ? config.auth(env, built.store) : createStoreAuth(built.store);
+    return createApp({ notifier: built.notifier, auth, authorizeSend: config.authorizeSend });
   }
   return {
     async fetch(request, env) {
@@ -164,16 +174,11 @@ function createWorker(config) {
     },
     /** Delete notifications past the retention window. Wire to a cron trigger. */
     async scheduled(_event, env) {
-      await (await buildNotifier(env))?.sweep();
+      await (await buildNotifier(env))?.notifier.sweep();
     }
   };
 }
-var worker_default = createWorker({
-  async resolver(env) {
-    if (!env.NOTIFY_TOKENS) return null;
-    return createStaticTokenResolver(JSON.parse(env.NOTIFY_TOKENS));
-  }
-});
+var worker_default = createWorker({});
 export {
   createWorker,
   worker_default as default

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-notify",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Notifications for humans and agents: in-app inbox, webhook and email delivery, with SDK, CLI, MCP server and Worker API.",
   "keywords": [
     "notifications",
@@ -65,10 +65,10 @@
     "check:worker": "esbuild src/worker.ts --bundle --platform=neutral --format=esm --log-level=warning --outfile=node_modules/.cache/worker-check.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "agentic-identity": "^0.4.0",
+    "@modelcontextprotocol/sdk": "^1.23.0",
+    "agentic-identity": "^0.7.0",
     "hono": "^4.13.14",
-    "zod": "^3.25.0"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/dist/types-C842YAMe.d.ts

@@ -1,217 +0,0 @@
-import { z } from 'zod';
-
-declare const CHANNELS: readonly ["inbox", "webhook", "email"];
-type Channel = (typeof CHANNELS)[number];
-declare const recipientSchema: z.ZodObject<{
-    kind: z.ZodEnum<["human", "agent"]>;
-    id: z.ZodString;
-}, "strict", z.ZodTypeAny, {
-    id: string;
-    kind: "human" | "agent";
-}, {
-    id: string;
-    kind: "human" | "agent";
-}>;
-type Recipient = z.infer<typeof recipientSchema>;
-declare const resourceRefSchema: z.ZodObject<{
-    kind: z.ZodString;
-    id: z.ZodString;
-    url: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-}, "strict", z.ZodTypeAny, {
-    id: string;
-    kind: string;
-    url?: string | undefined;
-}, {
-    id: string;
-    kind: string;
-    url?: string | undefined;
-}>;
-type ResourceRef = z.infer<typeof resourceRefSchema>;
-declare const actorSchema: z.ZodObject<{
-    kind: z.ZodEnum<["human", "agent"]>;
-    id: z.ZodString;
-}, "strict", z.ZodTypeAny, {
-    id: string;
-    kind: "human" | "agent";
-}, {
-    id: string;
-    kind: "human" | "agent";
-}>;
-type Actor = z.infer<typeof actorSchema>;
-declare const notificationSchema: z.ZodObject<{
-    id: z.ZodString;
-    recipient: z.ZodObject<{
-        kind: z.ZodEnum<["human", "agent"]>;
-        id: z.ZodString;
-    }, "strict", z.ZodTypeAny, {
-        id: string;
-        kind: "human" | "agent";
-    }, {
-        id: string;
-        kind: "human" | "agent";
-    }>;
-    type: z.ZodString;
-    resource: z.ZodObject<{
-        kind: z.ZodString;
-        id: z.ZodString;
-        url: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-    }, "strict", z.ZodTypeAny, {
-        id: string;
-        kind: string;
-        url?: string | undefined;
-    }, {
-        id: string;
-        kind: string;
-        url?: string | undefined;
-    }>;
-    actor: z.ZodObject<{
-        kind: z.ZodEnum<["human", "agent"]>;
-        id: z.ZodString;
-    }, "strict", z.ZodTypeAny, {
-        id: string;
-        kind: "human" | "agent";
-    }, {
-        id: string;
-        kind: "human" | "agent";
-    }>;
-    body: z.ZodString;
-    createdAt: z.ZodNumber;
-    readAt: z.ZodNullable<z.ZodNumber>;
-}, "strict", z.ZodTypeAny, {
-    type: string;
-    id: string;
-    recipient: {
-        id: string;
-        kind: "human" | "agent";
-    };
-    resource: {
-        id: string;
-        kind: string;
-        url?: string | undefined;
-    };
-    actor: {
-        id: string;
-        kind: "human" | "agent";
-    };
-    body: string;
-    createdAt: number;
-    readAt: number | null;
-}, {
-    type: string;
-    id: string;
-    recipient: {
-        id: string;
-        kind: "human" | "agent";
-    };
-    resource: {
-        id: string;
-        kind: string;
-        url?: string | undefined;
-    };
-    actor: {
-        id: string;
-        kind: "human" | "agent";
-    };
-    body: string;
-    createdAt: number;
-    readAt: number | null;
-}>;
-type Notification = z.infer<typeof notificationSchema>;
-declare const sendInputSchema: z.ZodObject<{
-    recipient: z.ZodObject<{
-        kind: z.ZodEnum<["human", "agent"]>;
-        id: z.ZodString;
-    }, "strict", z.ZodTypeAny, {
-        id: string;
-        kind: "human" | "agent";
-    }, {
-        id: string;
-        kind: "human" | "agent";
-    }>;
-    type: z.ZodString;
-    resource: z.ZodObject<{
-        kind: z.ZodString;
-        id: z.ZodString;
-        url: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
-    }, "strict", z.ZodTypeAny, {
-        id: string;
-        kind: string;
-        url?: string | undefined;
-    }, {
-        id: string;
-        kind: string;
-        url?: string | undefined;
-    }>;
-    actor: z.ZodObject<{
-        kind: z.ZodEnum<["human", "agent"]>;
-        id: z.ZodString;
-    }, "strict", z.ZodTypeAny, {
-        id: string;
-        kind: "human" | "agent";
-    }, {
-        id: string;
-        kind: "human" | "agent";
-    }>;
-    body: z.ZodString;
-}, "strict", z.ZodTypeAny, {
-    type: string;
-    recipient: {
-        id: string;
-        kind: "human" | "agent";
-    };
-    resource: {
-        id: string;
-        kind: string;
-        url?: string | undefined;
-    };
-    actor: {
-        id: string;
-        kind: "human" | "agent";
-    };
-    body: string;
-}, {
-    type: string;
-    recipient: {
-        id: string;
-        kind: "human" | "agent";
-    };
-    resource: {
-        id: string;
-        kind: string;
-        url?: string | undefined;
-    };
-    actor: {
-        id: string;
-        kind: "human" | "agent";
-    };
-    body: string;
-}>;
-type SendInput = z.infer<typeof sendInputSchema>;
-declare const preferencesSchema: z.ZodObject<{
-    channels: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodArray<z.ZodEnum<["inbox", "webhook", "email"]>, "many">, ("inbox" | "webhook" | "email")[], ("inbox" | "webhook" | "email")[]>>;
-    muted: z.ZodBoolean;
-    mutedTypes: z.ZodArray<z.ZodString, "many">;
-}, "strict", z.ZodTypeAny, {
-    channels: Record<string, ("inbox" | "webhook" | "email")[]>;
-    muted: boolean;
-    mutedTypes: string[];
-}, {
-    channels: Record<string, ("inbox" | "webhook" | "email")[]>;
-    muted: boolean;
-    mutedTypes: string[];
-}>;
-type Preferences = z.infer<typeof preferencesSchema>;
-declare const DEFAULT_CHANNELS: readonly Channel[];
-declare function defaultPreferences(): Preferences;
-declare function recipientKey(recipient: Recipient): string;
-interface DigestGroup {
-    type: string;
-    count: number;
-    latest: Notification;
-}
-interface Digest {
-    total: number;
-    groups: DigestGroup[];
-}
-
-export { type Actor as A, type Channel as C, type Digest as D, type Notification as N, type Preferences as P, type Recipient as R, type SendInput as S, type ResourceRef as a, CHANNELS as b, DEFAULT_CHANNELS as c, type DigestGroup as d, defaultPreferences as e, recipientKey as r };