@huaweidevtools/aishell-dsh-client-credentials 0.0.23 → 0.0.25

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/lib/client.js CHANGED
@@ -1071,11 +1071,23 @@ function CredentialRequestForm(props) {
1071
1071
  */
1072
1072
  const [loginWindowSeconds, setLoginWindowSeconds] = (0, react.useState)(void 0);
1073
1073
  /**
1074
- * Whether a credential is stored, read live rather than captured.
1074
+ * Whether this card should show the signed-in view.
1075
1075
  *
1076
- * Live because the card changes state under the person's hands: a successful
1077
- * save or login moves it to the signed-in view without a reopen, and a clear
1078
- * moves it back.
1076
+ * The question the view answers is "is this account usable right now?", and a
1077
+ * stored pair is only an answer to "is something stored?" — a credential IAM
1078
+ * has stopped accepting stays in the store until someone checks it. The two
1079
+ * diverge exactly when the card would otherwise lie: an expired STS token, or
1080
+ * a key deleted in the console, leaves a signed-in view whose only two
1081
+ * actions are "confirm" and "log out", neither of which fixes anything.
1082
+ *
1083
+ * `credentialsStored` is what the Host writes, and it is cleared by every path
1084
+ * that learns the pair is unusable (`./credential-watch.ts` and the `auth`
1085
+ * tool both go through `discard`). So this reads "stored, and not since
1086
+ * found to be refused" — the state the store actually supports.
1087
+ *
1088
+ * Live rather than captured: the card changes under the person's hands, and a
1089
+ * background check that clears the store must move this view without a
1090
+ * reopen.
1079
1091
  */
1080
1092
  const signedIn = status.hasAccessKey || status.hasSecretKey;
1081
1093
  (0, react.useEffect)(() => {
@@ -1735,6 +1747,141 @@ function createCredentialFormVisibility(deps) {
1735
1747
  };
1736
1748
  }
1737
1749
 
1750
+ //#endregion
1751
+ //#region src/revalidate.ts
1752
+ /**
1753
+ * How long to wait before the next background check.
1754
+ *
1755
+ * ## Why the interval is a function
1756
+ *
1757
+ * A fixed period is wrong in both directions. Checking a credential that has
1758
+ * never been stored verifies nothing; checking while the page is hidden spends
1759
+ * IAM quota to tell nobody anything; and retrying an IAM outage every minute
1760
+ * turns one outage into a steady stream of failing calls.
1761
+ *
1762
+ * ## The ladder
1763
+ *
1764
+ * - Nothing stored → no check. There is no credential to ask about, and the
1765
+ * form is the only way one arrives.
1766
+ * - Page hidden → no check. The person is not looking; a status that changed
1767
+ * while they were away is picked up on the next visible tick, and the
1768
+ * visible tick is what the interface is honest about.
1769
+ * - Last check unreachable → back off, doubling to a ceiling. This is the
1770
+ * case that must not become a retry storm: the credential is probably fine
1771
+ * and IAM is not.
1772
+ * - Otherwise → the ordinary period.
1773
+ *
1774
+ * Returns `undefined` for "do not schedule another check", which is distinct
1775
+ * from a very long delay: a hidden page or an empty store stops the loop, and
1776
+ * something else (a visibility change, a save) is what starts it again.
1777
+ *
1778
+ * @param input - current state, as the caller observes it.
1779
+ * @returns milliseconds until the next check, or `undefined` to stop.
1780
+ */
1781
+ function nextCheckDelay(input) {
1782
+ if (!input.hasCredential) return void 0;
1783
+ if (!input.visible) return void 0;
1784
+ if (input.consecutiveUnreachable === 0) return input.periodMs;
1785
+ const backoff = input.periodMs * 2 ** Math.min(input.consecutiveUnreachable, BACKOFF_CAP_STEPS);
1786
+ return Math.min(backoff, BACKOFF_CEILING_MS);
1787
+ }
1788
+ /** How many doublings the backoff may apply. */
1789
+ const BACKOFF_CAP_STEPS = 3;
1790
+ /** Slowest the backoff goes. */
1791
+ const BACKOFF_CEILING_MS = 3e5;
1792
+
1793
+ //#endregion
1794
+ //#region src/client/credential-watch.ts
1795
+ /** How often to re-check while the page is visible and IAM answers. */
1796
+ const WATCH_PERIOD_MS = 6e4;
1797
+ /**
1798
+ * Start watching the stored credential.
1799
+ *
1800
+ * One timer, re-armed after each check rather than running on a fixed interval:
1801
+ * the delay depends on the last answer, and an interval would either ignore the
1802
+ * backoff or have to be torn down and rebuilt for it.
1803
+ *
1804
+ * @param deps - presence, the check, and what to do with its answer.
1805
+ * @returns the handle the caller uses to restart or stop it.
1806
+ */
1807
+ function startCredentialWatch(deps) {
1808
+ const isVisible = deps.isVisible ?? (() => document.visibilityState === "visible");
1809
+ let timer;
1810
+ /** Consecutive checks that never reached IAM; drives the backoff. */
1811
+ let consecutiveUnreachable = 0;
1812
+ /**
1813
+ * Whether a check is in flight.
1814
+ *
1815
+ * A check costs an IAM round trip and can take longer than the ordinary
1816
+ * period. Re-arming while one is out would let two overlap — and a save, a
1817
+ * visibility change and a timer can all land in that window. One at a time is
1818
+ * the only bound that keeps the quota spent proportional to the period.
1819
+ */
1820
+ let inFlight = false;
1821
+ let stopped = false;
1822
+ /**
1823
+ * The check currently out, so disposing the plugin can drop it.
1824
+ *
1825
+ * A request left running after the fiber is gone reaches the Host after the
1826
+ * page has stopped caring — at worst clearing a store for a reload that has
1827
+ * already replaced it, at least spending IAM quota after the plugin that
1828
+ * asked for it no longer exists.
1829
+ */
1830
+ let controller;
1831
+ const clear = () => {
1832
+ if (timer !== void 0) clearTimeout(timer);
1833
+ timer = void 0;
1834
+ };
1835
+ const tick = async () => {
1836
+ timer = void 0;
1837
+ if (stopped || inFlight) return;
1838
+ inFlight = true;
1839
+ controller = new AbortController();
1840
+ let state;
1841
+ try {
1842
+ state = await deps.revalidate(controller.signal);
1843
+ } finally {
1844
+ inFlight = false;
1845
+ controller = void 0;
1846
+ }
1847
+ if (stopped) return;
1848
+ if (state === void 0 || state === "unreachable") consecutiveUnreachable += 1;
1849
+ else consecutiveUnreachable = 0;
1850
+ schedule();
1851
+ };
1852
+ const schedule = () => {
1853
+ clear();
1854
+ if (stopped || inFlight) return;
1855
+ const delay = nextCheckDelay({
1856
+ hasCredential: deps.hasCredential(),
1857
+ visible: isVisible(),
1858
+ consecutiveUnreachable,
1859
+ periodMs: WATCH_PERIOD_MS
1860
+ });
1861
+ if (delay === void 0) return;
1862
+ timer = setTimeout(() => {
1863
+ tick();
1864
+ }, delay);
1865
+ };
1866
+ schedule();
1867
+ return {
1868
+ arm: () => {
1869
+ stopped = false;
1870
+ schedule();
1871
+ },
1872
+ reset: () => {
1873
+ stopped = false;
1874
+ consecutiveUnreachable = 0;
1875
+ schedule();
1876
+ },
1877
+ stop: () => {
1878
+ stopped = true;
1879
+ clear();
1880
+ controller?.abort();
1881
+ }
1882
+ };
1883
+ }
1884
+
1738
1885
  //#endregion
1739
1886
  //#region src/client/locales.ts
1740
1887
  /**
@@ -1877,6 +2024,13 @@ const CONFIRM_ROUTE = "api/aishell/credentials/confirm";
1877
2024
  /** Prefill route; returns the values the host's environment already holds. */
1878
2025
  const PREFILL_ROUTE = "api/aishell/credentials/prefill";
1879
2026
  /**
2027
+ * Revalidation route; asks the Host to re-check the stored pair against IAM.
2028
+ *
2029
+ * Separate from the status route on purpose: the status read runs on every chip
2030
+ * render and must stay cheap, while this one costs an IAM round trip.
2031
+ */
2032
+ const REVALIDATE_ROUTE = "api/aishell/credentials/revalidate";
2033
+ /**
1880
2034
  * POST one JSON body to a Host credential route and read back its verdict.
1881
2035
  * A non-JSON or unreadable body is reported as a transport failure rather than
1882
2036
  * thrown, so the form shows a message instead of an unhandled rejection.
@@ -2042,6 +2196,39 @@ function apply(ctx) {
2042
2196
  ctx.effect(() => () => {
2043
2197
  visibility.dispose();
2044
2198
  }, "aishell-credentials: credential form teardown");
2199
+ const watch = startCredentialWatch({
2200
+ hasCredential: () => status.getSnapshot().hasAccessKey,
2201
+ revalidate: async (signal) => {
2202
+ const response = await fetch(REVALIDATE_ROUTE, {
2203
+ method: "POST",
2204
+ signal
2205
+ }).catch(() => void 0);
2206
+ if (response?.ok !== true) return void 0;
2207
+ const body = await response.json().catch(() => void 0);
2208
+ const state = body?.state;
2209
+ return state === "valid" || state === "discarded" || state === "absent" || state === "unreachable" ? state : void 0;
2210
+ }
2211
+ });
2212
+ ctx.effect(() => () => {
2213
+ watch.stop();
2214
+ }, "aishell-credentials: credential watch teardown");
2215
+ ctx.effect(() => {
2216
+ let hadCredential = status.getSnapshot().hasAccessKey;
2217
+ return status.subscribe(() => {
2218
+ const hasCredential = status.getSnapshot().hasAccessKey;
2219
+ if (hasCredential && !hadCredential) watch.reset();
2220
+ hadCredential = hasCredential;
2221
+ });
2222
+ }, "aishell-credentials: credential watch re-arm");
2223
+ ctx.effect(() => {
2224
+ const onVisibility = () => {
2225
+ if (document.visibilityState === "visible") watch.arm();
2226
+ };
2227
+ document.addEventListener("visibilitychange", onVisibility);
2228
+ return () => {
2229
+ document.removeEventListener("visibilitychange", onVisibility);
2230
+ };
2231
+ }, "aishell-credentials: credential watch visibility");
2045
2232
  /**
2046
2233
  * Answer the request this form is open for, if any.
2047
2234
  *
package/lib/index.js CHANGED
@@ -3,7 +3,7 @@ import { clearCredentials, hasStoredPair, readStoredPair, writeHuaweiCloud } fro
3
3
  import { verifyCredentials } from "@huaweidevtools/aishell-dsh-credentials-store/verify";
4
4
  import { createServer } from "node:http";
5
5
 
6
- //#region ../../node_modules/.pnpm/@deepseek-ai+cosmokit@1.8.5/node_modules/@deepseek-ai/cosmokit/lib/index.js
6
+ //#region ../../node_modules/.pnpm/@deepseek-ai+cosmokit@1.9.0/node_modules/@deepseek-ai/cosmokit/lib/index.js
7
7
  /** Return true when a value is `null` or `undefined`. */
8
8
  function isNullable(value) {
9
9
  return value === null || value === void 0;
@@ -262,7 +262,7 @@ var Time;
262
262
  })(Time || (Time = {}));
263
263
 
264
264
  //#endregion
265
- //#region ../../node_modules/.pnpm/@deepseek-ai+schemastery@3.18.4/node_modules/@deepseek-ai/schemastery/lib/index.mjs
265
+ //#region ../../node_modules/.pnpm/@deepseek-ai+schemastery@3.19.0/node_modules/@deepseek-ai/schemastery/lib/index.mjs
266
266
  const kSchema = Symbol.for("schemastery");
267
267
  const kValidationError = Symbol.for("ValidationError");
268
268
  globalThis.__schemastery_index__ ??= 0;
@@ -1001,7 +1001,7 @@ async function runAuth(store, deps, sessionId, signal) {
1001
1001
  if (stored !== void 0) {
1002
1002
  const verified = await verifyCredentials(stored, { region: VERIFY_REGION$1 });
1003
1003
  if (verified.ok) return describeAccount(verified);
1004
- if (verified.status === 401 || verified.status === 403) deps.discard();
1004
+ if (verified.status === 401 || verified.status === 403) await deps.discard();
1005
1005
  }
1006
1006
  if (sessionId === void 0 || sessionId === "") throw new Error("Not authenticated with Huawei Cloud IAM, and this call is not attached to a conversation, so the credential form cannot be shown. Ask the user to open the credential form themselves, then call auth again.");
1007
1007
  for (let round = 0; round < MAX_FORM_ROUNDS; round += 1) {
@@ -2299,6 +2299,40 @@ function createCredentialReconciler(deps) {
2299
2299
  };
2300
2300
  }
2301
2301
 
2302
+ //#endregion
2303
+ //#region src/revalidate.ts
2304
+ /**
2305
+ * Verify one stored pair, and discard it if IAM refused it.
2306
+ *
2307
+ * The discard is inside this function on purpose. Every caller that verifies a
2308
+ * stored pair has to make the same judgement about a refusal, and the one that
2309
+ * forgets leaves a credential the interface keeps advertising. Making it part
2310
+ * of "verify" means a caller cannot skip it by not knowing about it.
2311
+ *
2312
+ * @param credential - the pair to verify.
2313
+ * @param deps - verifier, refusal test, and the discard action.
2314
+ * @returns what the check found, in terms the caller can act on.
2315
+ */
2316
+ async function revalidate(credential, deps) {
2317
+ try {
2318
+ return {
2319
+ kind: "valid",
2320
+ accountName: await deps.verify(credential)
2321
+ };
2322
+ } catch (error) {
2323
+ const message = error instanceof Error ? error.message : String(error);
2324
+ if (!deps.isRejection(error)) return {
2325
+ kind: "unreachable",
2326
+ message
2327
+ };
2328
+ deps.discard();
2329
+ return {
2330
+ kind: "refused",
2331
+ message
2332
+ };
2333
+ }
2334
+ }
2335
+
2302
2336
  //#endregion
2303
2337
  //#region src/index.ts
2304
2338
  /**
@@ -2373,6 +2407,27 @@ const CANCEL_PATH = "/api/aishell/credentials/cancel";
2373
2407
  * destroys the credential the call was waiting to use.
2374
2408
  */
2375
2409
  const CONFIRM_PATH = "/api/aishell/credentials/confirm";
2410
+ /**
2411
+ * Route the browser calls on a timer to re-check the stored credential.
2412
+ *
2413
+ * ## Why this is a route and not a Host timer
2414
+ *
2415
+ * The Host cannot tell whether anyone is looking. A timer here would keep
2416
+ * asking IAM about a credential nobody has on screen — and a desktop app is
2417
+ * usually left open and unwatched, which is the worst case for a poll.
2418
+ *
2419
+ * The browser knows two things the Host does not: whether the page is visible,
2420
+ * and whether the credential the person is looking at is the one being asked
2421
+ * about. So the cadence lives there (`./client/credential-watch.ts`) and this
2422
+ * route is the single question it asks.
2423
+ *
2424
+ * ## Why it is separate from GET /credentials
2425
+ *
2426
+ * The status route is read on every chip render and must stay cheap. This one
2427
+ * calls IAM, and a route that costs a network round trip should be one a caller
2428
+ * opts into rather than one that fires whenever a component mounts.
2429
+ */
2430
+ const REVALIDATE_PATH = "/api/aishell/credentials/revalidate";
2376
2431
  /** Largest credential body accepted; a real payload is well under 1 KiB. */
2377
2432
  const MAX_BODY_BYTES = 8 * 1024;
2378
2433
  /**
@@ -2719,6 +2774,50 @@ function apply(ctx, config) {
2719
2774
  ctx.logger.warn(error);
2720
2775
  });
2721
2776
  };
2777
+ /**
2778
+ * Record status and wait for the document to hold it.
2779
+ *
2780
+ * ## Why the answer needs this and `recordStatus` is not enough
2781
+ *
2782
+ * The browser reads the settings document, not the Host's mirror. `mutate` is
2783
+ * asynchronous and the value reaches that document a moment later, so an
2784
+ * answer that says "the store was cleared" can reach the page while the page's
2785
+ * own view of the document still says a credential is stored. The card then
2786
+ * renders the signed-in view over an empty store — the contradiction this
2787
+ * whole path exists to remove.
2788
+ *
2789
+ * Awaiting the same `mutate` the mirror already followed closes that window:
2790
+ * by the time this resolves, the write has been applied, so the page's next
2791
+ * read of the document agrees with the answer.
2792
+ *
2793
+ * A refused write is rolled back exactly as `recordStatus` does it, and the
2794
+ * caller still gets its answer — the store is the truth, and the answer is
2795
+ * about the store.
2796
+ *
2797
+ * @param ops - the status edits to apply.
2798
+ */
2799
+ const recordStatusAndSettle = async (ops) => {
2800
+ if (ns === void 0) {
2801
+ mirrorOps(ops);
2802
+ return;
2803
+ }
2804
+ const before = {
2805
+ stored: recordedStored,
2806
+ hint: recordedHint
2807
+ };
2808
+ mirrorOps(ops);
2809
+ const after = {
2810
+ stored: recordedStored,
2811
+ hint: recordedHint
2812
+ };
2813
+ await ctx.settings.mutate(ns, ops).catch((error) => {
2814
+ if (recordedStored === after.stored && recordedHint === after.hint) {
2815
+ recordedStored = before.stored;
2816
+ recordedHint = before.hint;
2817
+ }
2818
+ ctx.logger.warn(error);
2819
+ });
2820
+ };
2722
2821
  const routes = createCredentialRoutes({
2723
2822
  store,
2724
2823
  verify: verifyCredentials$1,
@@ -2868,6 +2967,57 @@ function apply(ctx, config) {
2868
2967
  return routes.clear();
2869
2968
  }
2870
2969
  }), "aishell-credentials: clear route");
2970
+ ctx.effect(() => ctx.connection.fetch.register({
2971
+ path: REVALIDATE_PATH,
2972
+ methods: ["POST"],
2973
+ requestBody: "buffered",
2974
+ fetch: async () => {
2975
+ reconciler.reconcile();
2976
+ const pair = readStoredPair(store);
2977
+ if (pair === void 0) return Response.json({
2978
+ ok: true,
2979
+ state: "absent"
2980
+ });
2981
+ let statusSettled;
2982
+ const validity = await revalidate(pair, {
2983
+ verify: (credential) => verifyCredentials$1(credential.ak, credential.sk, credential.securityToken),
2984
+ isRejection: (error) => error instanceof CredentialRejectedError,
2985
+ discard: () => {
2986
+ clearCredentials(store);
2987
+ statusSettled = recordStatusAndSettle([
2988
+ {
2989
+ op: "set",
2990
+ path: ["credentialsStored"],
2991
+ value: false
2992
+ },
2993
+ {
2994
+ op: "unset",
2995
+ path: ["accessKeyIdHint"]
2996
+ },
2997
+ {
2998
+ op: "set",
2999
+ path: ["lastError"],
3000
+ value: "IAM refused the stored credential."
3001
+ }
3002
+ ]);
3003
+ announceCredentialsChanged();
3004
+ }
3005
+ });
3006
+ await statusSettled;
3007
+ if (validity.kind === "refused") return Response.json({
3008
+ ok: true,
3009
+ state: "discarded"
3010
+ });
3011
+ if (validity.kind === "unreachable") return Response.json({
3012
+ ok: true,
3013
+ state: "unreachable"
3014
+ });
3015
+ return Response.json({
3016
+ ok: true,
3017
+ state: "valid"
3018
+ });
3019
+ }
3020
+ }), "aishell-credentials: revalidate route");
2871
3021
  reconciler.reconcile();
2872
3022
  const reconcileTimer = setInterval(reconciler.reconcile, 3e4);
2873
3023
  ctx.effect(() => () => clearInterval(reconcileTimer), "aishell-credentials: status reconcile timer");
@@ -2900,16 +3050,24 @@ function apply(ctx, config) {
2900
3050
  settleFormRequest({ kind: "cancelled" });
2901
3051
  loginFlow.cancel();
2902
3052
  },
2903
- discard: () => {
3053
+ discard: async () => {
2904
3054
  clearCredentials(store);
2905
- recordStatus([{
2906
- op: "set",
2907
- path: ["credentialsStored"],
2908
- value: false
2909
- }, {
2910
- op: "unset",
2911
- path: ["accessKeyIdHint"]
2912
- }]);
3055
+ await recordStatusAndSettle([
3056
+ {
3057
+ op: "set",
3058
+ path: ["credentialsStored"],
3059
+ value: false
3060
+ },
3061
+ {
3062
+ op: "unset",
3063
+ path: ["accessKeyIdHint"]
3064
+ },
3065
+ {
3066
+ op: "set",
3067
+ path: ["lastError"],
3068
+ value: "IAM refused the stored credential."
3069
+ }
3070
+ ]);
2913
3071
  announceCredentialsChanged();
2914
3072
  }
2915
3073
  });
