源码快照 @ 2026-09-02 (source-only, 剔除非源码素材)
This commit is contained in:
commit
04bac1f6e2
2200 files changed
+489415
No files matched your search
@@ -0,0 +1,104 @@
|
||||
# `@openwork/enterprise-mcp-client`
|
||||
|
||||
Reference implementation for server-side remote MCP consumption in OpenWork.
|
||||
|
||||
The package owns the provider-neutral MCP/OAuth lifecycle. A composition root
|
||||
supplies networking, persistence, tenancy/authorization, diagnostics, and the
|
||||
clock. Den is one adapter; it is not embedded in the package architecture.
|
||||
|
||||
Den uses this package as its single runtime for new and existing MCP
|
||||
connections. Existing OAuth registrations retain their stored callback URL;
|
||||
new registrations use Den's deployment-wide shared callback.
|
||||
|
||||
## Reference architecture
|
||||
|
||||
```text
|
||||
Den routes and capability authorization composition root
|
||||
│
|
||||
▼
|
||||
enterprise MCP client API application package
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
network OAuth ports diagnostics injected contracts
|
||||
│ │
|
||||
▼ ▼
|
||||
guarded fetch encrypted Den DB adapter infrastructure adapters
|
||||
```
|
||||
|
||||
Dependency direction always points inward. The package does not import Den
|
||||
routes, database schemas, organization/member types, deployment configuration,
|
||||
or environment variables.
|
||||
|
||||
The public OAuth persistence contract is split into three narrow ports:
|
||||
|
||||
- `clientRegistrations`: validated pre-registered or dynamically registered
|
||||
clients with an opaque compare-and-swap revision and explicit expiry;
|
||||
- `authorizations`: state-bound, expiring PKCE transactions that are loaded
|
||||
without consumption; and
|
||||
- `credentials`: token load/save/invalidation, including an atomic callback
|
||||
commit that consumes the matching authorization transaction.
|
||||
|
||||
Every persistence write receives an absolute `commitExpiresAt` and abort
|
||||
signal. An adapter must reject or roll back a transaction that cannot commit
|
||||
inside that lifecycle. This prevents the system from reporting a timeout and
|
||||
then silently writing credentials afterward.
|
||||
|
||||
## Security invariants
|
||||
|
||||
- Outbound `fetch` is mandatory injection. There is no global-fetch fallback.
|
||||
Den supplies the redirect-safe SSRF/DNS-rebinding guard for the MCP endpoint,
|
||||
OAuth discovery, registration, token endpoints, SSE, and tool calls.
|
||||
- OAuth connect requires the caller's signed authorization id before network
|
||||
or persistence work begins. No random-state fallback exists.
|
||||
- PKCE transactions are state-bound, individually expiring, capped, encrypted
|
||||
by Den, and consumed in the same database transaction as callback tokens.
|
||||
- Callback token commit verifies the OAuth client revision, authorization
|
||||
revision, connection identity, member/shared ownership, and lifecycle.
|
||||
- Dynamic client registration is first-writer-wins. A losing concurrent DCR
|
||||
cannot silently continue with the wrong client.
|
||||
- Den supplies `application_type: web`, a deployment client-metadata URL, an
|
||||
exact authorization-server issuer binding, and the administrator-approved
|
||||
scope set. The SDK chooses pre-registration, client metadata, then DCR.
|
||||
- `discoverConnectionRequirements` performs bounded, side-effect-free MCP,
|
||||
protected-resource, authorization-server, and unauthenticated tool discovery.
|
||||
It never performs DCR or writes application state.
|
||||
- `scopes_supported` is treated as an availability declaration while an
|
||||
administrator or challenge selects scopes. When neither selects any, the
|
||||
client falls back to the provider-advertised set so providers with a
|
||||
scope-less challenge still receive a usable authorization request. It
|
||||
includes `offline_access` only when refresh support is advertised.
|
||||
- New DCR client secrets are stored only in Den's encrypted client-secret
|
||||
column. Unencrypted JSON metadata excludes `client_secret` and
|
||||
`registration_access_token`.
|
||||
- Access-token and client-secret expiration are absolute, validated values.
|
||||
An expired access token without a refresh token is invalidated and reported
|
||||
as reconnect-required. Refresh-token rotation preserves the previous refresh
|
||||
token when a valid provider omits it from the refresh response. Refresh
|
||||
commits compare the credential revision so a stale concurrent response cannot
|
||||
overwrite newer rotated credentials.
|
||||
- MCP `isError: true` is a failed provider operation, not a successful request.
|
||||
- Tool catalogs have page, item, cursor, name, schema depth, schema size, and
|
||||
aggregate-byte ceilings.
|
||||
- Diagnostic events contain phases, outcome, duration, and HTTP status only.
|
||||
They never contain tokens, API keys, codes, PKCE verifiers, URLs, tool
|
||||
arguments, provider bodies, or customer content; a failing sink is isolated.
|
||||
- Connection deletion and enterprise credential commits take the same Den row
|
||||
lock, so deletion and a late callback have one deterministic winner.
|
||||
|
||||
See [SECURITY.md](./SECURITY.md) for the expiration/validation contract and
|
||||
[PRIOR-FINDINGS.md](./PRIOR-FINDINGS.md) for the earlier MCP findings that were
|
||||
incorporated, delegated to Den, or intentionally kept outside this server-side
|
||||
package.
|
||||
|
||||
## Runtime boundary
|
||||
|
||||
The package covers Den's outbound server-side remote MCP client only. It does
|
||||
not change local/direct engine MCP, the incoming OpenWork Cloud meta-MCP,
|
||||
desktop UI, or provider-specific tenant administration.
|
||||
|
||||
Den uses this package as its only remote MCP OAuth runtime. New connections use
|
||||
the deployment-wide shared callback. Existing connection rows retain their
|
||||
stored callback mode and reconnect with that exact redirect URI, so no callback
|
||||
migration, credential rewrite, or token copy is required. Version-one legacy
|
||||
authorizations already in flight remain valid only through their original
|
||||
per-connection callback and normal expiration window.
|
||||
Reference in new issue
Block a user