[nengqi]

Summary

Fixes #2727: When a user token is granted the broader docx:document scope without an explicit docx:document:create grant, lark-cli docs +create --as user is prematurely rejected by local client-side scope validation with:

{
  "ok": false,
  "error": {
    "type": "authorization",
    "subtype": "missing_scope",
    "message": "missing required scope(s): docx:document:create",
    "missing_scopes": ["docx:document:create"]
  }
}

As reported and verified in #2727, the underlying document creation endpoints (POST /open-apis/docx/v1/documents and POST /open-apis/docs_ai/v1/documents) succeed with the same docx:document token. The shortcut's local pre-flight check relied on strict exact-string scope matching, leading to false-positive rejections.

Changes

1. Hierarchy-aware scope fulfillment (internal/auth/scope.go):
   • In MissingScopes, check whether a missing required scope is satisfied by an existing parent scope via isScopeSatisfied and parentScopes.
   • Map docx:document:create, docx:document:readonly, and docx:document:write_only to parent docx:document.
   • Maintain strict directional fulfillment: parent grants satisfy child requirements, but child grants do not satisfy parent requirements.
2. Unit & Integration tests:
   • Extended TestMissingScopes in internal/auth/scope_test.go to test parent-scope satisfaction and directional constraints.
   • Added TestDocsCreate_AcceptsDocxDocumentParentScope in shortcuts/doc/docs_create_test.go to verify end-to-end shortcut execution when the token only has docx:document.

Test plan

• go test -v -run TestDocsCreate_AcceptsDocxDocumentParentScope ./shortcuts/doc (PASS)
• go test -v -run TestMissingScopes ./internal/auth (PASS)
• go test ./cmd/... ./internal/auth/... ./shortcuts/... (PASS)
• make fmt-check (PASS, exit code 0)

Summary by CodeRabbit

• Bug Fixes
  • Document creation, read-only, and write-only actions now recognize the general document scope as sufficient authorization.
  • A specific document action scope does not grant access to the broader document scope.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: f2e7692f-fe94-45db-bdae-67a5189542dc

📥 Commits

Reviewing files that changed from the base of the PR and between 017b19a and efb93c0.

📒 Files selected for processing: 3

• internal/auth/scope.go
• internal/auth/scope_test.go
• shortcuts/doc/docs_create_test.go

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📝 Walkthrough

MissingScopes now accepts the docx:document grant for the create, readonly, and write_only child scopes. Tests cover these mappings and document creation with the parent scope.

Changes: Document Scope Validation

Layer / File(s)	Summary
Scope matching internal/auth/scope.go, internal/auth/scope_test.go	MissingScopes accepts recognized parent scopes for required child scopes. Tests cover the three docx:document child scopes, an unrelated scope, and the reverse parent-child case.
Document creation test shortcuts/doc/docs_create_test.go	A test configures a user credential with docx:document and verifies that document creation succeeds.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to efb93

Document creation with the parent scope is covered by the command test. No merge-blocking issue was identified.

Pre-merge checks: 3 · 2

Failed checks: 2 warnings

Check name	Status	Explanation	Resolution
Linked Issues check		The changes satisfy the primary #2727 docs requirement. MissingScopes now accepts docx:document for the three documented child scopes. Unit coverage checks parent fulfillment and directional const…	Investigate the reported task +get-my-tasks mismatch and other affected shortcuts. Fix each confirmed false rejection and add focused tests, or provide reviewable evidence that the reported alternatives do not require changes.
Docstring Coverage		Docstring coverage is 42.86% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 3 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: accepting the parent docx:document scope during docs create validation.
Description check		The description explains the motivation, lists the implementation and test changes, and reports verification results. It omits the Related Issues section and does not include the template's manual ver…
Out of Scope Changes check		The changed implementation is limited to hierarchy-aware scope validation for the documented docx scopes. The unit and docs-create integration tests directly verify the #2727 behavior and directiona…

Full details: Description check

Explanation

The description explains the motivation, lists the implementation and test changes, and reports verification results. It omits the Related Issues section and does not include the template's manual verification checkbox, but it is otherwise complete and on topic.

Full details: Out of Scope Changes check

Explanation

The changed implementation is limited to hierarchy-aware scope validation for the documented docx scopes. The unit and docs-create integration tests directly verify the #2727 behavior and directional matching. No unrelated product behavior is shown in the supplied changes.

Full details: Linked Issues check

Explanation

The changes satisfy the primary #2727 docs requirement. MissingScopes now accepts docx:document for the three documented child scopes. Unit coverage checks parent fulfillment and directional constraints. The docs-create integration test covers execution with only docx:document. However, #2727 also reports the task +get-my-tasks scope mismatch and requests investigation of other shortcuts. The supplied change summary shows no task-shortcut change or audit evidence.

Resolution

Investigate the reported task +get-my-tasks mismatch and other affected shortcuts. Fix each confirmed false rejection and add focused tests, or provide reviewable evidence that the reported alternatives do not require changes.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}