Security model

createHandler(notify, {
  identify: async (request) => {
    const session = await auth(request)
    if (!session) return null // → 401

    return {
      recipientId: session.user.id,
      tenantId: session.orgId,
      workspaceId: session.workspaceId,
    }
  },
})

createHandler(notify, {
  identify: async (request) => {
    const session = await auth(request)
    if (!session) return null
    return {
      recipientId: session.user.id,
      tenantId: session.orgId,
      permissions: session.role === "admin" ? ["admin"] : [],
    }
  },
  // Or use the authorize hook for dynamic checks:
  authorize: async (ctx, permission) => {
    if (permission === "deliveries.list") {
      return ctx.identity.permissions?.includes("admin") ?? false
    }
    return false
  },
})

notification({
  id: "password_changed",
  payload: { email: "string", ip: "string" },
  channels: [inbox({ title: "Password changed from {{ip}}" })],
  redact: ["email", "ip"],
})

// In hooks, timeline, and delivery logs:
// { email: "[REDACTED]", ip: "[REDACTED]" }

// In your notification definition:
channel.webhook({
  url: "https://your-service.com/hooks/notify",
  secret: process.env.WEBHOOK_SECRET, // enables signing
})

// The outgoing request includes:
// x-notifykit-signature: sha256=<hex-encoded HMAC-SHA256 of the body>

import { createHmac, timingSafeEqual } from "crypto"

function verifyWebhookSignature(
  body: string,
  signatureHeader: string | null,
  secret: string
): boolean {
  if (!signatureHeader) return false

  const expected = "sha256=" + createHmac("sha256", secret)
    .update(body)
    .digest("hex")

  // Timing-safe compare prevents timing side-channel attacks
  if (expected.length !== signatureHeader.length) return false
  return timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  )
}

// Example: Express/Hono/Next.js API route
export async function POST(request: Request) {
  const body = await request.text()
  const signature = request.headers.get("x-notifykit-signature")

  if (!verifyWebhookSignature(body, signature, process.env.WEBHOOK_SECRET!)) {
    return new Response("Invalid signature", { status: 401 })
  }

  const payload = JSON.parse(body)
  // Safe to process — signature verified
  await handleNotification(payload)
  return new Response("OK", { status: 200 })
}

createRouteHandler({
  notifykit: notify,
  identify: getIdentity,
  webhooks: {
    resend: (headers, body) => {
      // Verify using provider's signing mechanism
      const signature = headers.get("svix-signature")
      return verifyResendWebhook(body, signature, process.env.RESEND_WEBHOOK_SECRET!)
    },
  },
  onWebhookEvent: async (provider, payload) => {
    // Process verified webhook (delivery status, bounces, opens)
    if (payload.type === "email.bounced") {
      await deactivateRecipientEmail(payload.data.to)
    }
  },
})

createHandler(notify, {
  identify: getIdentity,
  requestRateLimit: {
    max: 60,          // per identity
    windowMs: 60_000, // sliding window
  },
  cors: "https://app.example.com", // or string[]
})

import { createRouteHandler } from "@notifykitjs/next"
import { notify } from "@/lib/notifykit"
import { auth } from "@/lib/auth"

export const { GET, POST, DELETE, OPTIONS, dynamic } = createRouteHandler({
  notifykit: notify,

  // Auth: resolve identity or reject
  identify: async (request) => {
    const session = await auth(request)
    if (!session) return null // → 401

    return {
      recipientId: session.user.id,
      tenantId: session.organizationId,
      workspaceId: session.workspaceId,
      permissions: session.user.role === "admin" ? ["admin"] : [],
    }
  },

  // Admin routes: only admins can list all deliveries
  authorize: async (ctx, permission) => {
    return ctx.identity.permissions?.includes("admin") ?? false
  },

  // Unsubscribe: HMAC-signed links in emails
  unsubscribeSecret: process.env.NOTIFYKIT_SECRET,

  // Rate limiting: 60 requests per minute per identity
  requestRateLimit: {
    max: 60,
    windowMs: 60_000,
  },

  // CORS: only your frontend origin
  cors: process.env.NEXT_PUBLIC_APP_URL!,

  // Notification metadata: require auth to list
  protectNotifications: true,
})

import { createNotifyKit } from "@notifykitjs/core"

export const notify = createNotifyKit({
  // ...notifications, database, providers

  unsubscribe: {
    // Primary secret — used for signing NEW links
    secret: process.env.NOTIFYKIT_SECRET!,

    // Previous secret(s) — verified on incoming unsubscribes
    // but never used for signing new links
    previousSecrets: process.env.NOTIFYKIT_SECRET_OLD
      ? [process.env.NOTIFYKIT_SECRET_OLD]
      : [],

    baseUrl: process.env.NEXT_PUBLIC_APP_URL + "/api/notifykit",
  },
})

