larksuite / larksuite/cli

bug: docs +create rejects a valid docx:document grant during local scope validation

Open
#2,727 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug domain/auth domain/doc domain/task
Dominant language
Go
Stars
17.3k
Forks
1.4k
Avg merge
2d 4h
Merged PRs (30d)
105

Description

I encountered a permission error when running docs +create with a user token that has docx:document granted but does not have docx:document:create.

The same token successfully creates documents through both the standard document creation API and the API used by the shortcut. However, docs +create reports that docx:document:create is missing.

CLI version: 1.0.85

Steps to reproduce
  1. Authorize a user token with docx:document.

  2. Check the actual granted scopes and confirm that docx:document:create is absent. Existing authorizations may accumulate scopes, so requesting only the broad scope does not by itself establish this condition.

  3. Run:

    lark-cli docs +create \
      --as user \
      --title "Scope validation test" \
      --doc-format xml
    
Actual behavior

The command exits with code 3, writes the failure to stderr, and leaves stdout empty. Relevant error fields:

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

The same local error occurs with --dry-run.

Expected behavior

docs +create should accept a granted scope that its underlying creation API supports, including docx:document.

Verification

Using the same user token:

Invocation Result
Raw POST /open-apis/docx/v1/documents Document created successfully
Raw POST /open-apis/docs_ai/v1/documents using the shortcut's format/content/extra_param request format Document created successfully
docs +create Rejected by local scope validation

Both temporary test documents were removed after verification. No document contents or credential values are included in this report.

This appears to be a mismatch between the shortcut's declared scope requirements and the permissions accepted by its underlying API. The shortcut requires an exact docx:document:create match, even though the granted docx:document scope is sufficient for the API call.

Potential impact across shortcuts and requested priority

This may affect more than the docx shortcut. I also reproduced a similar mismatch with task +get-my-tasks: a token with task:task:write but without task:task:read successfully calls the raw GET /open-apis/task/v2/tasks endpoint and task tasks list, while the shortcut reports a missing task:task:read scope.

Since shortcuts share local scope-validation machinery, other commands whose APIs accept alternative scopes may also be affected. These false rejections block otherwise authorized workflows and prompt users to grant additional permissions unnecessarily.

Please prioritize investigating and fixing this promptly, including auditing other shortcuts for the same mismatch between local requirements and API-supported alternative scopes.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the shared local scope-validation machinery used by docs +create, then reproduce the documented docx:document case with --dry-run. Compare the shortcut's declared requirements with the scopes accepted by the underlying API, and check task +get-my-tasks for the related mismatch. Done means authorized alternative scopes are accepted without unnecessary grants and affected shortcuts are audited.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
authorization, cli
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.