Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(connector): support oauth refs for document imports (#6447)

duyuxuan0518824e9c7ff5e7
diff --git a/openviking/connector/auth.py b/openviking/connector/auth.py
index 77e54e3b0..01977a4a3 100644
--- a/openviking/connector/auth.py
+++ b/openviking/connector/auth.py
@@ -1,6 +1,6 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
-"""Task-scoped access to centrally managed Feishu OAuth credentials."""
+"""Task-scoped access to centrally managed external OAuth credentials."""
import asyncio
import math
@@ -139,6 +139,30 @@ async def project_auth_config(args: Dict[str, Any], ctx: RequestContext) -> Dict
return {"user_access_token": credentials["access_token"], "user_key": user_key.strip()}
+async def document_auth_config(args: Dict[str, Any], ctx: RequestContext) -> Dict[str, Any]:
+ """Resolve enumeration credentials and retain a private reference for child imports."""
+ validate_feishu_auth_args(args)
+ if "auth_config" in args:
+ raise InvalidArgumentError("OAuth references cannot be combined with auth_config.")
+ reference = validate_oauth_ref(args[OAUTH_REF_ARG], ctx.user.user_id)
+ provider = ExternalFeishuToken(reference, ctx.api_key or "")
+ token = await asyncio.to_thread(provider.get_token)
+ return {"lark_access_token": token, OAUTH_REF_ARG: reference}
+
+
+async def confluence_auth_config(args: Dict[str, Any], ctx: RequestContext) -> Dict[str, str]:
+ """Resolve a Confluence OAuth reference into the plugin's Bearer-token config."""
+ if args.get("auth_config") or any(
+ key in args for key in ("access_token", "api_token", "email")
+ ):
+ raise InvalidArgumentError(
+ "OAuth references cannot be combined with explicit Confluence credentials."
+ )
+ reference = validate_oauth_ref(args[OAUTH_REF_ARG], ctx.user.user_id, platform="confluence")
+ provider = ExternalFeishuToken(reference, ctx.api_key or "")
+ return {"access_token": await asyncio.to_thread(provider.get_token)}
+
+
def is_external_feishu_auth(state: Optional[Dict[str, Any]]) -> bool:
return isinstance(state, dict) and state.get("provider") == EXTERNAL_FEISHU_PROVIDER
@@ -150,10 +174,10 @@ class ExternalFeishuToken:
self._url = external_auth_url()
if not self._url:
raise InvalidArgumentError(
- "connector.auth is required for external Feishu authorization."
+ "connector.auth is required for external OAuth authorization."
)
if not api_key:
- raise InvalidArgumentError("External Feishu authorization requires an API key.")
+ raise InvalidArgumentError("External OAuth authorization requires an API key.")
self._reference = reference
self._api_key = api_key
self._client = ConnectorClient("", "", account_id=reference["account_id"])
diff --git a/openviking/connector/delegate.py b/openviking/connector/delegate.py
index 4fba11d8b..e9258ef5d 100644
--- a/openviking/connector/delegate.py
+++ b/openviking/connector/delegate.py
@@ -26,7 +26,12 @@ from urllib.parse import urlsplit
import httpx
-from openviking.connector.auth import OAUTH_REF_ARG, project_auth_config
+from openviking.connector.auth import (
+ OAUTH_REF_ARG,
+ confluence_auth_config,
+ document_auth_config,
+ project_auth_config,
+)
from openviking.connector.client import ConnectorClient
from openviking.connector.routing import (
CONNECTOR_ARGS_AUTH_CONFIG_KEY,
@@ -59,6 +64,7 @@ from openviking_cli.utils import get_logger
logger = get_logger(__name__)
_TOS_BUCKET_PATTERN = re.compile(r"^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$")
+CONNECTOR_DISPLAY_RESOURCE_CONFIG_ARG = "resource_config"
def _safe_http_response(response: httpx.Response) -> Any:
@@ -469,7 +475,9 @@ class ConnectorDelegate:
supported_args = CONNECTOR_SUPPORTED_ARGS.get(
add_type, frozenset()
) | CONNECTOR_CREDENTIAL_ARGS.get(add_type, frozenset())
- unknown_args = sorted(set(connector_args) - supported_args)
+ unknown_args = sorted(
+ set(connector_args) - supported_args - {CONNECTOR_DISPLAY_RESOURCE_CONFIG_ARG}
+ )
if unknown_args:
supported_hint = (
f"supported: {sorted(supported_args)}"
@@ -555,10 +563,14 @@ class ConnectorDelegate:
# semantics, so they travel wholesale through param_config. The
# caller supplies credentials under the reserved args.auth_config
# key, lifted into the top-level auth_config field.
+ display_only_args = {
+ CONNECTOR_ARGS_AUTH_CONFIG_KEY,
+ CONNECTOR_DISPLAY_RESOURCE_CONFIG_ARG,
+ }
forwarded_args = {
key: value
for key, value in (connector_args or {}).items()
- if key != CONNECTOR_ARGS_AUTH_CONFIG_KEY and value is not None
+ if key not in display_only_args and value is not None
}
declared_auth = (connector_args or {}).get(CONNECTOR_ARGS_AUTH_CONFIG_KEY)
if declared_auth is not None and not isinstance(declared_auth, dict):
@@ -572,6 +584,12 @@ class ConnectorDelegate:
if add_type in {"meego", "feishu_project"} and OAUTH_REF_ARG in (connector_args or {}):
auth_config = await project_auth_config(connector_args or {}, ctx)
forwarded_args.pop(OAUTH_REF_ARG, None)
+ if add_type == "feishu_doc" and OAUTH_REF_ARG in (connector_args or {}):
+ auth_config = await document_auth_config(connector_args or {}, ctx)
+ forwarded_args.pop(OAUTH_REF_ARG, None)
+ if add_type == "confluence" and OAUTH_REF_ARG in (connector_args or {}):
+ auth_config = await confluence_auth_config(connector_args or {}, ctx)
+ forwarded_args.pop(OAUTH_REF_ARG, None)
tos_path: Optional[str] = None
param_config: Optional[Dict[str, Any]] = None
diff --git a/openviking/service/resource_service.py b/openviking/service/resource_service.py
index 67cf2fddc..aa83c4a0a 100644
--- a/openviking/service/resource_service.py
+++ b/openviking/service/resource_service.py
@@ -160,6 +160,7 @@ _ADD_RESOURCE_ARGS_RESERVED_FIELDS = frozenset(
)
_ADD_RESOURCE_TRANSIENT_ARGS = frozenset({"tos_signature", "tos_access"})
_ADD_RESOURCE_TAG_MODES = frozenset({"replace", "append", "clear"})
+_DISPLAY_RESOURCE_CONFIG_FIELDS = frozenset({"resource_name", "resource_tag"})
_INTERNAL_INGESTION_FIELDS = frozenset(
{
@@ -208,6 +209,17 @@ class _SourcePlan:
defer_unnamed_target: bool = False
+def _normalized_resource_config(value: Any) -> Dict[str, str]:
+ if not isinstance(value, dict):
+ return {}
+ result: Dict[str, str] = {}
+ for key in _DISPLAY_RESOURCE_CONFIG_FIELDS:
+ item = value.get(key)
+ if isinstance(item, str) and item.strip():
+ result[key] = item.strip()
+ return result
+
+
class ResourceService:
"""Resource management service."""
@@ -1794,7 +1806,10 @@ class ResourceService:
)
processing_mode = normalize_processing_mode(processing_mode)
self._validate_add_resource_tag_policy(tags=tags, tag_mode=tag_mode)
- from openviking.connector.delegate import ConnectorDelegate
+ from openviking.connector.delegate import (
+ CONNECTOR_DISPLAY_RESOURCE_CONFIG_ARG,
+ ConnectorDelegate,
+ )
allowed_reserved_fields = ConnectorDelegate.supported_args(path, add_type).intersection(
_ADD_RESOURCE_ARGS_RESERVED_FIELDS
@@ -1901,12 +1916,14 @@ class ResourceService:
watch_auth_state = None
create_watch = bool(watch_manager and manage_watch and watch_interval > 0)
if create_watch:
+ connector_watch_auth_args = dict(normalized_args.processor_kwargs)
+ connector_watch_auth_args.pop(CONNECTOR_DISPLAY_RESOURCE_CONFIG_ARG, None)
watch_auth_state = await connector.create_watch_auth_state(
api_key=ctx.api_key or "",
account_id=ctx.account_id,
add_type=resolved[0],
path=path,
- connector_args=normalized_args.processor_kwargs,
+ connector_args=connector_watch_auth_args,
)
connector_watch_processor_kwargs = self._watch_processor_kwargs(
{
@@ -1917,6 +1934,13 @@ class ResourceService:
tags,
tag_mode,
)
+ resource_config = _normalized_resource_config(
+ normalized_args.processor_kwargs.get(CONNECTOR_DISPLAY_RESOURCE_CONFIG_ARG)
+ )
+ if resource_config:
+ connector_watch_processor_kwargs[CONNECTOR_DISPLAY_RESOURCE_CONFIG_ARG] = (
+ resource_config
+ )
on_success: Optional[Callable[[Optional[Dict[str, Any]]], Awaitable[None]]] = None
on_complete: Optional[
Callable[[str, Optional[str], Optional[str]], Awaitable[None]]
@@ -2030,6 +2054,8 @@ class ResourceService:
# target alone: many imports share one folder, so the native
# "watch_interval=0 cancels the watch" rule would pause it as a side
# effect. Connector watches are paused or deleted only via the watches API.
+ if create_watch:
+ result["watch_id"] = watch_task_id
return result
from openviking.parse.accessors.feishu_accessor import FeishuAccessor
diff --git a/tests/connector/test_auth.py b/tests/connector/test_auth.py
index acb6f54eb..06f695b4e 100644
--- a/tests/connector/test_auth.py
+++ b/tests/connector/test_auth.py
@@ -287,3 +287,31 @@ async def test_project_credentials_use_account_identity_and_validate_reference(m
fetch.return_value = {"access_token": "token", "account": account}
with pytest.raises(InternalError, match="user key"):
await auth.project_auth_config(args, ctx)
+
+
+async def test_confluence_credentials_use_bearer_token_and_validate_reference(monkeypatch):
+ ctx = SimpleNamespace(user=SimpleNamespace(user_id="alice"), api_key="caller-key")
+ reference = {**REFERENCE, "platform": "confluence"}
+ fetch = Mock(return_value={"access_token": " token ", "expires_at": 4102444800})
+ monkeypatch.setattr(ConnectorClient, "get_oauth_access_token", fetch)
+ args = {auth.OAUTH_REF_ARG: reference}
+
+ assert await auth.confluence_auth_config(args, ctx) == {"access_token": "token"}
+
+ fetch.assert_called_once_with(auth.external_auth_url(), "caller-key", reference)
+ assert args == {auth.OAUTH_REF_ARG: reference}
+ with pytest.raises(InvalidArgumentError):
+ auth.validate_oauth_ref(reference, "alice")
+ for invalid in (None, REFERENCE, {**reference, "ov_user_id": "bob"}):
+ with pytest.raises(InvalidArgumentError):
+ await auth.confluence_auth_config({auth.OAUTH_REF_ARG: invalid}, ctx)
+ for extra in (
+ {"auth_config": {"api_token": "token"}},
+ {"access_token": "token"},
+ {"api_token": "token"},
+ {"email": "[email protected]"},
+ ):
+ with pytest.raises(InvalidArgumentError):
+ await auth.confluence_auth_config({**args, **extra}, ctx)
+ assert fetch.call_count == 1
diff --git a/tests/service/test_resource_service_connector.py b/tests/service/test_resource_service_connector.py
index dc0db6ef3..9f6774caa 100644
--- a/tests/service/test_resource_service_connector.py
+++ b/tests/service/test_resource_service_connector.py
@@ -12,7 +12,7 @@ from unittest.mock import AsyncMock, Mock
import httpx
import pytest
-from openviking.connector import delegate as connector_delegate_module
+from openviking.connector import auth, delegate as connector_delegate_module
from openviking.parse.mode import ParseMode
from openviking.resource.watch_manager import WatchManager
from openviking.resource.watch_scheduler import WatchScheduler
@@ -142,6 +142,48 @@ def _install_connector_dependencies(
monkeypatch.setattr(connector_delegate_module.asyncio, "create_task", discard_monitor)
+async def test_feishu_document_connector_separates_private_auth(
+ monkeypatch,
+ connector_config,
+ ctx,
+ service,
+):
+ reference = {
+ "account_id": "external",
+ "user_id": "owner",
+ "ov_user_id": "alice",
+ "type": "oauth",
+ "platform": "feishu_doc",
+ }
+ connector_config.allowed_add_types.append("feishu_doc")
+ client = SimpleNamespace(submit_doc_add=AsyncMock(return_value={"task_key": "C1"}))
+ _install_connector_dependencies(monkeypatch, _task_tracker(), client)
+ resolve = AsyncMock(
+ return_value={"lark_access_token": "secret", "openviking_oauth_ref": reference}
+ )
+ monkeypatch.setattr(connector_delegate_module, "document_auth_config", resolve)
+ args = {
+ "urls": [{"obj_type": "wiki", "obj_token": "W1", "include_child": True}],
+ "openviking_oauth_ref": reference,
+ }
+ result = await service.add_resource(
+ path="https://team.feishu.cn/wiki/W1",
+ ctx=ctx,
+ add_type="feishu_doc",
+ to="viking://resources/docs",
+ args=args,
+ )
+ assert result["task_id"] == "task-1"
+ payload = client.submit_doc_add.await_args.kwargs
+ assert payload["add_type"] == "feishu_doc"
+ assert payload["param_config"]["urls"][0]["include_child"] is True
+ assert "openviking_oauth_ref" not in payload["param_config"]
+ assert payload["auth_config"]["lark_access_token"] == "secret"
+ assert "secret" not in str(payload["param_config"])
+ resolve.assert_awaited_once()
+
+
@pytest.mark.asyncio
@pytest.mark.parametrize(
("path", "tos_path"),
@@ -239,12 +281,19 @@ async def test_connector_watch_stores_only_encrypted_replay_state(
monkeypatch.setattr(service._connector, "_monitor", complete_monitor)
- await service.add_resource(
+ result = await service.add_resource(
path="tos://bucket/docs/",
ctx=ctx,
to="viking://resources/x/y",
watch_interval=5,
- args={"tos_prefix": ["tos://bucket/docs/"]},
+ args={
+ "tos_prefix": ["tos://bucket/docs/"],
+ "resource_config": {
+ "resource_name": "Team Docs",
+ "resource_tag": "tos_docs",
+ "ignored": "value",
+ },
+ },
)
task = await watch_manager.get_task_by_uri(
@@ -254,6 +303,7 @@ async def test_connector_watch_stores_only_encrypted_replay_state(
role=str(Role.USER),
)
assert task is not None
+ assert result["watch_id"] == task.task_id
assert task.is_active is True
assert task.last_status is None
background_tasks = list(service._background_tasks)
@@ -263,6 +313,14 @@ async def test_connector_watch_stores_only_encrypted_replay_state(
assert task.last_status == "completed"
assert task.last_task_id == "task-1"
assert task.source_type == "tos"
+ assert task.processor_kwargs["resource_config"] == {
+ "resource_name": "Team Docs",
+ "resource_tag": "tos_docs",
+ }
+ assert task.to_dict()["processor_kwargs"]["resource_config"] == {
+ "resource_name": "Team Docs",
+ "resource_tag": "tos_docs",
+ }
assert task.auth_state["provider"] == "connector_encrypted"
assert "secret" not in json.dumps(task.auth_state)
assert "auth_state" not in task.to_dict()
@@ -275,6 +333,9 @@ async def test_connector_watch_stores_only_encrypted_replay_state(
"tos",
{"tos_prefix": ["tos://bucket/docs/"]},
)
+ assert connector_client.submit_doc_add.await_args.kwargs["param_config"] == {
+ "tos_prefix": ["tos://bucket/docs/"]
+ }
@pytest.mark.asyncio
@@ -1826,6 +1887,7 @@ async def test_git_credentials_with_include_never_enqueue_native_job(
)
async def test_native_git_enqueue_rejects_credentials_before_durable_job(
monkeypatch,
+ connector_config,
ctx,
service,
credential_args,
@@ -1986,7 +2048,7 @@ async def test_native_git_watch_refresh_queues_with_restored_task_auth(
@pytest.mark.asyncio
async def test_native_git_rejects_malformed_nested_auth_without_secret_in_error(
- monkeypatch, ctx, service
+ monkeypatch, connector_config, ctx, service
):
monkeypatch.setattr(resource_service_module, "is_git_repo_url", lambda _path: True)
service._connector.should_delegate = Mock(return_value=False)
@@ -2756,6 +2818,63 @@ async def test_declared_add_type_routes_generic_type_to_connector(
assert "s3cret" not in str(info_log.call_args_list)
[email protected]("with_oauth_ref", [False, True])
+async def test_confluence_uses_oauth_ref_only_when_present(
+ monkeypatch,
+ connector_config,
+ ctx,
+ service,
+ with_oauth_ref,
+):
+ connector_config.allowed_add_types = ["confluence"]
+ connector_config.auth = "https://connector.example/oauth/access_token"
+ tracker = _task_tracker()
+ connector_client = SimpleNamespace(
+ submit_doc_add=AsyncMock(return_value={"task_key": "connector-1"})
+ )
+ _install_connector_dependencies(monkeypatch, tracker, connector_client)
+ reference = {
+ "account_id": "cloud-account",
+ "user_id": "cloud-user",
+ "ov_user_id": "alice",
+ "platform": "confluence",
+ "type": "oauth",
+ }
+ fetch = Mock(return_value={"access_token": " oauth-token ", "expires_at": 4102444800})
+ monkeypatch.setattr(auth.ConnectorClient, "get_oauth_access_token", fetch)
+ args = {
+ "cloud_id": "cloud-1",
+ "resources": [{"type": "page", "id": "123"}],
+ }
+ expected_auth = {"email": "[email protected]", "api_token": "api-token"}
+ if with_oauth_ref:
+ args[auth.OAUTH_REF_ARG] = reference
+ else:
+ args["auth_config"] = expected_auth
+
+ await service.add_resource(
+ path="https://example.atlassian.net/wiki/spaces/ENG/pages/123/Page",
+ ctx=ctx,
+ add_type="confluence",
+ to="viking://resources/kb/confluence",
+ args=args,
+ )
+
+ request = connector_client.submit_doc_add.await_args.kwargs
+ assert request["param_config"] == {
+ "cloud_id": "cloud-1",
+ "resources": [{"type": "page", "id": "123"}],
+ "path": "https://example.atlassian.net/wiki/spaces/ENG/pages/123/Page",
+ }
+ if with_oauth_ref:
+ assert request["auth_config"] == {"access_token": "oauth-token"}
+ fetch.assert_called_once_with(connector_config.auth, ctx.api_key, reference)
+ else:
+ assert request["auth_config"] == expected_auth
+ fetch.assert_not_called()
+
+
@pytest.mark.asyncio
async def test_declared_registry_type_routes_like_probed(
monkeypatch,
@@ -2943,3 +3062,61 @@ async def test_project_oauth_dispatch_and_watch_replay(
path=path, ctx=ctx, add_type=add_type, to="viking://resources/kb/project", args=args
)
assert client.submit_doc_add.await_count == 2
+
+
+def _feishu_oauth_reference(**changes):
+ return {
+ "account_id": "external",
+ "user_id": "owner",
+ "ov_user_id": "alice",
+ "type": "oauth",
+ "platform": "feishu_doc",
+ **changes,
+ }
+
+
+def _feishu_request_context():
+ return RequestContext(
+ user=UserIdentifier("kernel", "alice"),
+ role=Role.USER,
+ api_key="key",
+ )
+
+
+async def test_document_auth_resolves_token_and_retains_only_private_reference(monkeypatch):
+ provider = Mock(get_token=Mock(return_value="token"))
+ factory = Mock(return_value=provider)
+ monkeypatch.setattr(auth, "ExternalFeishuToken", factory)
+ args = {"openviking_oauth_ref": _feishu_oauth_reference()}
+
+ resolved = await auth.document_auth_config(args, _feishu_request_context())
+
+ assert resolved == {
+ "lark_access_token": "token",
+ "openviking_oauth_ref": _feishu_oauth_reference(),
+ }
+ factory.assert_called_once_with(_feishu_oauth_reference(), "key")
+ assert args == {"openviking_oauth_ref": _feishu_oauth_reference()}
+
+
+ "patch",
+ [
+ {"feishu_access_token": "secret"},
+ {"auth_config": {}},
+ {"openviking_oauth_ref": _feishu_oauth_reference(ov_user_id="bob")},
+ {"openviking_oauth_ref": _feishu_oauth_reference(platform="feishu_project")},
+ {"openviking_oauth_ref": {"account_id": "missing"}},
+ ],
+)
+async def test_document_auth_rejects_ambiguous_or_foreign_credentials(patch, monkeypatch):
+ factory = Mock()
+ monkeypatch.setattr(auth, "ExternalFeishuToken", factory)
+ with pytest.raises(InvalidArgumentError):
+ await auth.document_auth_config(
+ {"openviking_oauth_ref": _feishu_oauth_reference(), **patch},
+ _feishu_request_context(),
+ )
+ factory.assert_not_called()