fix(api): 透传 /api/actions 认证会话以避免 getUsers 返回空数据

[WAY29]

Summary

Fix session propagation in /api/actions endpoints to ensure getSession() returns valid data when called from within actions.

Problem

After PR #704 fixed the authentication issue (#687) by adding allowReadOnlyAccess: true to endpoints, a related problem remained: when the action adapter (Hono-based) successfully authenticates a user and the action internally calls getSession(), it returns null because:

1. The adapter layer uses Hono to read Cookie/Authorization headers and calls validateKey()
2. The action layer traditionally relies on next/headers to read request context
3. In certain runtimes, the action cannot access the Next.js headers context, causing getSession() to return null
4. This results in actions returning ok: true but with empty data

Related Issues:

• Follow-up to api使用普通用户的auth-token认证无效 #687 - Addresses remaining session propagation issue after authentication fix
• Follow-up to PR feat(api): 扩展只读密钥访问权限以支持更多端点 #704 - Completes the fix for regular user API access

Solution

Introduce AsyncLocalStorage to propagate the authenticated session from the adapter layer to the action layer:

1. New session storage (auth-session-storage.node.ts): Creates a global AsyncLocalStorage instance for request-scoped session storage
2. Session injection functions (auth.ts): Adds runWithAuthSession() to wrap action execution with session context, and getScopedAuthSession() to retrieve the injected session
3. Priority-based session retrieval: Modifies getSession() to first check for an adapter-injected session before falling back to next/headers
4. Adapter integration (action-adapter-openapi.ts): Wraps authenticated action calls with runWithAuthSession() to inject the validated session

Changes

Core Changes

File	Change
src/lib/auth-session-storage.node.ts	New file: AsyncLocalStorage-based session storage
src/lib/auth.ts	Add runWithAuthSession(), getScopedAuthSession(), and priority check in getSession()
src/lib/api/action-adapter-openapi.ts	Wrap action calls with runWithAuthSession() when authenticated
src/app/api/actions/[...route]/route.ts	Import session storage module to initialize global storage

Test Changes

File	Change
tests/api/action-adapter-auth-session.unit.test.ts	New regression test verifying session propagation

Testing

Automated Tests

• Unit test added: Verifies getSession() returns injected session within action context
• Test mocks next/headers to throw error, ensuring the new path is used

Manual Testing

Verified with curl command:

curl http://localhost:13500/api/actions/users/getUsers \
  --request POST \
  --header 'Content-Type: application/json' \
  --cookie 'auth-token=YOUR_SECRET_TOKEN' \
  --data '{}'

Regular user tokens now return valid user data instead of empty results.

Breaking Changes

None. This is a backwards-compatible fix that improves session handling without changing the API contract.

Checklist

• Code follows project conventions
• Self-review completed
• Tests pass locally
• No breaking changes

---

Description enhanced by Claude AI

Greptile Overview

Greptile Summary

Fixes session propagation in /api/actions endpoints by introducing AsyncLocalStorage-based context passing, ensuring getSession() returns valid data when called from within actions.

Key Changes

• New session storage (auth-session-storage.node.ts): Global AsyncLocalStorage singleton for request-scoped session storage
• Session injection (auth.ts): runWithAuthSession() wraps execution context, getScopedAuthContext() retrieves injected session
• Priority-based retrieval: getSession() checks ALS context first, falls back to next/headers
• Adapter integration: Action calls wrapped with runWithAuthSession() when authenticated
• Permission inheritance: Scoped sessions respect their creation-time allowReadOnlyAccess setting, with support for explicit downgrade

Technical Approach

The solution addresses the runtime incompatibility where actions cannot access Next.js headers() context by:

1. Adapter layer validates credentials via validateKey()
2. Session stored in AsyncLocalStorage before action execution
3. Actions retrieve session from ALS instead of Next.js headers
4. Permission semantics preserved with proper inheritance logic

Test Coverage

Comprehensive unit test verifies:

• Session propagation through ALS
• Correct handling of read-only keys (canLoginWebUi: false)
• Permission downgrade when calling getSession({allowReadOnlyAccess: false})
• Fallback doesn't trigger next/headers in action context

Confidence Score: 5/5

• This PR is safe to merge - it's a well-architected fix with comprehensive test coverage
• Elegant solution using standard Node.js AsyncLocalStorage pattern, proper permission semantics preservation, excellent test coverage, and backwards-compatible implementation with fallback to existing behavior
• No files require special attention - all changes follow established patterns and include proper safeguards