import { describe, it, expect } from "vitest"
import { createNotifyKit, memoryAdapter, fakeEmailProvider, createHandler } from "@notifykitjs/core"
import { commentMentioned } from "./notifications"

function setup() {
  const notify = createNotifyKit({
    notifications: [commentMentioned] as const,
    database: memoryAdapter(),
    providers: { email: fakeEmailProvider() },
  })
  return notify
}

describe("security boundaries", () => {
  it("rejects unauthenticated requests with 401", async () => {
    const notify = setup()
    const handler = createHandler(notify, {
      identify: async () => null, // no session
    })

    const res = await handler(new Request("http://localhost/api/notifykit/inbox"))
    expect(res.status).toBe(401)

    const body = await res.json()
    expect(body.code).toBe("UNAUTHENTICATED")
  })

  it("rejects cross-tenant inbox access", async () => {
    const notify = setup()
    await notify.upsertRecipient({ id: "alice", tenantId: "org_a", email: "a@test.com" })
    await notify.send({
      recipientId: "alice",
      tenantId: "org_a",
      notificationId: "comment_mentioned",
      payload: { actorName: "Rey", postUrl: "/p/1" },
    })

    // Handler scoped to org_b — should NOT see org_a's items
    const handler = createHandler(notify, {
      identify: async () => ({ recipientId: "alice", tenantId: "org_b" }),
    })

    const res = await handler(new Request("http://localhost/api/notifykit/inbox"))
    const { data: items } = await res.json()
    expect(items).toHaveLength(0) // ✓ isolated
  })

  it("prevents preference writes to another tenant", async () => {
    const notify = setup()
    await notify.upsertRecipient({ id: "alice", tenantId: "org_a", email: "a@test.com" })

    // Handler scoped to org_b tries to write preferences for org_a
    const handler = createHandler(notify, {
      identify: async () => ({ recipientId: "alice", tenantId: "org_b" }),
    })

    const res = await handler(new Request("http://localhost/api/notifykit/preferences", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        notificationId: "comment_mentioned",
        channels: { email: false },
      }),
    }))

    // Preference is written to org_b scope (the handler's scope), NOT org_a
    // Verify org_a's preferences are untouched
    const prefs = await notify.preferences.list("alice", { tenantId: "org_a" })
    expect(prefs).toHaveLength(0)
  })

  it("rejects forged unsubscribe tokens", async () => {
    const notify = setup()
    const handler = createHandler(notify, {
      identify: async () => ({ recipientId: "alice" }),
      unsubscribeSecret: "real-secret-32-bytes-long-here!!",
    })

    // Forged token
    const res = await handler(new Request(
      "http://localhost/api/notifykit/unsubscribe?token=forged_token_value"
    ))
    expect(res.status).toBe(400)
  })

  it("enforces rate limiting with 429", async () => {
    const notify = setup()
    await notify.upsertRecipient({ id: "alice", email: "a@test.com" })

    const handler = createHandler(notify, {
      identify: async () => ({ recipientId: "alice" }),
      requestRateLimit: { max: 3, windowMs: 60_000 },
    })

    // Fire requests up to the limit
    for (let i = 0; i < 3; i++) {
      const res = await handler(new Request("http://localhost/api/notifykit/inbox"))
      expect(res.status).toBe(200)
    }

    // Next request should be rate-limited
    const blocked = await handler(new Request("http://localhost/api/notifykit/inbox"))
    expect(blocked.status).toBe(429)
    expect(blocked.headers.get("Retry-After")).toBeDefined()
  })
})

describe("authorization", () => {
  function handlerWithRole(role: "user" | "admin") {
    return createHandler(notify, {
      identify: async () => ({
        recipientId: "alice",
        permissions: role === "admin" ? ["admin"] : [],
      }),
      authorize: async (ctx, permission) => {
        if (permission === "deliveries.list") {
          return ctx.identity.permissions?.includes("admin") ?? false
        }
        return true
      },
    })
  }

  it("admin can list deliveries", async () => {
    const handler = handlerWithRole("admin")
    const res = await handler(new Request("http://localhost/api/notifykit/deliveries"))
    expect(res.status).toBe(200)
  })

  it("regular user cannot list deliveries", async () => {
    const handler = handlerWithRole("user")
    const res = await handler(new Request("http://localhost/api/notifykit/deliveries"))
    expect(res.status).toBe(403)
  })

  it("regular user can still access their own inbox", async () => {
    const handler = handlerWithRole("user")
    const res = await handler(new Request("http://localhost/api/notifykit/inbox"))
    expect(res.status).toBe(200)
  })
})