@novorb/mcp-core 2.1.2 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +77 -163
- package/bin/mcp-core-jest.mjs +112 -0
- package/dist/auth.d.ts +57 -0
- package/dist/auth.d.ts.map +1 -0
- package/dist/auth.js +74 -0
- package/dist/auth.js.map +1 -0
- package/dist/bootstrap.d.ts +129 -0
- package/dist/bootstrap.d.ts.map +1 -0
- package/dist/bootstrap.js +206 -0
- package/dist/bootstrap.js.map +1 -0
- package/dist/client-input.d.ts +72 -0
- package/dist/client-input.d.ts.map +1 -0
- package/dist/client-input.js +109 -0
- package/dist/client-input.js.map +1 -0
- package/dist/credential-checks.d.ts +80 -0
- package/dist/credential-checks.d.ts.map +1 -0
- package/dist/credential-checks.js +189 -0
- package/dist/credential-checks.js.map +1 -0
- package/dist/credential-health.d.ts +12 -0
- package/dist/credential-health.d.ts.map +1 -0
- package/dist/credential-health.js +12 -0
- package/dist/credential-health.js.map +1 -0
- package/dist/credential-report.d.ts +46 -0
- package/dist/credential-report.d.ts.map +1 -0
- package/dist/credential-report.js +135 -0
- package/dist/credential-report.js.map +1 -0
- package/dist/credential-status-tool.d.ts +20 -0
- package/dist/credential-status-tool.d.ts.map +1 -0
- package/dist/credential-status-tool.js +33 -0
- package/dist/credential-status-tool.js.map +1 -0
- package/dist/credentials.d.ts +288 -0
- package/dist/credentials.d.ts.map +1 -0
- package/dist/credentials.js +652 -0
- package/dist/credentials.js.map +1 -0
- package/dist/express-peers.d.ts +29 -0
- package/dist/express-peers.d.ts.map +1 -0
- package/dist/express-peers.js +36 -0
- package/dist/express-peers.js.map +1 -0
- package/dist/express.d.ts +74 -0
- package/dist/express.d.ts.map +1 -0
- package/dist/express.js +164 -0
- package/dist/express.js.map +1 -0
- package/dist/http-client.d.ts +277 -42
- package/dist/http-client.d.ts.map +1 -1
- package/dist/http-client.js +620 -180
- package/dist/http-client.js.map +1 -1
- package/dist/index.d.ts +27 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +47 -8
- package/dist/index.js.map +1 -1
- package/dist/limits.d.ts +28 -0
- package/dist/limits.d.ts.map +1 -0
- package/dist/limits.js +37 -0
- package/dist/limits.js.map +1 -0
- package/dist/list-pagination.d.ts +41 -0
- package/dist/list-pagination.d.ts.map +1 -0
- package/dist/list-pagination.js +104 -0
- package/dist/list-pagination.js.map +1 -0
- package/dist/net.d.ts +112 -0
- package/dist/net.d.ts.map +1 -0
- package/dist/net.js +490 -0
- package/dist/net.js.map +1 -0
- package/dist/notifications.d.ts +78 -0
- package/dist/notifications.d.ts.map +1 -0
- package/dist/notifications.js +173 -0
- package/dist/notifications.js.map +1 -0
- package/dist/pagination.d.ts +236 -5
- package/dist/pagination.d.ts.map +1 -1
- package/dist/pagination.js +393 -6
- package/dist/pagination.js.map +1 -1
- package/dist/prompts.d.ts +70 -0
- package/dist/prompts.d.ts.map +1 -0
- package/dist/prompts.js +109 -0
- package/dist/prompts.js.map +1 -0
- package/dist/protocol-errors.d.ts +15 -0
- package/dist/protocol-errors.d.ts.map +1 -0
- package/dist/protocol-errors.js +28 -0
- package/dist/protocol-errors.js.map +1 -0
- package/dist/protocol-logging.d.ts +37 -0
- package/dist/protocol-logging.d.ts.map +1 -0
- package/dist/protocol-logging.js +77 -0
- package/dist/protocol-logging.js.map +1 -0
- package/dist/rate-limiter.d.ts +36 -0
- package/dist/rate-limiter.d.ts.map +1 -0
- package/dist/rate-limiter.js +79 -0
- package/dist/rate-limiter.js.map +1 -0
- package/dist/request-state.d.ts +74 -0
- package/dist/request-state.d.ts.map +1 -0
- package/dist/request-state.js +190 -0
- package/dist/request-state.js.map +1 -0
- package/dist/resources.d.ts +181 -0
- package/dist/resources.d.ts.map +1 -0
- package/dist/resources.js +302 -0
- package/dist/resources.js.map +1 -0
- package/dist/result-limits.d.ts +80 -0
- package/dist/result-limits.d.ts.map +1 -0
- package/dist/result-limits.js +248 -0
- package/dist/result-limits.js.map +1 -0
- package/dist/retry.d.ts +79 -23
- package/dist/retry.d.ts.map +1 -1
- package/dist/retry.js +170 -57
- package/dist/retry.js.map +1 -1
- package/dist/sdk/client-stdio.d.ts +6 -0
- package/dist/sdk/client-stdio.d.ts.map +1 -0
- package/dist/sdk/client-stdio.js +6 -0
- package/dist/sdk/client-stdio.js.map +1 -0
- package/dist/sdk/client.d.ts +6 -0
- package/dist/sdk/client.d.ts.map +1 -0
- package/dist/sdk/client.js +6 -0
- package/dist/sdk/client.js.map +1 -0
- package/dist/sdk/express.d.ts +3 -0
- package/dist/sdk/express.d.ts.map +1 -0
- package/dist/sdk/express.js +11 -0
- package/dist/sdk/express.js.map +1 -0
- package/dist/sdk/node.d.ts +6 -0
- package/dist/sdk/node.d.ts.map +1 -0
- package/dist/sdk/node.js +6 -0
- package/dist/sdk/node.js.map +1 -0
- package/dist/sdk/server-stdio.d.ts +6 -0
- package/dist/sdk/server-stdio.d.ts.map +1 -0
- package/dist/sdk/server-stdio.js +6 -0
- package/dist/sdk/server-stdio.js.map +1 -0
- package/dist/sdk/server.d.ts +6 -0
- package/dist/sdk/server.d.ts.map +1 -0
- package/dist/sdk/server.js +6 -0
- package/dist/sdk/server.js.map +1 -0
- package/dist/server.d.ts +88 -35
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +98 -44
- package/dist/server.js.map +1 -1
- package/dist/task-request.d.ts +20 -0
- package/dist/task-request.d.ts.map +1 -0
- package/dist/task-request.js +43 -0
- package/dist/task-request.js.map +1 -0
- package/dist/task-store.d.ts +230 -0
- package/dist/task-store.d.ts.map +1 -0
- package/dist/task-store.js +459 -0
- package/dist/task-store.js.map +1 -0
- package/dist/task-tools.d.ts +115 -0
- package/dist/task-tools.d.ts.map +1 -0
- package/dist/task-tools.js +397 -0
- package/dist/task-tools.js.map +1 -0
- package/dist/testing/client.d.ts +25 -0
- package/dist/testing/client.d.ts.map +1 -0
- package/dist/testing/client.js +11 -0
- package/dist/testing/client.js.map +1 -0
- package/dist/testing/in-memory.d.ts +26 -0
- package/dist/testing/in-memory.d.ts.map +1 -0
- package/dist/testing/in-memory.js +41 -0
- package/dist/testing/in-memory.js.map +1 -0
- package/dist/testing/index.d.ts +20 -0
- package/dist/testing/index.d.ts.map +1 -0
- package/dist/testing/index.js +20 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/testing/isolated-dirs.d.ts +27 -0
- package/dist/testing/isolated-dirs.d.ts.map +1 -0
- package/dist/testing/isolated-dirs.js +67 -0
- package/dist/testing/isolated-dirs.js.map +1 -0
- package/dist/testing/logs.d.ts +61 -0
- package/dist/testing/logs.d.ts.map +1 -0
- package/dist/testing/logs.js +113 -0
- package/dist/testing/logs.js.map +1 -0
- package/dist/testing/raw-http.d.ts +25 -0
- package/dist/testing/raw-http.d.ts.map +1 -0
- package/dist/testing/raw-http.js +41 -0
- package/dist/testing/raw-http.js.map +1 -0
- package/dist/testing/raw-peer.d.ts +43 -0
- package/dist/testing/raw-peer.d.ts.map +1 -0
- package/dist/testing/raw-peer.js +101 -0
- package/dist/testing/raw-peer.js.map +1 -0
- package/dist/testing/recording-server.d.ts +38 -0
- package/dist/testing/recording-server.d.ts.map +1 -0
- package/dist/testing/recording-server.js +38 -0
- package/dist/testing/recording-server.js.map +1 -0
- package/dist/testing/server-process.d.ts +76 -0
- package/dist/testing/server-process.d.ts.map +1 -0
- package/dist/testing/server-process.js +241 -0
- package/dist/testing/server-process.js.map +1 -0
- package/dist/testing/tools.d.ts +53 -0
- package/dist/testing/tools.d.ts.map +1 -0
- package/dist/testing/tools.js +98 -0
- package/dist/testing/tools.js.map +1 -0
- package/dist/testing/unit.d.ts +52 -0
- package/dist/testing/unit.d.ts.map +1 -0
- package/dist/testing/unit.js +95 -0
- package/dist/testing/unit.js.map +1 -0
- package/dist/tools.d.ts +205 -0
- package/dist/tools.d.ts.map +1 -0
- package/dist/tools.js +370 -0
- package/dist/tools.js.map +1 -0
- package/dist/transport.d.ts +143 -52
- package/dist/transport.d.ts.map +1 -1
- package/dist/transport.js +292 -123
- package/dist/transport.js.map +1 -1
- package/dist/url-path.d.ts +49 -0
- package/dist/url-path.d.ts.map +1 -0
- package/dist/url-path.js +165 -0
- package/dist/url-path.js.map +1 -0
- package/dist/utils/dataStore.d.ts +143 -0
- package/dist/utils/dataStore.d.ts.map +1 -0
- package/dist/utils/dataStore.js +429 -0
- package/dist/utils/dataStore.js.map +1 -0
- package/dist/utils/envLoader.d.ts +129 -0
- package/dist/utils/envLoader.d.ts.map +1 -0
- package/dist/utils/envLoader.js +399 -0
- package/dist/utils/envLoader.js.map +1 -0
- package/dist/utils/logger.d.ts +181 -0
- package/dist/utils/logger.d.ts.map +1 -0
- package/dist/utils/logger.js +664 -0
- package/dist/utils/logger.js.map +1 -0
- package/dist/utils/redact.d.ts +50 -0
- package/dist/utils/redact.d.ts.map +1 -0
- package/dist/utils/redact.js +318 -0
- package/dist/utils/redact.js.map +1 -0
- package/docs/api-reference.md +29 -0
- package/docs/building-a-server.md +63 -0
- package/docs/credentials.md +131 -0
- package/docs/data-store.md +37 -0
- package/docs/env.md +38 -0
- package/docs/features.md +28 -0
- package/docs/http-client.md +116 -0
- package/docs/logger.md +100 -0
- package/docs/migrating-to-v3.md +45 -0
- package/docs/outbound-urls.md +104 -0
- package/docs/pagination.md +45 -0
- package/docs/protocol-features.md +62 -0
- package/docs/resources-prompts-tasks.md +95 -0
- package/docs/sdk.md +33 -0
- package/docs/server.md +68 -0
- package/docs/testing-harness.md +139 -0
- package/docs/testing.md +151 -0
- package/docs/tools.md +88 -0
- package/docs/transport.md +85 -0
- package/examples/testing/tools.integration.test.example.ts +312 -0
- package/examples/testing/tools.unit.test.example.ts +149 -0
- package/package.json +130 -17
- package/dist/logger.d.ts +0 -80
- package/dist/logger.d.ts.map +0 -1
- package/dist/logger.js +0 -237
- package/dist/logger.js.map +0 -1
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @novorb/mcp-core - Credential health
|
|
3
|
+
*
|
|
4
|
+
* A credential is checked once when the env is loaded (see `credential-checks.ts`); after that its
|
|
5
|
+
* health is learned from use. A key can degrade (quota, rate limit), become invalid or expire while the
|
|
6
|
+
* server runs: that never crashes the server and never turns a tool call into an error on its own.
|
|
7
|
+
* Instead every tool result that touched a credential carries a report of the keys it used and the
|
|
8
|
+
* ones that are degraded, invalid or expired (see `registerTools`).
|
|
9
|
+
*
|
|
10
|
+
* - `CredentialRegistry` (process-wide by default, `processCredentials()`): the status per DECLARED key
|
|
11
|
+
* name, pools (an env `multi` family: `KEY`, `KEY_1`, `KEY_2`, ...), `pick(pool)` rotation that
|
|
12
|
+
* prefers valid over unknown over degraded and keeps invalid and expired keys as the last resort (so
|
|
13
|
+
* no key is lost for good), `record(key, outcome)`, `snapshot()`, and a background re-check of invalid
|
|
14
|
+
* and expired keys (the startup `check`) after `recheckMs`. Transitions are logged once per change.
|
|
15
|
+
* - `CredentialScope`: one tool call's view of the registry. It remembers which credentials the call
|
|
16
|
+
* touched, so the result can report them; the http-client records into the current scope.
|
|
17
|
+
* - `credentialOutcomeFromHttp`: the one HTTP outcome mapping (status-gated, see there).
|
|
18
|
+
*
|
|
19
|
+
* Only declared key NAMES ever appear in logs, results and snapshots: an identifier that is not a
|
|
20
|
+
* registered name is refused with `UnknownCredentialError` (a programming error), so a value passed by
|
|
21
|
+
* mistake is never published. A registry never holds a value.
|
|
22
|
+
*/
|
|
23
|
+
import { type Logger } from './utils/logger.js';
|
|
24
|
+
/**
|
|
25
|
+
* - `valid`: the provider accepted the key.
|
|
26
|
+
* - `invalid`: the provider rejected it (auth error); re-checked after `recheckMs`, still tried last.
|
|
27
|
+
* - `expired`: the provider reported it expired; handled like `invalid`.
|
|
28
|
+
* - `degraded`: quota exhausted or rate limited; back to `unknown` once the retry-after elapses.
|
|
29
|
+
* - `unknown`: not decided (no check, the check timed out or hit a network error).
|
|
30
|
+
*/
|
|
31
|
+
export type CredentialStatus = 'valid' | 'invalid' | 'expired' | 'degraded' | 'unknown';
|
|
32
|
+
export declare const CREDENTIAL_STATUSES: readonly CredentialStatus[];
|
|
33
|
+
/**
|
|
34
|
+
* What one use of a key showed:
|
|
35
|
+
* - `ok` (alias `recovered`): the provider accepted it; the key becomes `valid`.
|
|
36
|
+
* - `used`: the call went out but proved nothing about the key (a 404, a 500, a network error).
|
|
37
|
+
* - `degraded` / `invalid` / `expired`: the key's new status.
|
|
38
|
+
*/
|
|
39
|
+
export type CredentialOutcome = 'ok' | 'recovered' | 'used' | 'degraded' | 'invalid' | 'expired';
|
|
40
|
+
export interface CredentialOutcomeInfo {
|
|
41
|
+
/** Short, value-free reason (`quota`, `rate limit`, `auth rejected`, ...). */
|
|
42
|
+
reason?: string;
|
|
43
|
+
/** For `degraded`: how long until the key may work again. */
|
|
44
|
+
retryAfterMs?: number;
|
|
45
|
+
}
|
|
46
|
+
/** An outcome with its details (what `credentialOutcomeFromHttp` returns). */
|
|
47
|
+
export interface ClassifiedOutcome extends CredentialOutcomeInfo {
|
|
48
|
+
outcome: CredentialOutcome;
|
|
49
|
+
}
|
|
50
|
+
/** One credential's state as `snapshot()` reports it. Names only, never a value. */
|
|
51
|
+
export interface CredentialState {
|
|
52
|
+
key: string;
|
|
53
|
+
/** The pool (env `multi` base key) this key belongs to, when it is a pool member. */
|
|
54
|
+
pool?: string;
|
|
55
|
+
status: CredentialStatus;
|
|
56
|
+
reason?: string;
|
|
57
|
+
/** For `degraded`: seconds until the retry-after elapses. */
|
|
58
|
+
retryInSeconds?: number;
|
|
59
|
+
/** ISO time of the last status change. */
|
|
60
|
+
changedAt?: string;
|
|
61
|
+
/** ISO time of the last recorded use. */
|
|
62
|
+
lastUsedAt?: string;
|
|
63
|
+
}
|
|
64
|
+
/** A re-check of one key (the startup `check` bound to the key's value): its new status. */
|
|
65
|
+
export type CredentialProbe = () => Promise<CredentialOutcomeInfo & {
|
|
66
|
+
status: CredentialStatus;
|
|
67
|
+
}>;
|
|
68
|
+
export interface CredentialRegistryOptions {
|
|
69
|
+
/** Clock (tests). */
|
|
70
|
+
now?: () => number;
|
|
71
|
+
/** Logger for transitions (default the mcp-core singleton). */
|
|
72
|
+
logger?: Logger;
|
|
73
|
+
/** Cool-down for a `degraded` outcome that carries no retry-after (default 60000 ms). */
|
|
74
|
+
defaultRetryAfterMs?: number;
|
|
75
|
+
/** How long an invalid or expired key waits before its probe re-checks it (default 300000 ms). */
|
|
76
|
+
recheckMs?: number;
|
|
77
|
+
}
|
|
78
|
+
export declare const DEFAULT_CREDENTIAL_RECHECK_MS = 300000;
|
|
79
|
+
/** No candidate of a pool worked: every one was tried and failed on its credential, or none is configured. */
|
|
80
|
+
export declare class NoUsableCredentialError extends Error {
|
|
81
|
+
readonly pool: string;
|
|
82
|
+
readonly keys: readonly string[];
|
|
83
|
+
constructor(pool: string, keys: readonly string[], detail?: string);
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* A programming error: an identifier that is not a declared credential name (env key or pool member)
|
|
87
|
+
* was passed where a key NAME belongs (often the VALUE by mistake). The identifier itself is never put
|
|
88
|
+
* in the message.
|
|
89
|
+
*/
|
|
90
|
+
export declare class UnknownCredentialError extends Error {
|
|
91
|
+
constructor();
|
|
92
|
+
}
|
|
93
|
+
/** The process-wide (or a test's own) credential health registry. */
|
|
94
|
+
export declare class CredentialRegistry {
|
|
95
|
+
private readonly entries;
|
|
96
|
+
private readonly pools;
|
|
97
|
+
private readonly cursors;
|
|
98
|
+
private readonly now;
|
|
99
|
+
private readonly logger?;
|
|
100
|
+
private readonly defaultRetryAfterMs;
|
|
101
|
+
private recheckMs;
|
|
102
|
+
constructor(options?: CredentialRegistryOptions);
|
|
103
|
+
private log;
|
|
104
|
+
/** Set the invalid/expired re-check cool-down (startup reads MCP_CREDENTIAL_RECHECK_MS). */
|
|
105
|
+
setRecheckMs(ms: number): void;
|
|
106
|
+
/**
|
|
107
|
+
* Declare a credential by its env NAME (status `unknown` until checked or used). Re-registering keeps
|
|
108
|
+
* the status and updates the pool. A pool member is appended to its pool in registration order.
|
|
109
|
+
* Throws `UnknownCredentialError` for anything that is not an env-variable-shaped name.
|
|
110
|
+
*/
|
|
111
|
+
register(key: string, options?: {
|
|
112
|
+
pool?: string;
|
|
113
|
+
}): void;
|
|
114
|
+
/** Attach the re-check for an invalid or expired key (the startup `check` bound to its value). */
|
|
115
|
+
setProbe(key: string, probe: CredentialProbe): void;
|
|
116
|
+
/**
|
|
117
|
+
* Declare that `key` stands for the other parts of a multi-part credential (client id + secret, key +
|
|
118
|
+
* secret): every status change of `key` (a check, a recheck, a recorded outcome) is applied to each
|
|
119
|
+
* part too, with the same reason. Both sides must be declared (else `UnknownCredentialError`); `key`
|
|
120
|
+
* itself is ignored if listed.
|
|
121
|
+
*/
|
|
122
|
+
cover(key: string, parts: readonly string[]): void;
|
|
123
|
+
/** Forget every credential (tests, or a server re-reading its env). */
|
|
124
|
+
clear(): void;
|
|
125
|
+
/** Whether `key` is a declared credential name. */
|
|
126
|
+
has(key: string): boolean;
|
|
127
|
+
/** The declared entry, or `UnknownCredentialError`. */
|
|
128
|
+
private entry;
|
|
129
|
+
/** A degraded key whose retry-after elapsed goes back to `unknown` (logged once). */
|
|
130
|
+
private refresh;
|
|
131
|
+
/** The current status (`unknown` for a key never registered). */
|
|
132
|
+
status(key: string): CredentialStatus;
|
|
133
|
+
/**
|
|
134
|
+
* The member keys of `pool`: a pool name, a single declared key, or an explicit list of declared keys
|
|
135
|
+
* (an undeclared name in a list throws `UnknownCredentialError`). An unknown pool name has no members.
|
|
136
|
+
*/
|
|
137
|
+
members(pool: string | readonly string[]): string[];
|
|
138
|
+
/**
|
|
139
|
+
* Set a status directly (startup checks, re-checks). `silent` skips the transition log line (the
|
|
140
|
+
* caller logs a summary instead).
|
|
141
|
+
*/
|
|
142
|
+
set(key: string, status: CredentialStatus, info?: CredentialOutcomeInfo & {
|
|
143
|
+
silent?: boolean;
|
|
144
|
+
}): void;
|
|
145
|
+
/** Record what a use of `key` showed. `key` must be a declared name. */
|
|
146
|
+
record(key: string, outcome: CredentialOutcome, info?: CredentialOutcomeInfo): void;
|
|
147
|
+
/** Mark a declared key as used (no outcome). */
|
|
148
|
+
touch(key: string): void;
|
|
149
|
+
private transition;
|
|
150
|
+
private transitionOne;
|
|
151
|
+
/** Rank for `candidates`: valid 0, unknown 1, degraded 2, invalid/expired 3 (the last resort). */
|
|
152
|
+
private rank;
|
|
153
|
+
/**
|
|
154
|
+
* Re-check `key` now with its probe (the startup `check`). Resolves with the new status, or the
|
|
155
|
+
* current one when there is no probe. One probe per key runs at a time; a probe never throws out.
|
|
156
|
+
*/
|
|
157
|
+
recheck(key: string): Promise<CredentialStatus>;
|
|
158
|
+
/** Start the re-check of every invalid/expired member whose cool-down elapsed (not awaited). */
|
|
159
|
+
private recheckDue;
|
|
160
|
+
/**
|
|
161
|
+
* Every member of `pool`, best first: valid, unknown, degraded, then invalid and expired as the last
|
|
162
|
+
* resort (so a pool whose keys all went bad still tries a request, and a success restores the key).
|
|
163
|
+
* Rotated within the best tier so repeated calls spread over equally healthy keys. Invalid and expired
|
|
164
|
+
* members whose re-check cool-down elapsed are re-checked in the background.
|
|
165
|
+
*/
|
|
166
|
+
candidates(pool: string | readonly string[]): string[];
|
|
167
|
+
/** The best member of `pool` (see `candidates`), or undefined when the pool has no member. */
|
|
168
|
+
pick(pool: string | readonly string[]): string | undefined;
|
|
169
|
+
/** One key's state (undefined when never registered). */
|
|
170
|
+
state(key: string): CredentialState | undefined;
|
|
171
|
+
/** Every credential's state, in registration order. */
|
|
172
|
+
snapshot(): CredentialState[];
|
|
173
|
+
}
|
|
174
|
+
/** The process-wide registry `runMcpServer` fills and `registerTools` reports from. */
|
|
175
|
+
export declare function processCredentials(): CredentialRegistry;
|
|
176
|
+
/** Replace the process-wide registry (tests, or a host with its own). Undefined resets it. */
|
|
177
|
+
export declare function setProcessCredentials(registry: CredentialRegistry | undefined): void;
|
|
178
|
+
/** One credential in a tool result's report. */
|
|
179
|
+
export interface CredentialReportEntry {
|
|
180
|
+
key: string;
|
|
181
|
+
status: CredentialStatus;
|
|
182
|
+
/** True when this call used the key (a request went out with it). */
|
|
183
|
+
used: boolean;
|
|
184
|
+
reason?: string;
|
|
185
|
+
retryInSeconds?: number;
|
|
186
|
+
}
|
|
187
|
+
/** Anything that accepts an outcome for a key (a registry or a call scope). */
|
|
188
|
+
export interface CredentialRecorder {
|
|
189
|
+
/** Whether `key` is a declared credential name. */
|
|
190
|
+
has(key: string): boolean;
|
|
191
|
+
record(key: string, outcome: CredentialOutcome, info?: CredentialOutcomeInfo): void;
|
|
192
|
+
}
|
|
193
|
+
/** A tool call's view of the registry: what it picks and records is reported on its result. */
|
|
194
|
+
export declare class CredentialScope implements CredentialRecorder {
|
|
195
|
+
readonly registry: CredentialRegistry;
|
|
196
|
+
private readonly touched;
|
|
197
|
+
private readonly valueFor;
|
|
198
|
+
constructor(registry: CredentialRegistry, valueFor?: (key: string) => string | undefined);
|
|
199
|
+
private touch;
|
|
200
|
+
has(key: string): boolean;
|
|
201
|
+
/** Consider every member of `pool` (reported when not healthy) and return them, best first. */
|
|
202
|
+
candidates(pool: string | readonly string[]): string[];
|
|
203
|
+
/**
|
|
204
|
+
* The best key of `pool` (marked used); an invalid or expired key when nothing better is left (try
|
|
205
|
+
* it and record the outcome). Undefined only when the pool has no member.
|
|
206
|
+
*/
|
|
207
|
+
pick(pool: string | readonly string[]): string | undefined;
|
|
208
|
+
/** Like `pick`, but throws `NoUsableCredentialError` when the pool has no member. */
|
|
209
|
+
require(pool: string | readonly string[]): string;
|
|
210
|
+
/** Mark a declared `key` as used by this call without recording an outcome. */
|
|
211
|
+
use(key: string): void;
|
|
212
|
+
record(key: string, outcome: CredentialOutcome, info?: CredentialOutcomeInfo): void;
|
|
213
|
+
/**
|
|
214
|
+
* Try the members of `pool` in order (best first, invalid and expired last): `fn(key, value)` for each
|
|
215
|
+
* until one succeeds. A failure that is a credential problem (see `credentialOutcomeFromError`) is
|
|
216
|
+
* recorded and the next key is tried; any other error is rethrown. When every member failed on its
|
|
217
|
+
* credential (or the pool is empty) it throws `NoUsableCredentialError`.
|
|
218
|
+
*/
|
|
219
|
+
withFallback<T>(pool: string | readonly string[], fn: (key: string, value: string | undefined) => Promise<T>): Promise<T>;
|
|
220
|
+
/** Whether this call touched any credential. */
|
|
221
|
+
get touchedAny(): boolean;
|
|
222
|
+
/**
|
|
223
|
+
* The report entries: every key the call used, plus every considered key that is not healthy
|
|
224
|
+
* (degraded, invalid, expired). Considered-but-unused healthy keys are left out.
|
|
225
|
+
*/
|
|
226
|
+
report(): CredentialReportEntry[];
|
|
227
|
+
}
|
|
228
|
+
/** The report as one line the model reads: `Credentials: A used; B degraded (quota, retry in 60s); C invalid`. */
|
|
229
|
+
export declare function formatCredentialReport(entries: readonly CredentialReportEntry[]): string;
|
|
230
|
+
/**
|
|
231
|
+
* Run `fn` with `scope` as the current call's credential scope (registerTools does this per call).
|
|
232
|
+
* Outcomes are recorded into the scope active where a request STARTS: a shared in-flight promise
|
|
233
|
+
* (a dedup cache, a coalesced request) reports its key on the call that started it only.
|
|
234
|
+
*/
|
|
235
|
+
export declare function runWithCredentialScope<T>(scope: CredentialScope, fn: () => T): T;
|
|
236
|
+
/** The current tool call's credential scope, when inside one. */
|
|
237
|
+
export declare function currentCredentialScope(): CredentialScope | undefined;
|
|
238
|
+
/** The facts `credentialOutcomeFromHttp` reads. */
|
|
239
|
+
export interface CredentialHttpFacts {
|
|
240
|
+
/** HTTP status; undefined for a network error. */
|
|
241
|
+
status?: number;
|
|
242
|
+
/** Upstream or normalized error code. */
|
|
243
|
+
code?: string;
|
|
244
|
+
/** Upstream error message (already masked). */
|
|
245
|
+
message?: string;
|
|
246
|
+
/** Upstream OAuth-style `error_description` (already masked), when the body carried one apart from `message`. */
|
|
247
|
+
description?: string;
|
|
248
|
+
/**
|
|
249
|
+
* The `WWW-Authenticate` response header, when present. Only its `error` and `error_description`
|
|
250
|
+
* parameters are read (RFC 6750), never the realm or anything else.
|
|
251
|
+
*/
|
|
252
|
+
authenticate?: string;
|
|
253
|
+
/** The challenge's parameters already parsed (`HttpError.challenge`); used instead of `authenticate`. */
|
|
254
|
+
challenge?: AuthChallenge;
|
|
255
|
+
retryAfterMs?: number;
|
|
256
|
+
}
|
|
257
|
+
/** The two `WWW-Authenticate` parameters the credential mapping reads (RFC 6750). */
|
|
258
|
+
export interface AuthChallenge {
|
|
259
|
+
error?: string;
|
|
260
|
+
description?: string;
|
|
261
|
+
}
|
|
262
|
+
/**
|
|
263
|
+
* The `error` and `error_description` auth-params of a `WWW-Authenticate` header (first occurrence of
|
|
264
|
+
* each). The header is tokenised left to right: a quoted string (`"..."` with backslash escapes, or
|
|
265
|
+
* `'...'`) is one value and is never searched, so a quoted realm cannot inject a parameter.
|
|
266
|
+
*/
|
|
267
|
+
export declare function parseAuthChallenge(header: string | undefined): AuthChallenge;
|
|
268
|
+
/**
|
|
269
|
+
* Map an HTTP outcome onto a credential outcome, status-gated:
|
|
270
|
+
* - 2xx/3xx -> ok; 5xx, network errors and every other 4xx (400, 404, 409, 413, 422, ...) -> used;
|
|
271
|
+
* - 401 -> invalid, or expired when the code, message, `error_description` or the `WWW-Authenticate`
|
|
272
|
+
* `error` / `error_description` parameters name an expired credential (GitLab: `error="invalid_token",
|
|
273
|
+
* error_description="Token is expired"`);
|
|
274
|
+
* - 402 -> degraded (quota); 429 -> degraded (rate limit, or quota when the body says so);
|
|
275
|
+
* - 403 -> expired / degraded / invalid ONLY when the body (or the challenge's `error="invalid_token"`)
|
|
276
|
+
* says the credential itself expired, hit a quota or rate limit, or was rejected; a plain 403 is an
|
|
277
|
+
* authorization answer about one resource and leaves the key alone (used).
|
|
278
|
+
* Degraded outcomes carry the Retry-After.
|
|
279
|
+
*/
|
|
280
|
+
export declare function credentialOutcomeFromHttp(facts: CredentialHttpFacts): ClassifiedOutcome;
|
|
281
|
+
/**
|
|
282
|
+
* Classify a thrown error as a credential problem, or undefined when it is not one. Reads an
|
|
283
|
+
* `HttpError`-shaped object (`status`, `code`, `message`, `description`, `challenge`, `retryAfterMs`), so
|
|
284
|
+
* it reaches the same verdict the http-client recorded (an expired GitLab token stays expired inside
|
|
285
|
+
* `withFallback` and on a throwing startup check); only invalid, expired and degraded count.
|
|
286
|
+
*/
|
|
287
|
+
export declare function credentialOutcomeFromError(err: unknown): ClassifiedOutcome | undefined;
|
|
288
|
+
//# sourceMappingURL=credentials.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"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"}
|