Important Files Changed

Filename	Overview
src/lib/auth-session-storage.node.ts	New file creates AsyncLocalStorage-based session storage using global singleton pattern
src/lib/auth.ts	Adds session injection helpers and priority-based session retrieval with proper permission inheritance
src/lib/api/action-adapter-openapi.ts	Wraps authenticated action calls with session context propagation using runWithAuthSession

Sequence Diagram

sequenceDiagram
    participant Client
    participant Adapter as Hono Adapter
    participant Route as Action Route Handler
    participant Storage as AsyncLocalStorage
    participant Action as Server Action
    participant GetSession as getSession()

    Client->>Adapter: HTTP Request with credentials
    Adapter->>Route: Forward to action route
    
    Route->>Route: validateKey() authenticates user
    
    Route->>Storage: runWithAuthSession(session, fn, opts)
    Storage->>Storage: Store session in ALS context
    Storage->>Action: Execute action function
    
    Action->>GetSession: Call getSession()
    GetSession->>Storage: getScopedAuthContext()
    Storage-->>GetSession: Return context from ALS
    
    Note over GetSession: Priority logic:<br/>1. ALS context (injected)<br/>2. next/headers (fallback)
    
    GetSession->>GetSession: Apply permission downgrade if needed
    
    GetSession-->>Action: Return session or null
    Action-->>Storage: Return result
    Storage-->>Route: Propagate result
    Route-->>Client: HTTP Response

Loading

_{(2/5) Greptile learns from your feedback when you react with thumbs up/down!}

[gemini-code-assist]

Summary of Changes

Hello @WAY29, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

此拉取请求旨在修复 /api/actions 接口在某些情况下无法正确返回数据的问题，其根本原因是认证会话在 API 适配器层和业务 action 层之间未能有效传递。通过引入基于 AsyncLocalStorage 的会话透传机制，确保了认证信息在整个请求处理流程中的一致性，从而使 getUsers 等需要认证信息的 action 能够正常工作并返回预期数据。

Highlights

• 引入异步本地存储 (AsyncLocalStorage) 进行会话透传: 为了解决在 /api/actions 路由中认证会话无法正确传递到 action 内部的问题，引入了基于 AsyncLocalStorage 的会话存储机制。这允许在请求的整个异步生命周期中，将认证会话从 API 适配器层传递到业务 action 层。
• 修改认证会话获取逻辑: 更新了 getSession 函数，使其优先从新引入的异步本地存储中获取会话。如果存储中存在会话，则直接使用，避免了在某些运行时环境下因无法访问 next/headers 而导致会话丢失的问题。
• API 适配器集成会话透传: 在 createActionRoute 函数中，当认证成功后，会将验证过的 AuthSession 通过 runWithAuthSession 方法注入到 action 的执行上下文中，确保 action 内部能够正确访问到当前用户的认证信息。
• 新增单元测试: 添加了一个新的单元测试文件，专门验证 /api/actions 适配器在鉴权通过后，action 内部调用 getSession() 能够正确获取到注入的会话，从而避免返回空数据的问题。

Changelog

• src/lib/api/action-adapter-openapi.ts
  • 引入 runWithAuthSession 函数以支持会话透传。
  • 在 createActionRoute 中声明 authSession 变量，用于存储验证后的会话。
  • 在认证成功后，将验证的会话赋值给 authSession。
  • 修改 action 的调用方式，使用 runWithAuthSession 将 authSession 注入到 action 的执行上下文中。
• src/lib/auth-session-storage.node.ts
  • 新增文件，用于实现 Node.js 环境下的 AsyncLocalStorage 会话存储。
  • 定义并初始化全局变量 __cchAuthSessionStorage，作为 AuthSessionStorage 的实例。
• src/lib/auth.ts
  • 定义 AuthSessionStorage 类型，规范会话存储接口。
  • 在 globalThis 中声明 __cchAuthSessionStorage 全局变量。
  • 新增 runWithAuthSession 函数，用于在指定会话上下文中执行回调函数。
  • 新增 getScopedAuthSession 函数，用于获取当前作用域的认证会话。
  • 修改 getSession 函数，使其优先通过 getScopedAuthSession 获取会话，以支持适配器注入的请求级会话。
