In quick-start / worker-vars / email-routing (zh + en), explicitly
call out that a Cloudflare-hosted domain with Email Routing + Catch-all
must be set up before deploying, and that subdomains do not inherit
the parent domain's Email Routing. Closes#1004.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Stale localStorage credentials (`jwt` / `auth` / `adminAuth` / `userJwt` /
`access_token`) can be the empty string, the literal string `"undefined"`,
or carry a stray newline / control character left over from an older
build. axios + undici reject these eagerly with `Invalid character in
header content ["Authorization"]`, so every API call crashes client-side
before reaching the worker.
This adds two tiny helpers in `frontend/src/utils/headers.js`:
- `safeHeaderValue(v)` returns the trimmed value when it is a non-empty
string with no control chars (per RFC 7230) and no `"undefined"` /
`"null"` sentinel; otherwise `undefined`.
- `safeBearerHeader(jwt)` wraps a safe JWT with `Bearer `, otherwise
`undefined`.
`apiFetch` builds the headers object incrementally and only sets each
auth header when its value is safe. Missing/unsafe credentials now drop
out cleanly and the worker returns a normal 401, which the existing
`response.status === 401` flow already handles by surfacing the auth
prompt — the same UX users see on a fresh session.
Tests: `frontend/src/utils/__tests__/headers.test.js` adds 9 vitest
cases covering safe input, sentinel strings, control chars (\\n / \\r /
\\t / NUL / 0x1F / DEL), trimming, and `Bearer` construction. Build
(`pnpm build`) and tests (`pnpm test`) both pass.
Co-authored-by: voidborne-d <voidborne.d@agentmail.to>
Co-authored-by: Dream Hunter <dreamhunter2333@gmail.com>
* feat(i18n): enhance locale handling and routing
- Implemented dynamic locale aliases in router configuration.
- Added support for preferred locale storage in global state.
- Improved locale resolution logic in router beforeEach guard.
- Created utility functions for locale management and path manipulation.
- Added tests for locale matching and message extraction.
- Updated Header component to allow language selection.
- Refactored getRouterPathWithLang to utilize new locale utilities.
- Updated Vite configuration to support aliasing for vue-i18n.
- Bumped version numbers across various packages to 1.9.0.
* feat(i18n): update version to 1.8.0 and enhance locale handling
- Updated version numbers across all package.json files to 1.8.0.
- Enhanced locale handling in App.vue by centralizing locale configurations.
- Improved Turnstile component to support dynamic language rendering.
- Refactored i18n utilities to include initial locale setup and empty locale messages.
- Updated i18n.ts to utilize the new locale management structure.
- Added naive-locale.ts for better integration with Naive UI's locale handling.
- Adjusted Header.vue to streamline language selection and locale changes.
- Fixed translations in multiple locale files for consistency and accuracy.
* fix(i18n): address review feedback
* feat(i18n): update default locale to English and enhance language handling in components
* fix(i18n): switch locale selector to dropdown
* docs: add topbar language and github order design spec
* fix(i18n): 修复 Header 语言切换器相关问题，恢复为独立控件并调整样式
* Refactor locale handling in router and add locale-guard utility functions
- Improved locale resolution logic in router by introducing utility functions for better readability and maintainability.
- Added `locale-guard.js` to encapsulate locale-related functions such as getting route locale, resolving locale for navigation, and applying locale navigation state.
- Updated JWT synchronization logic to streamline the handling of JWT from query parameters.
- Modified i18n messages test to check for coverage of registered locale message keys instead of extracting English source messages.
* 删除顶部栏语言和GitHub顺序设计文档
* fix: 修复前端设置初始化时未返回 domains 数组导致的 undefined 错误
* refactor(i18n): consolidate locale infrastructure
* fix(i18n): stabilize locale route switching
* fix(i18n): persist default locale selection
* fix(i18n): 修复前端设置初始化时未返回 domains 数组导致的 undefined 错误，统一按空数组兜底处理
feat(i18n): 添加 locale 别名处理，支持默认语言的重定向
test(i18n): 增加对默认语言别名重定向的测试用例
* refactor: replace useAppI18n with useScopedI18n in multiple components for improved localization management
* fix(tests): 移除不必要的 URL 断言以简化 Passkey 测试
* fix(i18n): 更新语言切换逻辑，确保使用当前语言设置进行路由导航
* fix(i18n): 强制路由切换以确保语言切换后正确导航
* refactor(i18n): 优化消息注册和路由本地化逻辑，移除冗余代码
* refactor(i18n): 拆分 API 文件以优化路由管理，更新语言处理逻辑
* fix: align i18n release notes and frontend test script
* feat: add cf-temp-mail-usage skill and parsed mail API for AI agents
- feat: new /api/parsed_mails and /api/parsed_mail/:id endpoints returning
server-parsed subject/text/html/attachments metadata (reuses commonParseMail)
- feat: add .claude/skills/cf-temp-mail-usage read-only skill so AI agents
(OpenClaw / Codex / Cursor) can consume a mailbox with a user-supplied JWT,
bypassing the Turnstile challenge required for mailbox creation
- refactor: split mails_api/index.ts and admin_api/index.ts into thin route
shells; move business logic into dedicated *_api.ts files
- docs: update README / README_EN / CHANGELOG with agent-email feature and
npx degit install instructions for the skill
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* feat: rename skill to cf-temp-mail-agent-mail, add agent-email docs, fix sender trim
- Rename skill from cf-temp-mail-usage to cf-temp-mail-agent-mail
- Rewrite SKILL.md: parsed API primary, local fallback, prerequisites, multi-agent install
- Add vitepress docs (zh + en) for AI Agent mailbox usage
- Fix leading space in parsed_mail_api sender field via .trim()
- Update README install section with 3 install methods
- Update changelogs (zh + en)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* docs: simplify README agent skill section to one-liner with links
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* feat: add send mail API to skill, credential persistence, remove poll example
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
- Upgrade version to 1.8.0 in all package.json files
- Add cf-temp-mail-release-notify skill with MarkdownV2 Telegram posting
- Optimize docs_deploy.yml to auto-trigger on Tag Build CI completion
- Add v1.8.0 placeholder in CHANGELOG.md and CHANGELOG_EN.md
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
* fix: auto initialize default send balance
* fix: tighten send access auto init flow
* refactor: centralize send balance state
* fix: separate legacy repair from admin control in send balance
Add an `address_sender.source` column to distinguish legacy / auto /
user / admin rows. `ensureDefaultSendBalance` now only repairs rows
with `source IS NULL`, so admin-disabled and user-requested rows are
never overwritten. Admin POST writes tag `source = 'admin'`; new
auto-init inserts tag `'auto'`; `requestSendMailAccess` inserts tag
`'user'`.
Bumps DB_VERSION to v0.0.8 with the usual `PRAGMA table_info` guarded
ALTER, plus a standalone SQL patch under db/.
Adds E2E regressions: legacy repair path, admin-disabled rows stay
disabled across settings and send, send after admin deletion
auto-initializes a fresh row.
* fix: drop runtime legacy repair; backfill source='legacy' on migrate
Pre-v0.0.8 schema cannot distinguish legacy request-send-access
remnants from admin-disabled rows — both share `balance = 0,
enabled = 0`. Letting ensureDefaultSendBalance repair that shape on
upgrade could silently re-enable an admin-disabled row.
Remove the runtime repair path entirely:
- `ensureDefaultSendBalance` now uses `ON CONFLICT(address) DO NOTHING`;
existing rows are never touched.
- The v0.0.8 migration (and the matching SQL patch) backfills every
pre-existing row with `source = 'legacy'`, making pre-migration
state explicitly off-limits to runtime auto-init.
- E2E: flip the legacy test to the negative direction — a
`source='legacy'` zero-balance row stays untouched by settings
reads and send attempts. Harden `resetSenderToLegacy` to return
404 when `meta.changes < 1`.
- Update changelog and docs: legacy/admin-disabled rows must be
restored manually via the admin UI.
* refactor: collapse send balance auto-init to missing-row insert
Per review feedback: the runtime guarantee we actually need is
"create an address_sender row when one is missing, leave existing
rows alone". Once `ensureDefaultSendBalance` switched to
`ON CONFLICT DO NOTHING`, the `source` column, the v0.0.8 migration,
and the `resetSenderToLegacy` test endpoint became dead weight —
the DO NOTHING path already protects admin-disabled and admin-edited
rows without any provenance metadata.
- Drop `address_sender.source` and the v0.0.8 migration; revert
DB_VERSION to v0.0.7. No schema change ships with this PR.
- Strip the `source` field from `ensureDefaultSendBalance`,
`requestSendMailAccess`, and the admin-update path.
- Remove the `/admin/test/reset_sender_to_legacy` test endpoint and
its E2E helper; the negative legacy-repair test it served is no
longer needed because the runtime no longer touches existing rows.
- E2E coverage stays focused on the three guardrails: missing-row
auto-init, admin-disabled rows stay disabled, admin deletion
triggers a fresh re-insert.
- Tighten changelog and docs to "auto-initialize missing rows".
* docs: align common-issues with missing-row-only auto-init
The FAQ entries for "DEFAULT_SEND_BALANCE set but still No balance"
still described the old behaviour of repairing legacy
`balance = 0 && enabled = 0` rows. Rewrite both zh and en rows to
match the current runtime: only addresses with no existing
`address_sender` row get auto-initialised; legacy, admin-disabled,
and admin-edited rows must be restored manually through the admin
console.
* fix: harden send mail form validation
* fix: tighten send mail content checks
* fix: refine send mail empty-content checks
* fix: reset send mail preview state
- Upgrade deps across frontend/worker/pages/vitepress-docs (wrangler 4.82.2, dompurify 3.4.0, resend 6.11.0, etc.)
- Bump version to v1.7.0 in all package.json and worker constants
- Add v1.7.0 CHANGELOG placeholder; move #978/#930 Bug Fixes from v1.6.0 to v1.7.0 (merged after v1.6.0 tag)
- Add upgrade-dependencies skill; translate version-upgrade skill to English
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: normalize address casing for password login
Store new mailbox addresses in lowercase and migrate historical address data so mixed-case password logins can read inbox, sendbox, and settings consistently.
* fix: only lowercase configured address prefixes
Limit the #930 change to prefix normalization and document that existing mixed-case data must be migrated manually by users.
* fix: respect user mail deletion toggle in user center
Hide user mailbox delete actions and block /user_api/mails deletion when ENABLE_USER_DELETE_EMAIL is disabled. Add an e2e regression test and changelog entries for issue #978.
* test: hash user password in mail deletion e2e
Use the same SHA-256 pre-hashed password format as the frontend for the user register/login flow in the mail deletion regression test.
* feat(admin): add IP whitelist (strict allowlist mode) (#920)
- Add enableWhitelist/whitelist fields to IpBlacklistSettings
- Implement three-layer access control: whitelist → blacklist → daily limit
- Whitelist uses exact match for IPv4/IPv6, regex for patterns
- Whitelisted IPs skip blacklist checks (trusted)
- Fail-closed when cf-connecting-ip missing under whitelist mode
- Frontend: independent whitelist toggle + empty list protection
- Backend: backward compatible (old frontends get defaults)
- E2E tests: config validation + runtime behavior
- Docs: CHANGELOG zh/en updated
Closes#920
* fix(admin): address PR review feedback on IP whitelist
- Add IPv4-mapped IPv6 (::ffff:x.x.x.x) exact match in isWhitelisted
- Include error.message in whitelist regex parse failure log
- Include actual/max size in whitelist size limit error message
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(admin): validate whitelist regex on save and preserve existing whitelist on partial update
- Reject invalid regex patterns in whitelist at save time to prevent runtime lockout
- Preserve existing enableWhitelist/whitelist from DB when older clients omit these fields
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(admin): revert P2 - keep simple ?? defaults for backward compat
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(admin): validate whitelist elements are strings before trimming
Prevents 500 error when whitelist contains non-string elements (e.g. numbers, null)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs(admin): add IP blacklist/whitelist documentation (zh + en)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(admin): fix fingerprint blacklist bypass when cf-connecting-ip absent, improve e2e tests
- Split checkBlacklist into checkFingerprintBlacklist (IP-independent) and checkIpAsnBlacklist
- Fingerprint check now runs before the !reqIp early-return to prevent bypass
- Add afterEach reset to config test group, extract RESET_SETTINGS constant
- Strengthen whitelist-blocks test to deterministic 403 assertion
- Add e2e tests: invalid regex rejection, non-string element rejection, fingerprint-blocks-without-IP
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(admin): suppress no-useless-escape lint warning in whitelist regex check
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Subdomains do not inherit Email Routing from the apex domain;
each subdomain must enable Email Routing and configure its own
DNS records and Catch-all rule.
Refs #969
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
D1 caps LIKE/GLOB pattern length at 50 bytes. /admin/address and
/admin/users wrapped the query as `%${query}%` and fed it to LIKE,
so searching by a full email address crashed with "LIKE or GLOB
pattern too complex". Fall back to instr() above the 50-byte
threshold.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* ci: upgrade GitHub Actions to support Node.js 24
- pnpm/action-setup: v4 → v5
- actions/upload-artifact: v4 → v6
- actions/download-artifact: v4 → v6
- sync.yaml: replace inactive aormsby/Fork-Sync-With-Upstream-action with gh repo sync
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* ci: replace softprops/action-gh-release with gh release CLI
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(ci): use gh release upload instead of create for existing releases
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* docs: restructure sidebar, expand FAQ, enhance send mail docs
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: remove specific example domain reference in FAQ per review
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* feat: upgrade version to v1.6.0
- Update version number to 1.6.0 in all package.json files
- Add v1.6.0 placeholder in CHANGELOG.md and CHANGELOG_EN.md
* docs: update release skill to use bilingual format (zh + en collapsed)
* chore: upgrade dependencies
* fix: correct CHANGELOG placeholder position and update version-upgrade skill
* docs: update version-upgrade skill with correct CHANGELOG placeholder position
* feat(mail): support gzip compressed email storage in D1 raw_blob column
Add ENABLE_MAIL_GZIP env var to optionally gzip-compress incoming emails
into a new raw_blob BLOB column, saving D1 storage space. Reading is
backward-compatible: prioritizes raw_blob (decompress) with fallback to
plaintext raw field. Includes DB migration v0.0.7, docs, and changelogs.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: gzip fallback on missing column + decouple resolve from handleListQuery
- email/index.ts: gzip INSERT failure now falls back to plaintext INSERT
instead of silently losing the email (P1: data loss prevention)
- common.ts: add handleMailListQuery for raw_mails-specific list queries
with resolveRawEmailList, keeping handleListQuery generic
- Replace handleListQuery → handleMailListQuery in mails_api, admin_mail_api,
user_mail_api (only raw_mails callers)
- Add e2e test infrastructure: worker-gzip service, wrangler.toml.e2e.gzip,
api-gzip playwright project, mail-gzip.spec.ts with 4 test cases
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: address CodeRabbit review feedback for gzip feature
- Use destructuring in resolveRawEmailRow to truly remove raw_blob key
- Narrow fallback scope: only fallback to plaintext on compression failure
or missing raw_blob column, re-throw other DB errors
- Clean unused imports in e2e gzip test
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: add try-catch in resolveRawEmail to prevent single corrupt blob from failing entire list
A corrupted raw_blob would cause decompressBlob to throw, which with
Promise.all in resolveRawEmailList would reject the entire batch query.
Now catches decompression errors and falls back to row.raw field.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(mail): align sendAdminInternalMail with gzip storage path
sendAdminInternalMail now respects ENABLE_MAIL_GZIP: compresses to
raw_blob when enabled, with fallback to plaintext on failure.
Added e2e test verifying admin internal mail is readable under gzip.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(e2e): match admin internal mail by body content instead of encoded subject
mimetext base64-encodes the Subject header, so the raw MIME string
does not contain the literal subject text. Match on body content
(balance: 99) which is plaintext.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(e2e): add WORKER_GZIP_URL guard and length assertions in gzip tests
Address CodeRabbit feedback:
- Skip gzip tests when WORKER_GZIP_URL is not set to prevent false positives
- Assert results array length before accessing [0] for clearer error messages
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(mail): narrow gzip fallback scope and fix webhook query compatibility
- sendAdminInternalMail: separate compress vs DB error handling, only
fallback to plaintext on compression failure or missing raw_blob
column, rethrow other DB errors (aligns with email/index.ts)
- Webhook test endpoints: use SELECT * instead of explicit raw_blob
column reference, so pre-migration databases don't 500
- Docs/changelog: clarify that db_migration must run before enabling
ENABLE_MAIL_GZIP
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(telegram): use generic Record type for raw_mails query result
Align with other query sites — avoid hardcoding raw_blob in the
TypeScript type annotation so the query works with or without the
column after migration.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(models): add RawMailRow type and unify raw_mails query typing
Add RawMailRow type to models with raw_blob as optional field, replacing
ad-hoc Record<string, unknown> and inline type annotations across
webhook test endpoints, telegram API, and gzip utilities.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