@@ -112,8 +112,13 @@ export interface AuthToolDeps {
112
112
  * SAME pair useless. Clearing first is what turns the next form into "sign
113
113
  * in from scratch" instead of a signed-in card whose only button does
114
114
  * nothing.
115
+ *
116
+ * Resolves once the interface's status document holds the cleared state. The
117
+ * form opens right after this returns and the card reads that document, so a
118
+ * discard that resolved before the write landed would draw a signed-in card
119
+ * over an empty store.
115
120
  */
116
- readonly discard: () => void;
121
+ readonly discard: () => Promise<void>;
117
122
  }
118
123
  /**
119
124
  * Register the `auth` tool on the host's tool registry.
@@ -0,0 +1,94 @@
1
+ /**
2
+ * The credential watch: keeps the signed-in state honest about IAM.
3
+ *
4
+ * ## What it is for
5
+ *
6
+ * A stored pair can stop working with nothing in the store changing — an
7
+ * expired STS token, a key deleted in the console. The card and the chips read
8
+ * a status document the Host writes from the store, so without a check they go
9
+ * on reporting "signed in" until something else happens to call IAM. The first
10
+ * thing to notice is then a failing tool call, which reads to the person as the
11
+ * product contradicting itself.
12
+ *
13
+ * This asks the Host to re-check, on a cadence, and stops the moment the answer
14
+ * cannot matter.
15
+ *
16
+ * ## Why the cadence lives in the browser
17
+ *
18
+ * The Host cannot see whether a window is on screen. A timer there would keep
19
+ * spending IAM quota on a credential nobody is looking at — and a desktop app
20
+ * is usually open and unwatched, which is exactly the case a Host timer handles
21
+ * badly. `document.visibilityState` is the fact only this side has.
22
+ *
23
+ * ## When it does not run
24
+ *
25
+ * Three states, and each is a reason not to ask rather than a reason to ask
26
+ * less often:
27
+ *
28
+ * - **Nothing stored.** There is no credential to verify; the form is the
29
+ * only way one arrives, and a save starts the watch again.
30
+ * - **The page is hidden.** A status that changed while the person was away
31
+ * is picked up on the first tick after they come back, and until then there
32
+ * is nobody to be misled.
33
+ * - **IAM is unreachable.** The credential is probably fine and IAM is not;
34
+ * retrying on the ordinary period turns one outage into a steady stream of
35
+ * failing calls. Backing off is what keeps a temporary fault temporary.
36
+ *
37
+ * The decision itself is in `../revalidate.ts` so it is drivable from a spec;
38
+ * this module owns the timer and the fetch, which are not.
39
+ *
40
+ * @module @huaweidevtools/aishell-dsh-client-credentials/client/credential-watch
41
+ */
42
+ /** What one revalidation found, as the route reports it. */
43
+ export type RevalidateState =
44
+ /** IAM accepted the pair. */
45
+ 'valid'
46
+ /** IAM refused it; the Host has cleared the store. */
47
+ | 'discarded'
48
+ /** No credential is stored here. */
49
+ | 'absent'
50
+ /** The call did not reach IAM. Says nothing about the credential. */
51
+ | 'unreachable';
52
+ /** How often to re-check while the page is visible and IAM answers. */
53
+ export declare const WATCH_PERIOD_MS = 60000;
54
+ /** Collaborators the watch runs against; injected so a spec can drive it. */
55
+ export interface CredentialWatchDeps {
56
+ /** Whether a credential is currently stored, as the status document says. */
57
+ readonly hasCredential: () => boolean;
58
+ /** Asks the Host to re-check. Resolves `undefined` when the route could not be reached. */
59
+ readonly revalidate: (signal: AbortSignal) => Promise<RevalidateState | undefined>;
60
+ /** Whether a page can see the watch run; defaults to `document.visibilityState`. */
61
+ readonly isVisible?: () => boolean;
62
+ }
63
+ /** The watch, as the plugin body holds it. */
64
+ export interface CredentialWatch {
65
+ /**
66
+ * Schedule a check from now, keeping the backoff.
67
+ *
68
+ * For a page becoming visible: the person is back, but nothing about the
69
+ * credential changed, so an unreachable IAM is still unreachable and the
70
+ * backoff it earned still stands.
71
+ */
72
+ readonly arm: () => void;
73
+ /**
74
+ * Schedule a check from now and forget the backoff.
75
+ *
76
+ * For a credential arriving. A save or a login replaces the material being
77
+ * verified, so whatever failed before was a different question.
78
+ */
79
+ readonly reset: () => void;
80
+ /** Stop the timer. Called when the plugin fiber is disposed. */
81
+ readonly stop: () => void;
82
+ }
83
+ /**
84
+ * Start watching the stored credential.
85
+ *
86
+ * One timer, re-armed after each check rather than running on a fixed interval:
87
+ * the delay depends on the last answer, and an interval would either ignore the
88
+ * backoff or have to be torn down and rebuilt for it.
89
+ *
90
+ * @param deps - presence, the check, and what to do with its answer.
91
+ * @returns the handle the caller uses to restart or stop it.
92
+ */
93
+ export declare function startCredentialWatch(deps: CredentialWatchDeps): CredentialWatch;
94
+ //# sourceMappingURL=credential-watch.d.ts.map
@@ -0,0 +1,114 @@
1
+ /**
2
+ * Re-checking a stored credential against IAM, and acting on the answer.
3
+ *
4
+ * ## What this governs
5
+ *
6
+ * A stored pair can stop working without anything about it changing: a
7
+ * temporary credential's token expires, a permanent key is deleted in the
8
+ * console. Nothing in the store moves, so a reader of the store keeps reporting
9
+ * a credential that IAM would now refuse.
10
+ *
11
+ * The question "is this still usable?" is therefore asked of IAM, and its three
12
+ * possible answers are not interchangeable — which is what this module exists
13
+ * to keep straight. The same classification serves the background check and the
14
+ * `auth` tool, so a chip that reads "signed in" and a tool that reports "no
15
+ * credentials" cannot be the same moment seen twice.
16
+ *
17
+ * ## The three answers, and what each may do to the store
18
+ *
19
+ * - **Accepted.** Nothing to change; the account name is refreshed.
20
+ * - **Refused** (401/403). The pair cannot be used again, so it is discarded
21
+ * and the interface returns to "not configured". Re-entering the same bytes
22
+ * cannot help, which is why this is the only case that clears.
23
+ * - **Unreachable** (status 0, or 5xx). Says nothing about the credential.
24
+ * Clearing here would log a person out because their network blipped.
25
+ *
26
+ * That third case is the one a poll must not turn into a logout, and the one a
27
+ * background loop makes easy to get wrong: a laptop waking from sleep, an IAM
28
+ * outage, a proxy dropping the call all look like "the credential is bad" if
29
+ * the only question asked is whether verification succeeded.
30
+ *
31
+ * @module @huaweidevtools/aishell-dsh-client-credentials/revalidate
32
+ */
33
+ import type { SignCredentials } from '@huaweidevtools/aishell-dsh-credentials-store/signer';
34
+ /** What one verification said about the credential, in the terms callers act on. */
35
+ export type Validity =
36
+ /** IAM accepted the pair. */
37
+ {
38
+ readonly kind: 'valid';
39
+ readonly accountName: string;
40
+ }
41
+ /** IAM refused the pair itself; it cannot be used again. */
42
+ | {
43
+ readonly kind: 'refused';
44
+ readonly message: string;
45
+ }
46
+ /** The question never reached IAM, or IAM failed to answer. The pair may be fine. */
47
+ | {
48
+ readonly kind: 'unreachable';
49
+ readonly message: string;
50
+ };
51
+ /** Collaborators one revalidation runs against; injected so it is testable. */
52
+ export interface RevalidateDeps {
53
+ /** Verifies against IAM; resolves the account name, or rejects with a status-carrying error. */
54
+ readonly verify: (credential: SignCredentials) => Promise<string>;
55
+ /**
56
+ * Whether a verify failure means IAM refused the credential.
57
+ *
58
+ * Asked of the error rather than re-derived from a message: the classification
59
+ * lives in one place (the host's `isRejection`), and a second copy would
60
+ * disagree with it the first time the wording changed.
61
+ */
62
+ readonly isRejection: (error: unknown) => boolean;
63
+ /** Removes the stored pair and announces the change. Called only when refused. */
64
+ readonly discard: () => void;
65
+ }
66
+ /**
67
+ * Verify one stored pair, and discard it if IAM refused it.
68
+ *
69
+ * The discard is inside this function on purpose. Every caller that verifies a
70
+ * stored pair has to make the same judgement about a refusal, and the one that
71
+ * forgets leaves a credential the interface keeps advertising. Making it part
72
+ * of "verify" means a caller cannot skip it by not knowing about it.
73
+ *
74
+ * @param credential - the pair to verify.
75
+ * @param deps - verifier, refusal test, and the discard action.
76
+ * @returns what the check found, in terms the caller can act on.
77
+ */
78
+ export declare function revalidate(credential: SignCredentials, deps: RevalidateDeps): Promise<Validity>;
79
+ /**
80
+ * How long to wait before the next background check.
81
+ *
82
+ * ## Why the interval is a function
83
+ *
84
+ * A fixed period is wrong in both directions. Checking a credential that has
85
+ * never been stored verifies nothing; checking while the page is hidden spends
86
+ * IAM quota to tell nobody anything; and retrying an IAM outage every minute
87
+ * turns one outage into a steady stream of failing calls.
88
+ *
89
+ * ## The ladder
90
+ *
91
+ * - Nothing stored → no check. There is no credential to ask about, and the
92
+ * form is the only way one arrives.
93
+ * - Page hidden → no check. The person is not looking; a status that changed
94
+ * while they were away is picked up on the next visible tick, and the
95
+ * visible tick is what the interface is honest about.
96
+ * - Last check unreachable → back off, doubling to a ceiling. This is the
97
+ * case that must not become a retry storm: the credential is probably fine
98
+ * and IAM is not.
99
+ * - Otherwise → the ordinary period.
100
+ *
101
+ * Returns `undefined` for "do not schedule another check", which is distinct
102
+ * from a very long delay: a hidden page or an empty store stops the loop, and
103
+ * something else (a visibility change, a save) is what starts it again.
104
+ *
105
+ * @param input - current state, as the caller observes it.
106
+ * @returns milliseconds until the next check, or `undefined` to stop.
107
+ */
108
+ export declare function nextCheckDelay(input: {
109
+ readonly hasCredential: boolean;
110
+ readonly visible: boolean;
111
+ readonly consecutiveUnreachable: number;
112
+ readonly periodMs: number;
113
+ }): number | undefined;
114
+ //# sourceMappingURL=revalidate.d.ts.map
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@huaweidevtools/aishell-dsh-client-credentials",
3
3
  "description": "AI Shell credentials — chip-opened web form for storing Huawei Cloud AK/SK in the credential store",