• tests/api/action-adapter-auth-session.unit.test.ts
  • 新增单元测试文件，验证 api/actions 适配器会话透传功能。
  • 模拟 next/headers 以确保测试中不会意外调用。
  • 测试在 requiresAuth=true 的情况下，action 内部的 getSession() 能正确获取到注入的会话，并返回正确的用户 ID。

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[coderabbitai]

📝 Walkthrough

Walkthrough

在服务器端增加基于 AsyncLocalStorage 的全局作用域认证会话存储，并在 action adapter 中支持在存在认证会话时通过 runWithAuthSession 包装 action 调用；新增单元测试验证会话传播。

Changes

Cohort / File(s)	Summary
认证会话存储基础设施 src/lib/auth-session-storage.node.ts, src/lib/auth.ts	新增服务端 AsyncLocalStorage 实现和全局 AuthSessionStorage 声明；新增类型 ScopedAuthContext、AuthSessionStorage 与函数 runWithAuthSession、getScopedAuthSession、getScopedAuthContext；getSession 优先使用作用域会话。
Action Adapter 集成 src/lib/api/action-adapter-openapi.ts, src/app/api/actions/[...route]/route.ts	在 adapter 中导入并使用 runWithAuthSession：当存在验证后的会话且需要认证时，用 runWithAuthSession 包装 action 调用；另在 route 文件添加对 auth-session-storage 的副作用导入以确保初始化。
测试覆盖 tests/api/action-adapter-auth-session.unit.test.ts	新增单元测试，模拟验证返回的会话并断言在 requiresAuth 情形下会话能被传递到 action（验证 validateKey 调用、action 执行次数和 200 响应）。

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 分钟

Possibly related PRs

• feat(api): 扩展只读密钥访问权限以支持更多端点 #704 — 涉及将 allowReadOnlyAccess 应用于多条路由，与本次对 runWithAuthSession/作用域会话路径的更改在认证/只读控制流层面存在代码关联。

Suggested reviewers

• ding113

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	标题准确地概括了主要变更：修复 /api/actions 端点中的会话传播，使 getSession() 能够返回有效数据。
Description check	✅ Passed	描述详细说明了问题、解决方案和所有受影响的文件，与代码变更完全相关。

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

此拉取请求通过引入基于 AsyncLocalStorage 的认证会话透传机制，有效解决了 /api/actions 认证会话无法正确传递到 getUsers 等内部 action 函数的问题。新增的 runWithAuthSession 和 getScopedAuthSession 函数提供了在不同上下文（如 Hono 适配器和 Next.js getSession）中访问和管理认证会话的统一方式，这是一个很好的改进，提升了 API 的健壮性和可维护性。然而，我们发现 getSession 实现中存在一个高严重性安全漏洞，注入的会话绕过了 allowReadOnlyAccess 检查，可能导致受限的 API 密钥执行未经授权的操作。请务必应用建议的修复，以确保即使从作用域存储中检索会话时，其权限也能得到正确验证。

[github-actions]

Code Review Summary

This PR implements a clean solution to fix session propagation in the /api/actions adapter by using AsyncLocalStorage. The implementation is well-designed with proper defensive coding and adequate test coverage.

PR Size: S

• Lines changed: 169 (167 additions, 2 deletions)
• Files changed: 5

Issues Found

Category	Critical	High	Medium	Low
Logic/Bugs	0	0	0	0
Security	0	0	0	0
Error Handling	0	0	0	0
Types	0	0	0	0
Comments/Docs	0	0	0	0
Tests	0	0	0	0
Simplification	0	0	0	0

Key Implementation Highlights

Correct Use of AsyncLocalStorage: The PR uses Node.js AsyncLocalStorage to propagate authentication sessions from the Hono adapter layer to Server Actions, solving the issue where next/headers is unavailable in the Hono context.

Defensive Fallbacks: The code includes proper fallback logic - if the storage isn't initialized, it safely returns without session propagation. The test verifies this behavior by mocking next/headers to throw, ensuring the scoped session is used.

Type Safety: The type cast in auth-session-storage.node.ts is intentional to create a minimal interface contract, and the actual runtime behavior matches the type definitions.

Test Coverage: The regression test adequately covers the critical path (requiresAuth=true with successful authentication), and the test design correctly validates that the session propagation works by mocking next/headers.cookies() to throw an error.

Review Coverage

• Logic and correctness - Clean
• Security (OWASP Top 10) - Clean
• Error handling - Clean
• Type safety - Clean
• Documentation accuracy - Clean
• Test coverage - Adequate
• Code clarity - Good

---

Automated review by Claude AI