@ appwarden/ 中间软件

核心特征

• 分解整合:通过Discord命令对您的网站进行检疫(/quarantine [un]lock(中文(简体) )
• 即时隔离: 启动时立即将所有访问者重定向到一个锁定页面,以阻止进行中的攻击.
• 非基于内容安全政策(见 特性相容性(中文(简体) ): 在所支持的 Cloudflare 上使用 HTML 重写方式, 部署基于非ce的内容安全政策.
• 最小运行时间: 通过使用可忽略的性能影响 event.waitUntil 状态检查

特性相容性

下表概述了每个平台上有哪些Appwarden功能,包括检疫执行和内容安全政策(CSP)支持(有或没有非ces).

基于nonce的CSP需要HTML重写,并且只能在Cloudflare上提供. Next.js on Cloudflare (OpenNext) 和Vercel Edge Middleware 仅应用 CSP 头并做 没有 支持非切数。 如果您在 Cloudflare 上使用 Next.js, 请使用 Cloudflare 通用中件支持 CSP 非ce .

配置

以下选项通过 Cloudflare 和 Vercel 中间软件包共享 。 你必须 至少提供其中之一 website, (中文(简体) ), api,或 multidomainConfig (只有云雾通用) Appwarden知道哪些要求保护.

appwardenApiToken (必须)

Appwarden API 令牌用于认证向 Appwarden API 提出的请求. 见 API 令牌管理指南 关于创建和 管理你的纪念品.

将此令牌视为一个秘密( 类似于密码): 不要将其承诺用于源控件和存储 在环境变量或秘密管理中进行。 使用 Appwarden 存储 API 令牌 AES-GCM加密,在创建后不显示.

debug (可选)

默认为 false设置为 true (或字符串) "true"在初始设置中进行日志锁检查 和配置问题。 集成稳定后即停产.

appwardenApiHostname (可选)

预留用于内部测试. 保留未设置用于生产 Appwarden API .

bypassPaths (可选)

一连串的路径模式,应该总是通过而不检查锁. 模式匹配 精确的路径和分界线的子路径。 尾声 /* 是可选的.

bypassPaths: ["/health", "/api/health"]

website (可选)

配置网站隔离和CSP.

• lockPageSlug – 站点被锁定时的相对路径重定向. 默认为 /maintenance。 。 。 .

• cspMode - 可选 CSP 模式 : "disabled", (中文(简体) ), "report-only",或 "enforced"。省略时,无 CSP 头被应用.

• cspDirectives - 可选的 CSP 指令对象,或 JSON 字符串. 例如:

  website: {
    lockPageSlug: "/maintenance",
    cspMode: "enforced",
    cspDirectives: {
      "script-src": ["'self'", "{{nonce}}"],
      "style-src": ["'self'", "{{nonce}}"],
    },
  }
  

在指令中添加非ce(参见 特性相容性页:1 "{{nonce}}" 源列表中的占位符.

api (可选)

配置API隔离.

• basePaths – 一系列路径图案,可视为API路径. 默认为 ["/"]。 。 。 .
• response - 当 API 路由锁定时返回的可选响应 :
  • status - 默认为 503
  • body - 默认为 {"error":"Service unavailable"}
  • headers - 可选数组 { name, value }

api: {
  basePaths: ["/api"],
  response: {
    status: 503,
    body: '{"error":"Service unavailable"}',
    headers: [{ name: "Content-Type", value: "application/json" }],
  },
}

multidomainConfig (只有云彩通用,可选)

每个主机名覆盖。 每个键是主机名, 每个值可以覆盖 website, (中文(简体) ), api, (中文(简体) ), bypassPaths,以及 debug。域特有值优先于顶级值.

multidomainConfig: {
  "app.example.com": {
    website: { lockPageSlug: "/maintenance-app" },
  },
  "api.example.com": {
    api: { basePaths: ["/api"] },
  },
}

cacheUrl (仅限Vercel)

缓存提供者的 URL 或连接字符串( 例如 Upstash 或 Vercel Edge Cfig) 将隔离状态保存在您的域。 见 Vercel 集成指南 用于缓存提供者配置细节.

vercelApiToken (仅限Vercel)

Appwarden 用来管理 Vercel Edge Config 缓存提供者的 Vercel API 令牌, 以同步您的域的隔离状态 . 见 Vercel 集成指南 用于缓存提供者配置细节.

Appwarden从未存储或登录您的 Vercel API 令牌; 它仅用于管理您的域的隔离状态缓存 .

安装

与网站兼容 云雾花 或者说 维塞尔。 。 。 .

更多背景和高级配置请见 应用文档。 。 。 .

1. 云层

1.1 通用中件(云花板工人直接使用)

这个 通用中间软件 (单位:千美元)@appwarden/middleware/cloudflare支持Cloudflare上部署的任何网站。 它作为独立的云旗工人部署,并产生额外的使用费。 使用这个通用中间器件最简单的方法是通过我们 建立- 云层- 行动; 见 云花板整合指南 用于工作流程细节。 如果您更愿意管理自己的Cloudflare Worker, 而不是使用 GitHub 动作, 您可以直接使用 @appwarden/middleware/cloudflare 捆绑 :

// src/worker.ts
import { createAppwardenMiddleware } from "@appwarden/middleware/cloudflare"

const appwardenHandler = createAppwardenMiddleware((cloudflare) => ({
  debug: cloudflare.env.DEBUG,
  appwardenApiToken: cloudflare.env.APPWARDEN_API_TOKEN,
  website: {
    lockPageSlug: cloudflare.env.APPWARDEN_LOCK_PAGE_SLUG,
    cspMode: cloudflare.env.CSP_MODE,
    cspDirectives: cloudflare.env.CSP_DIRECTIVES,
  },
  api: {
    basePaths: ["/api"],
  },
  bypassPaths: ["/health"],
}))

export default {
  fetch(request: Request, env: CloudflareEnv, ctx: ExecutionContext) {
    return appwardenHandler(request, env, ctx)
  },
}

见Cloudflare集成文件 appwarden.io (英语) 用于环境变量设置和部署细节.

1.2 云浮框架适配器

如果您正在使用一个支持的框架, 您可以使用特定框架的适配器在应用程序中挂载 Appwarden 。 这种办法不涉及额外费用.

框架适配器还可以同步 Appwarden 管理的锁定页面和 CSP 设置到您的构建中 :

1. 添加一个构建钩, 如 "prebuild": "appwarden-link --fqdn=your.app"
2. 导入 .appwarden/linked/middleware.json
3. 通过调用将生成配置与代码级别覆盖合并 getAppwardenConfiguration(generatedConfig, overrides)

传入的值 overrides 优先于生成的配置.

云层上的天体

// src/middleware.ts
import {
  createAppwardenMiddleware,
  getAppwardenConfiguration,
} from "@appwarden/middleware/cloudflare/astro"
import { sequence } from "astro:middleware"
import { env } from "cloudflare:workers"
import appwardenConfig from "../.appwarden/linked/middleware.json"

const appwarden = createAppwardenMiddleware(() =>
  getAppwardenConfiguration(appwardenConfig, {
    appwardenApiToken: env.APPWARDEN_API_TOKEN,
  }),
)

export const onRequest = sequence(appwarden)

见 天体+ 云花向导 更多细节.

在 Cloudflare 上反应路由器

• 设定 future.v8_middleware: true 在你身边 react-router.config.ts 文件

// app/root.tsx
import {
  createAppwardenMiddleware,
  getAppwardenConfiguration,
} from "@appwarden/middleware/cloudflare/react-router"
import { env } from "cloudflare:workers"
import appwardenConfig from "../.appwarden/linked/middleware.json"

export const middleware = [
  createAppwardenMiddleware(() =>
    getAppwardenConfiguration(appwardenConfig, {
      appwardenApiToken: env.APPWARDEN_API_TOKEN,
    }),
  ),
]

见 反应路由器 + Cloudflare 指南 更多细节.

在云层上开始 TanStack

// start.ts
import {
  createAppwardenMiddleware,
  getAppwardenConfiguration,
} from "@appwarden/middleware/cloudflare/tanstack-start"
import { createMiddleware, createStart } from "@tanstack/react-start"
import { env } from "cloudflare:workers"
import appwardenConfig from "../.appwarden/linked/middleware.json"

const appwardenMiddleware = createMiddleware().server(
  createAppwardenMiddleware(() =>
    getAppwardenConfiguration(appwardenConfig, {
      appwardenApiToken: env.APPWARDEN_API_TOKEN,
    }),
  ),
)

export const startInstance = createStart(() => ({
  requestMiddleware: [appwardenMiddleware],
}))

见 TanStack 启动 + Cloudflare 引导 更多细节.

Next.js on Cloudflare(下个开放)

// middleware.ts or proxy.ts
import {
  createAppwardenMiddleware,
  getAppwardenConfiguration,
} from "@appwarden/middleware/cloudflare/nextjs"
import appwardenConfig from "./.appwarden/linked/middleware.json"

export const config = {
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
}

export default createAppwardenMiddleware((runtime) =>
  getAppwardenConfiguration(appwardenConfig, {
    appwardenApiToken: runtime.env.APPWARDEN_API_TOKEN,
  }),
)

此适配器应用 CSP 仅页眉 在来源前(没有 HTML 重写,没有非ce 注射) 。 非基于CSP( CSP){{nonce}})为 不支持 ; CSP 指令不得包括 {{nonce}}。 。 。 .

2. 韦塞尔

要使用 Appwarden 作为 Vercel Edge Middleware, 请使用 @appwarden/middleware/vercel 捆绑 :

// middleware.ts (Next.js app on Vercel)
import {
  createAppwardenMiddleware,
  getAppwardenConfiguration,
} from "@appwarden/middleware/vercel"

const appwardenMiddleware = createAppwardenMiddleware(
  getAppwardenConfiguration(
    {},
    {
      // Edge Config or Upstash KV URL
      cacheUrl: process.env.APPWARDEN_CACHE_URL!,
      // Required when using Vercel Edge Config
      vercelApiToken: process.env.APPWARDEN_VERCEL_API_TOKEN!,
      appwardenApiToken: process.env.APPWARDEN_API_TOKEN!,
      debug: true,
      website: {
        lockPageSlug: "/maintenance",
        cspMode: "report-only",
        cspDirectives: {
          "default-src": ["'self'"],
        },
      },
      api: {
        basePaths: ["/api"],
      },
      bypassPaths: ["/health"],
    },
  ),
)

export default appwardenMiddleware

非基于CSP( CSP){{nonce}})为 不支持 在Vercel Edge Middleware中; CSP指令不得包括 {{nonce}}。 。 。 .

支持的平台

• Cloudflare上的所有网站
  • 云层上的天体
  • 在 Cloudflare 上反应路由器
  • 在云层上开始 TanStack
  • Next.js on Cloudflare(下个开放)
• Vercel上的所有网站

代理技能

这个仓库的船 TanStack 意图 技术 skills/ 因此编码代理可以发现并应用 Appwarden 安装,配置,以及故障排除指导.

安装后 @appwarden/middleware,配置您的代理以使用这些技能 :

npx @tanstack/intent@latest install

可选的是,安装代理钩,因此编辑被锁定,直到一个技能被加载(Claude Code和Codex):

npx @tanstack/intent@latest hooks install

然后在执行任务时装入特定技能:

npx @tanstack/intent@latest load @appwarden/middleware#appwarden-middleware-get-started

列出现有技能:

npx @tanstack/intent@latest list

捐款

欢迎捐款! 请随意提交拉力请求.

1. 叉子存储器
2. 创建您的特性分支( E)git checkout -b feature/amazing-feature(中文(简体) )
3. 使用 常规武器委员会 格式
   • 此工程将执行带有 content 的信件格式
   • 实例:
     • feat: add new feature
     • fix: resolve issue with X
     • docs: update README
     • chore: update dependencies
     • test: add tests for feature X
4. 推向分行(git push origin feature/amazing-feature(中文(简体) )
5. 打开拉请求

发展

# Install dependencies
pnpm install

# Build the package
pnpm build

# Run tests
pnpm test

警卫

请审查一下我们 安全政策 详细介绍我们如何处理脆弱性和如何报告安全问题.

这个软件包与 npm 信任的出版商一起发布,以防止 npm 令牌被过滤,并启用出处,这为出版软件包及其源代码提供了可核查的链接. 更多信息见 npm 出处文档。 。 。 .

版本依赖性( N)

• 这个项目使用常规承诺和自动发布工具,使版本和更改日志不断更新.
• 补丁发布可能包括错误修正和内部维护或依赖性更新(例如Cloudflare Workers类型,Wrangler,和GitHub Action工具). 新的特性在小版本中被运出.
• 见 CHANGELOG.md 为完整的发布历史.

许可证

这个项目根据麻省理工学院许可证颁发——见 自由主义 详细文件.