4
- "version": "0.0.23",
4
+ "version": "0.0.25",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
@@ -43,33 +43,33 @@
43
43
  },
44
44
  "license": "Apache-2.0",
45
45
  "dependencies": {
46
- "@deepseek-ai/dsh-client-store": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
46
+ "@deepseek-ai/dsh-client-store": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
47
47
  "immer": "^10.1.3",
48
48
  "zustand": "~4.5.7",
49
- "@huaweidevtools/aishell-dsh-credentials-store": "0.0.23"
49
+ "@huaweidevtools/aishell-dsh-credentials-store": "0.0.25"
50
50
  },
51
51
  "peerDependencies": {
52
- "@deepseek-ai/cordis": "^4.0.4",
53
- "@deepseek-ai/dsh-client-connection": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
54
- "@deepseek-ai/dsh-settings": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
55
- "@deepseek-ai/dsh-tools": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2"
52
+ "@deepseek-ai/cordis": "^4.1.0",
53
+ "@deepseek-ai/dsh-client-connection": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
54
+ "@deepseek-ai/dsh-settings": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
55
+ "@deepseek-ai/dsh-tools": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3"
56
56
  },
57
57
  "devDependencies": {
58
- "@deepseek-ai/cordis": "^4.0.4",
59
- "@deepseek-ai/cordis-plugin-loader": "^1.0.5",
60
- "@deepseek-ai/dsh-client-connection": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
61
- "@deepseek-ai/dsh-client-locale": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
62
- "@deepseek-ai/dsh-client-ui-conversation": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
63
- "@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
64
- "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
65
- "@deepseek-ai/dsh-client-ui-session": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
66
- "@deepseek-ai/dsh-client-ui-settings": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
67
- "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
68
- "@deepseek-ai/dsh-client-ui-workspace": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
69
- "@deepseek-ai/dsh-session": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
70
- "@deepseek-ai/dsh-settings": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
71
- "@deepseek-ai/dsh-tools": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
72
- "@deepseek-ai/schemastery": "3.18.4",
58
+ "@deepseek-ai/cordis": "^4.1.0",
59
+ "@deepseek-ai/cordis-plugin-loader": "^1.1.0",
60
+ "@deepseek-ai/dsh-client-connection": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
61
+ "@deepseek-ai/dsh-client-locale": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
62
+ "@deepseek-ai/dsh-client-ui-conversation": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
63
+ "@deepseek-ai/dsh-client-ui-primitives": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
64
+ "@deepseek-ai/dsh-client-ui-renderer": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
65
+ "@deepseek-ai/dsh-client-ui-session": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
66
+ "@deepseek-ai/dsh-client-ui-settings": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
67
+ "@deepseek-ai/dsh-client-ui-slots": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
68
+ "@deepseek-ai/dsh-client-ui-workspace": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
69
+ "@deepseek-ai/dsh-session": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
70
+ "@deepseek-ai/dsh-settings": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
71
+ "@deepseek-ai/dsh-tools": "0.2.2-rc.1 || 0.2.2-rc.2 || 0.2.2-rc.3",
72
+ "@deepseek-ai/schemastery": "3.19.0",
73
73
  "@types/react": "~18.3.1",
74
74
  "react": "^18.2.0",
75
75
  "tsdown": "^0.10.0",