@huaweidevtools/aishell-dsh-client-credentials 0.0.8 → 0.0.10

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/index.js CHANGED
@@ -1227,9 +1227,9 @@ const LOGIN_OUTCOME_FIELD = "loginOutcome";
1227
1227
  *
1228
1228
  * Any non-safelisted header would do it; this one names why. Declared here
1229
1229
  * because both halves need the same string and neither owns it: the browser
1230
- * half sends it, the host's listener must allow it in its preflight answer,
1231
- * and a mismatch between the two is a probe that fails on a deployment that
1232
- * would actually work — the entry hidden for no reason.
1230
+ * half sends it on the loopback fetch, the host's listener must allow it in
1231
+ * its preflight answer, and a mismatch between the two is a probe that fails
1232
+ * on a route that would actually work — the entry hidden for no reason.
1233
1233
  */
1234
1234
  const PROBE_HEADER = "x-aishell-probe";
1235
1235
  /**
@@ -1460,6 +1460,114 @@ const PNA_REQUEST_HEADER = "access-control-request-private-network";
1460
1460
  /** Query parameter carrying the probe nonce. */
1461
1461
  const PROBE_NONCE_PARAM = "n";
1462
1462
  /**
1463
+ * Borrow a loopback port, answer one probe, and give it back.
1464
+ *
1465
+ * ## What this is for
1466
+ *
1467
+ * The cloud posts a credential to `127.0.0.1` **as the browser's machine
1468
+ * resolves it**, so a browser login works only when that browser can reach a
1469
+ * listener on this host. Neither side can tell by looking — an SSH-forwarded
1470
+ * session makes a distant browser look local to the host and a distant host
1471
+ * look local to the page — so the page fetches a URL and the fetch is the
1472
+ * answer. A fetch that resolves means the page reached a socket here.
1473
+ *
1474
+ * ## How it ends
1475
+ *
1476
+ * Two ways, whichever comes first:
1477
+ *
1478
+ * - **Someone reaches it.** The response is written, and the socket closes
1479
+ * immediately after — the question has been answered, so the port has no
1480
+ * further use.
1481
+ * - **{@link PROBE_WINDOW_MS} passes.** Nobody came, which is itself an
1482
+ * answer (this browser cannot reach loopback), and the socket closes.
1483
+ *
1484
+ * Either way the port is held for seconds at most. A probe borrowed to ask one
1485
+ * question must not outlive the asking — a card left open would otherwise keep
1486
+ * a socket for the life of the page, which is what the earlier design did.
1487
+ *
1488
+ * ## Why the nonce
1489
+ *
1490
+ * The probe answers whatever origin asks, because the page's own origin is by
1491
+ * definition not one of the cloud's. That is only safe with a secret: without
1492
+ * one, any page that swept local ports would get an answer, making this a
1493
+ * fingerprinting beacon for the plugin's presence. A caller without the nonce
1494
+ * is answered exactly as an empty port would be.
1495
+ *
1496
+ * ## What the caller gets, and what it does not
1497
+ *
1498
+ * A URL and nothing else. The caller cannot observe the port closing — it
1499
+ * closes on its own, either on being reached or when the window runs out — and
1500
+ * a promise for that would be a handle no caller has a use for. Awaiting it
1501
+ * would also mean a route waiting up to the whole window before answering,
1502
+ * which is precisely what the page cannot afford.
1503
+ *
1504
+ * @param path - the path the probe is served on.
1505
+ * @returns the URL to hand the page.
1506
+ */
1507
+ async function probeLoopback(path) {
1508
+ const bound = await bindLoopback();
1509
+ const nonce = randomProbeNonce();
1510
+ const reachable = Promise.withResolvers();
1511
+ bound.serve(
1512
+ // A plan that matches nothing: this listener exists only for the probe, so
1513
+ // a callback arriving here is a stray and is refused by the path check.
1514
+ {
1515
+ address: bound.address,
1516
+ path: "\0",
1517
+ method: "POST",
1518
+ correlation: "none"
1519
+ },
1520
+ {
1521
+ path,
1522
+ nonce,
1523
+ onAnswered: () => {
1524
+ reachable.resolve(true);
1525
+ bound.close();
1526
+ }
1527
+ }
1528
+ );
1529
+ const timer = setTimeout(() => {
1530
+ reachable.resolve(false);
1531
+ bound.close();
1532
+ }, PROBE_WINDOW_MS);
1533
+ unrefIfPossible(timer);
1534
+ reachable.promise.then(() => {
1535
+ clearTimeout(timer);
1536
+ });
1537
+ return { probeUrl: `http://${bound.address}${path}?n=${nonce}` };
1538
+ }
1539
+ /**
1540
+ * Detach a timer from the event loop, when the runtime has that notion.
1541
+ *
1542
+ * Node's timer objects carry `unref`; a browser's are numbers. This package's
1543
+ * tsconfig compiles against the DOM signature (the browser half is most of
1544
+ * it), so the method is reached through a narrow cast rather than declared.
1545
+ *
1546
+ * Exported because the login's deadline needs the same treatment, and two
1547
+ * copies of a three-line cast is how they drift.
1548
+ *
1549
+ * @param timer - the timer handle, of whichever shape this runtime uses.
1550
+ */
1551
+ function unrefIfPossible(timer) {
1552
+ const candidate = timer;
1553
+ if (typeof candidate?.unref === "function") candidate.unref();
1554
+ }
1555
+ /**
1556
+ * How long a probe port is held.
1557
+ *
1558
+ * Generous for a request that takes under a millisecond when it works, because
1559
+ * the cost of the wait is a bound port and the cost of being too quick is
1560
+ * calling a working route unsupported. A page that is slow to get going —
1561
+ * a large bundle still parsing — still gets its answer.
1562
+ */
1563
+ const PROBE_WINDOW_MS = 3e4;
1564
+ /** A value that cannot be guessed from the port alone. */
1565
+ function randomProbeNonce() {
1566
+ const bytes = new Uint8Array(16);
1567
+ globalThis.crypto.getRandomValues(bytes);
1568
+ return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
1569
+ }
1570
+ /**
1463
1571
  * Whether an `Origin` matches an allowed origin exactly.
1464
1572
  *
1465
1573
  * Exact comparison, deliberately: a suffix or prefix rule would admit
@@ -1648,6 +1756,7 @@ async function bindLoopback() {
1648
1756
  return;
1649
1757
  }
1650
1758
  writePreflight(response, origin$2, "GET, OPTIONS", PROBE_HEADER, allowPrivateNetwork, request);
1759
+ probe.onAnswered?.();
1651
1760
  return;
1652
1761
  }
1653
1762
  if (method !== "GET" || !isProbe(request)) {
@@ -1661,6 +1770,7 @@ async function bindLoopback() {
1661
1770
  vary: "Origin"
1662
1771
  });
1663
1772
  response.end();
1773
+ probe.onAnswered?.();
1664
1774
  return;
1665
1775
  }
1666
1776
  if (method === "OPTIONS") {
@@ -1728,12 +1838,6 @@ async function bindLoopback() {
1728
1838
 
1729
1839
  //#endregion
1730
1840
  //#region src/out-of-band/login.ts
1731
- /** A value that cannot be guessed from the port alone. */
1732
- function randomNonce() {
1733
- const bytes = new Uint8Array(16);
1734
- globalThis.crypto.getRandomValues(bytes);
1735
- return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
1736
- }
1737
1841
  /**
1738
1842
  * How long to wait when the service does not say.
1739
1843
  *
@@ -1743,45 +1847,26 @@ function randomNonce() {
1743
1847
  */
1744
1848
  const DEFAULT_EXPIRES_SECONDS = 600;
1745
1849
  /**
1746
- * Detach a timer from the event loop, when the runtime has that notion.
1747
- *
1748
- * Node's timer objects carry `unref`; a browser's are numbers. This package's
1749
- * tsconfig compiles against the DOM signature (the browser half is most of
1750
- * it), so the method is reached through a narrow cast rather than declared.
1751
- *
1752
- * @param timer - the timer handle, of whichever shape this runtime uses.
1753
- */
1754
- function unrefIfPossible(timer) {
1755
- const candidate = timer;
1756
- if (typeof candidate?.unref === "function") candidate.unref();
1757
- }
1758
- /**
1759
1850
  * Begin a browser login.
1760
1851
  *
1761
- * Everything it returns is settled by the time it returns except `credential`,
1762
- * which resolves when the person finishes signing in. The bind, the plan fetch
1763
- * and the plan check all happen first, so a caller that gets a login back
1764
- * knows there is a listener and somewhere to send the browser — a failure in
1765
- * any of those throws instead.
1852
+ * Binds its own listener and fetches a login URL projected for it, so both are
1853
+ * as fresh as the moment the person clicked — see the module note for why that
1854
+ * matters. Everything except `credential` is settled by the time this returns;
1855
+ * a failure to bind, reach the service, or match the plan throws instead.
1766
1856
  *
1767
- * @param options - provider, verifier, and the probe path.
1857
+ * @param options - the provider and the verifier.
1768
1858
  * @returns the running login.
1769
1859
  * @throws {AuthContractError} when the port cannot be bound, the service
1770
1860
  * cannot be reached, or the plan names an address this machine is not on.
1771
1861
  */
1772
1862
  async function startBrowserLogin(options) {
1773
- const { provider, verify, probePath, contract } = options;
1863
+ const { provider, verify, contract } = options;
1774
1864
  const bound = await bindLoopback();
1775
1865
  let cancelled = false;
1776
1866
  try {
1777
1867
  const target = await requestLogin(provider.id, `http://${bound.address}/`, contract);
1778
1868
  if (target.callback.address !== "" && target.callback.address !== bound.address) throw new AuthContractError(`The login service expects the callback at ${target.callback.address}, but this machine is listening on ${bound.address}. Refusing to wait for a callback that cannot arrive.`);
1779
- const nonce = randomNonce();
1780
- const listener = bound.serve(target.callback, {
1781
- path: probePath,
1782
- nonce
1783
- });
1784
- const probeUrl = `http://${bound.address}${probePath}?n=${nonce}`;
1869
+ const listener = bound.serve(target.callback);
1785
1870
  const expiresInSeconds = target.expires_in > 0 ? target.expires_in : DEFAULT_EXPIRES_SECONDS;
1786
1871
  let settleCredential;
1787
1872
  let failCredential;
@@ -1791,12 +1876,11 @@ async function startBrowserLogin(options) {
1791
1876
  const credential = completion.promise;
1792
1877
  credential.catch(() => {});
1793
1878
  (async () => {
1794
- const expirySeconds = expiresInSeconds;
1795
1879
  let expiry;
1796
1880
  const expired = new Promise((resolve) => {
1797
1881
  expiry = setTimeout(() => {
1798
1882
  resolve("expired");
1799
- }, expirySeconds * 1e3);
1883
+ }, expiresInSeconds * 1e3);
1800
1884
  unrefIfPossible(expiry);
1801
1885
  });
1802
1886
  let payload;
@@ -1807,7 +1891,7 @@ async function startBrowserLogin(options) {
1807
1891
  })), expired.then(() => ({ kind: "expired" }))]);
1808
1892
  if (outcome.kind === "expired") {
1809
1893
  bound.close();
1810
- failCredential(new AuthContractError(`The browser sign-in was not completed within ${String(Math.round(expirySeconds / 60))} minutes. Open the credential form again to retry.`));
1894
+ failCredential(new AuthContractError(`The browser sign-in was not completed within ${String(Math.round(expiresInSeconds / 60))} minutes. Start it again when you are ready.`));
1811
1895
  return;
1812
1896
  }
1813
1897
  payload = outcome.value;
@@ -1839,7 +1923,6 @@ async function startBrowserLogin(options) {
1839
1923
  })();
1840
1924
  return {
1841
1925
  address: bound.address,
1842
- probeUrl,
1843
1926
  loginUrl: target.login_url,
1844
1927
  expiresInSeconds,
1845
1928
  credential,
@@ -1858,17 +1941,19 @@ async function startBrowserLogin(options) {
1858
1941
 
1859
1942
  //#endregion
1860
1943
  //#region src/out-of-band/routes.ts
1944
+ /** Path the browser half posts to, to ask whether the browser route works here. */
1945
+ const LOGIN_PROBE_ROUTE = "/api/aishell/credentials/login/probe";
1861
1946
  /** Path the browser half posts to, to begin a login. */
1862
1947
  const LOGIN_START_PATH = "/api/aishell/credentials/login/start";
1863
1948
  /** Path the browser half posts to, to abandon a login. */
1864
1949
  const LOGIN_CANCEL_PATH = "/api/aishell/credentials/login/cancel";
1865
1950
  /**
1866
- * Path the probe is served on, on the callback listener.
1951
+ * Path the probe is served on.
1867
1952
  *
1868
- * On the listener rather than the host's `/api` route deliberately: the
1869
- * question is whether the browser can reach *that* socket, so the probe has to
1870
- * be answered there. Under a name no provider will use as a callback path —
1871
- * the shipped provider posts to the root, so anything else is free.
1953
+ * On the borrowed listener rather than the host's `/api` route: the question is
1954
+ * whether the browser can reach *that* socket, so the probe has to be answered
1955
+ * there. Under a name no provider will use as a callback path — the shipped
1956
+ * provider posts to the root, so anything else is free.
1872
1957
  */
1873
1958
  const LOGIN_PROBE_PATH = "/__aishell_probe";
1874
1959
  /** One JSON response the browser half reads. */
@@ -1889,8 +1974,21 @@ async function readBody(request) {
1889
1974
  }
1890
1975
  /** The login routes, bound to their collaborators. */
1891
1976
  function createLoginRoutes(deps) {
1892
- const { findProvider: findProvider$1, begin, cancel, inProgress } = deps;
1977
+ const { findProvider: findProvider$1, probe, begin, cancel, inProgress } = deps;
1893
1978
  return {
1979
+ probe: async () => {
1980
+ try {
1981
+ return json({
1982
+ ok: true,
1983
+ ...await probe()
1984
+ });
1985
+ } catch (error) {
1986
+ return json({
1987
+ ok: false,
1988
+ error: error instanceof Error ? error.message : String(error)
1989
+ }, 503);
1990
+ }
1991
+ },
1894
1992
  start: async (request) => {
1895
1993
  if (inProgress()) return json({
1896
1994
  ok: false,
@@ -1947,6 +2045,10 @@ function createLoginFlow(deps) {
1947
2045
  };
1948
2046
  return {
1949
2047
  findProvider: (providerId) => findProvider(providerId, contract),
2048
+ probe: async () => {
2049
+ const { probeUrl } = await probeLoopback(LOGIN_PROBE_PATH);
2050
+ return { probeUrl };
2051
+ },
1950
2052
  inProgress: () => active !== void 0,
1951
2053
  cancel: () => {
1952
2054
  const login = active;
@@ -1958,7 +2060,6 @@ function createLoginFlow(deps) {
1958
2060
  if (active !== void 0) throw new AuthContractError("A browser login is already in progress.");
1959
2061
  const login = await startBrowserLogin({
1960
2062
  provider,
1961
- probePath: LOGIN_PROBE_PATH,
1962
2063
  contract,
1963
2064
  verify
1964
2065
  });
@@ -1997,7 +2098,6 @@ function createLoginFlow(deps) {
1997
2098
  return {
1998
2099
  ok: true,
1999
2100
  loginUrl: login.loginUrl,
2000
- probeUrl: login.probeUrl,
2001
2101
  providerName: provider.display_name,
2002
2102
  expiresInSeconds: login.expiresInSeconds
2003
2103
  };
@@ -2395,6 +2495,37 @@ function apply(ctx, config) {
2395
2495
  * awaiting.
2396
2496
  */
2397
2497
  let pendingForm;
2498
+ /**
2499
+ * Settle the pending request and withdraw it from the document.
2500
+ *
2501
+ * One helper on purpose: the field is **persisted** — it is this entry's row
2502
+ * in the profile — so a request left in the document outlives the call that
2503
+ * made it. On the next boot the browser half reads that stale value and opens
2504
+ * the form for a question nobody is asking, which is why a fresh install
2505
+ * showed a credential form unprompted.
2506
+ *
2507
+ * Every path that answers a request goes through here. Writing the clear
2508
+ * beside each settle instead would work until someone added a path and
2509
+ * forgot, and the symptom would be an unexplained form on a later boot.
2510
+ *
2511
+ * @param outcome - what the person did, or `undefined` to abandon without
2512
+ * answering (used for the release path, where nothing is waiting).
2513
+ * @param expected - the request being settled. When given, a settle for a
2514
+ * different request is ignored, so a late answer cannot clear a form
2515
+ * somebody else is looking at.
2516
+ */
2517
+ const settleFormRequest = (outcome, expected) => {
2518
+ if (expected !== void 0 && pendingForm !== expected) return;
2519
+ const pending = pendingForm;
2520
+ pendingForm = void 0;
2521
+ if (pending !== void 0 && outcome !== void 0) pending.settle(outcome);
2522
+ if (ns !== void 0) ctx.settings.mutate(ns, [{
2523
+ op: "unset",
2524
+ path: [FORM_REQUEST_FIELD]
2525
+ }]).catch((error) => {
2526
+ ctx.logger.warn(error);
2527
+ });
2528
+ };
2398
2529
  /** Apply one batch of ops to the mirror. */
2399
2530
  const mirrorOps = (ops) => {
2400
2531
  for (const op of ops) if (op.path[0] === "credentialsStored") recordedStored = op.op === "set" && op.value === true;
@@ -2452,11 +2583,7 @@ function apply(ctx, config) {
2452
2583
  headers: request.headers,
2453
2584
  body
2454
2585
  }));
2455
- if (response.ok && requestToken !== void 0 && pendingForm !== void 0 && pendingForm.request.token === requestToken) {
2456
- const pending = pendingForm;
2457
- pendingForm = void 0;
2458
- pending.settle({ kind: "submitted" });
2459
- }
2586
+ if (response.ok && requestToken !== void 0 && pendingForm !== void 0 && pendingForm.request.token === requestToken) settleFormRequest({ kind: "submitted" }, pendingForm);
2460
2587
  return response;
2461
2588
  }
2462
2589
  }), "aishell-credentials: credentials route");
@@ -2479,11 +2606,7 @@ function apply(ctx, config) {
2479
2606
  ok: false,
2480
2607
  error: "token is required."
2481
2608
  }, { status: 400 });
2482
- if (pendingForm !== void 0 && pendingForm.request.token === token) {
2483
- const pending = pendingForm;
2484
- pendingForm = void 0;
2485
- pending.settle({ kind: "cancelled" });
2486
- }
2609
+ if (pendingForm !== void 0 && pendingForm.request.token === token) settleFormRequest({ kind: "cancelled" }, pendingForm);
2487
2610
  return Response.json({ ok: true });
2488
2611
  }
2489
2612
  }), "aishell-credentials: cancel route");
@@ -2546,19 +2669,22 @@ function apply(ctx, config) {
2546
2669
  }
2547
2670
  ]);
2548
2671
  announceCredentialsChanged();
2549
- const pending = pendingForm;
2550
- if (pending !== void 0) {
2551
- pendingForm = void 0;
2552
- pending.settle({ kind: "submitted" });
2553
- }
2672
+ settleFormRequest({ kind: "submitted" });
2554
2673
  }
2555
2674
  });
2556
2675
  const loginRoutes = createLoginRoutes({
2557
2676
  findProvider: loginFlow.findProvider,
2677
+ probe: loginFlow.probe,
2558
2678
  begin: loginFlow.begin,
2559
2679
  cancel: loginFlow.cancel,
2560
2680
  inProgress: loginFlow.inProgress
2561
2681
  });
2682
+ ctx.effect(() => ctx.connection.fetch.register({
2683
+ path: LOGIN_PROBE_ROUTE,
2684
+ methods: ["POST"],
2685
+ requestBody: "buffered",
2686
+ fetch: loginRoutes.probe
2687
+ }), "aishell-credentials: browser login probe route");
2562
2688
  ctx.effect(() => ctx.connection.fetch.register({
2563
2689
  path: LOGIN_START_PATH,
2564
2690
  methods: ["POST"],
@@ -2586,6 +2712,12 @@ function apply(ctx, config) {
2586
2712
  reconciler.reconcile();
2587
2713
  const reconcileTimer = setInterval(reconciler.reconcile, 3e4);
2588
2714
  ctx.effect(() => () => clearInterval(reconcileTimer), "aishell-credentials: status reconcile timer");
2715
+ if (ns !== void 0 && config.credentialFormRequest.get() !== "") ctx.settings.mutate(ns, [{
2716
+ op: "unset",
2717
+ path: [FORM_REQUEST_FIELD]
2718
+ }]).catch((error) => {
2719
+ ctx.logger.warn(error);
2720
+ });
2589
2721
  registerAuthTool(ctx, store, {
2590
2722
  requestForm: (sessionId) => {
2591
2723
  if (ns === void 0) return void 0;
@@ -2598,19 +2730,12 @@ function apply(ctx, config) {
2598
2730
  value: pending.encoded
2599
2731
  }]).catch((error) => {
2600
2732
  ctx.logger.warn(error);
2601
- if (pendingForm === pending) {
2602
- pendingForm = void 0;
2603
- pending.settle({ kind: "cancelled" });
2604
- }
2733
+ settleFormRequest({ kind: "cancelled" }, pending);
2605
2734
  });
2606
2735
  return pending.outcome;
2607
2736
  },
2608
2737
  releaseForm: () => {
2609
- const pending = pendingForm;
2610
- if (pending !== void 0) {
2611
- pendingForm = void 0;
2612
- pending.settle({ kind: "cancelled" });
2613
- }
2738
+ settleFormRequest({ kind: "cancelled" });
2614
2739
  loginFlow.cancel();
2615
2740
  }
2616
2741
  });
@@ -1,32 +1,33 @@
1
1
  /**
2
- * The credential form — the one surface where credentials are entered.
2
+ * The credential card — the one surface where credentials are entered.
3
3
  *
4
- * A masked AK/SK form rendered into `conversation.composer`, taking over the
5
- * input box the way the approval panel does. A credential chip opens it; that
6
- * is the only door, and the form is the only place a credential is entered.
4
+ * Rendered into `conversation.composer`, taking over the input box the way the
5
+ * approval panel does. A credential chip opens it, and `aishell__auth` asks for
6
+ * it when a tool call has no usable credential.
7
7
  *
8
- * Submitting goes through the Host credential route, which verifies against IAM
9
- * and writes the store. The form closes itself after a successful save — the
10
- * chip flipping to the account name is the confirmation, so no "saved" banner
11
- * is needed — and closes when the person cancels.
8
+ * ## Two states, decided by whether a credential is stored
12
9
  *
13
- * Nothing here ever receives the stored secret back: the form posts it and the
14
- * route answers with a verdict, so neither the browser nor the conversation
15
- * holds the credential afterwards.
10
+ * The card shows **one** of two things, and nothing else:
16
11
  *
17
- * ## Why the composer and not a modal
12
+ * - **Signed in** — the account name, a way to accept it, and a way out. No
13
+ * inputs, because the question a signed-in person has is "who am I, and am
14
+ * I done", not "what is your access key". `确认` answers a waiting
15
+ * `aishell__auth`; `退出` clears the credential.
16
+ * - **Not signed in** — both ways to obtain a credential, side by side.
18
17
  *
19
- * The form belongs where the person's attention already is and where they act:
20
- * the composer. It is the same seat the approval panel uses — a surface that
21
- * takes over the input box while something needs an answer. The takeover works
22
- * on the blank New-Session page exactly as it does mid-conversation.
18
+ * An earlier version spread this across four pages (`choose` / `manual` /
19
+ * `waiting` plus a "deciding" state) and moved between them as the probe
20
+ * answered. The pages were the same card wearing different hats — the person
21
+ * sees one panel either way — and the transitions were visible: fields appeared
22
+ * and were replaced a moment later. One upright card with a button that reports
23
+ * its own state is both smaller and calmer.
23
24
  *
24
- * ## Why masked inputs are not optional
25
+ * ## Why the browser route reports itself in place
25
26
  *
26
- * A secret key typed into a plain field is a secret on screen — in a
27
- * screenshot, a screen-share, or over a shoulder. `type="password"` is the
28
- * whole reason this form exists instead of reusing the question composer, whose
29
- * free-text field is a plain `<textarea>`.
27
+ * The button is the status: `checking` while the probe runs, `login` once it
28
+ * passes, `unsupported` when it fails, `cancel` while a login is in flight with
29
+ * the countdown beside it. A separate page for "waiting" was a second layout to
30
+ * keep in step with the first for no gain.
30
31
  *
31
32
  * @module @huaweidevtools/aishell-dsh-client-credentials/client/CredentialRequestForm
32
33
  */
@@ -53,42 +54,49 @@ export interface CredentialRequestFormInjected {
53
54
  /** Store AK/SK/SecurityToken through the Host credential route. */
54
55
  save: (accessKeyId: string, secretAccessKey: string, securityToken?: string) => Promise<SaveVerdict>;
55
56
  /**
56
- * Begin a browser login, if this deployment can complete one.
57
+ * Ask whether a browser here can reach a loopback listener.
57
58
  *
58
- * Binds a listener on the host and proves this page can reach it. Resolves
59
- * `undefined` when it cannot — which is the ordinary answer when the browser
60
- * runs on a different machine from the host, and the case that hides this
61
- * entry entirely.
59
+ * Called on open, so the button can report whether the route exists here
60
+ * before anyone presses it.
62
61
  *
63
- * The check is re-run every time the form opens: reachability changes with
64
- * VPNs, tunnels and taken ports, so a remembered answer would keep the entry
65
- * hidden after someone fixed their setup.
62
+ * @param signal - aborts the request when the card goes away.
63
+ * @returns whether the browser route works from where this page is loaded.
64
+ */
65
+ probeBrowserRoute: (signal?: AbortSignal) => Promise<boolean>;
66
+ /**
67
+ * Begin a browser login. Called when the person asks for one, not before.
68
+ *
69
+ * Binds its own listener and fetches a URL projected for it at that moment,
70
+ * so the URL is fresh however long the card sat open.
66
71
  *
67
- * @returns a started login, or `undefined` when the path is unavailable.
72
+ * @returns a handle for the login in flight, or `undefined` on failure.
68
73
  */
69
- startBrowserLogin: () => Promise<BrowserLoginHandle | undefined>; /**
74
+ startBrowserLogin: () => Promise<BrowserLoginHandle | undefined>;
75
+ /**
70
76
  * Values the host already has, to start the fields with.
71
77
  *
72
- * Fills the inputs; it does not submit, does not hide the form, and every
78
+ * Fills the inputs; it does not submit, does not hide the card, and every
73
79
  * field stays editable. The point is to save the person copying three values
74
80
  * out of their shell — not to skip the form.
75
81
  */
76
82
  readPrefill: () => Promise<CredentialPrefill>;
77
- /**
78
- * Clear the stored credentials.
79
- *
80
- * Only invoked from the clear button, which renders only when credentials
81
- * already exist — there is nothing to clear otherwise.
82
- */
83
+ /** Clear the stored credentials. */
83
84
  clear: () => Promise<SaveVerdict>;
85
+ /** Withdraw the card after saving — restores the ordinary composer. */
86
+ close: () => void;
84
87
  /**
85
- * Withdraw the form after saving — restores the ordinary composer.
88
+ * Accept the stored credentials and withdraw the card.
86
89
  *
87
- * Used by the success path, where there is nothing to decline.
90
+ * The signed-in card's affirmative action: the person looked at the account
91
+ * and is done. Distinct from {@link close} because it also answers a waiting
92
+ * `aishell__auth` — without it, a blocked call could only be answered by
93
+ * logging out, which destroys the credential it was waiting to use.
94
+ *
95
+ * Writes nothing and verifies nothing; the caller re-reads the store.
88
96
  */
89
- close: () => void;
97
+ confirm: () => void;
90
98
  /**
91
- * Decline: withdraw the form and tell the host this request was refused.
99
+ * Decline: withdraw the card and tell the host this request was refused.
92
100
  *
93
101
  * The difference matters. Without it the host cannot tell "the person said
94
102
  * no" from "the person has not answered", and a model whose call failed has
@@ -99,12 +107,10 @@ export interface CredentialRequestFormInjected {
99
107
  /** Full component props: composer owner share + locale seat + inject face. */
100
108
  export type CredentialRequestFormProps = PropsRuntime<'conversation.composer'> & PropsLocale<'aishell'> & InjectFace<CredentialRequestFormInjected>;
101
109
  /**
102
- * The masked credential form.
110
+ * The credential card.
103
111
  *
104
- * Submitting saves through the Host route; the form then closes itself, and the
105
- * chip flipping to the account name is the feedback that it worked. There is no
106
- * request behind an open form — a chip opened it — so nothing else takes it
107
- * down.
112
+ * Submitting saves through the Host route; the card then closes itself, and the
113
+ * chip flipping to the account name is the feedback that it worked.
108
114
  */
109
115
  export declare function CredentialRequestForm(props: CredentialRequestFormProps): ReactNode;
110
116
  //# sourceMappingURL=CredentialRequestForm.d.ts.map
@@ -0,0 +1,58 @@
1
+ /**
2
+ * What the browser-login button says and whether it can be pressed.
3
+ *
4
+ * ## Why this is a module
5
+ *
6
+ * The button is the browser route's whole status display: it reports the probe
7
+ * (`checking`), a refusal (`unsupported`), readiness (`login`), and a login in
8
+ * flight (`cancel`). Four states in one control, decided by two inputs, is
9
+ * exactly the kind of table that reads correctly inline and is wrong at the
10
+ * edges — and this package has no component-rendering test tier, so inline
11
+ * means untested.
12
+ *
13
+ * Split out as a pure function for the same reason
14
+ * `./credential-form-visibility` is: the decision is drivable from a spec.
15
+ *
16
+ * ## The label is a locale key
17
+ *
18
+ * Returned as a key rather than as text so the caller keeps the only `t` — the
19
+ * dictionary is the single place the wording lives, and a function returning
20
+ * English would be a second one.
21
+ *
22
+ * @module @huaweidevtools/aishell-dsh-client-credentials/client/card-state
23
+ */
24
+ import type { AishellLocaleKey } from './locales.ts';
25
+ /** The button's state: what it says, and whether it does anything. */
26
+ export interface BrowserButtonState {
27
+ /** Locale key for the label. */
28
+ readonly label: AishellLocaleKey;
29
+ /** Whether the press is refused. */
30
+ readonly disabled: boolean;
31
+ }
32
+ /** Where a browser login has got to. Mirrors the component's `LoginPhase`. */
33
+ export type LoginPhase = 'checking' | 'starting' | 'ready' | 'unsupported' | 'running';
34
+ /**
35
+ * The button's label and enabled state.
36
+ *
37
+ * @param phase - the probe's answer and whether a login is in flight.
38
+ * @param hasCountdown - whether a countdown is being shown. Unused by the
39
+ * label, which names the action rather than the remaining time — the
40
+ * countdown sits above the button where it can be read without the label
41
+ * changing under the pointer. Kept in the signature so callers pass the same
42
+ * pair the render does, and so a future state that does depend on it has
43
+ * somewhere to say so.
44
+ * @returns the label key and whether the button is disabled.
45
+ */
46
+ export declare function browserButton(phase: LoginPhase, hasCountdown: boolean): BrowserButtonState;
47
+ /**
48
+ * Render a countdown as `m:ss`.
49
+ *
50
+ * Language-neutral on purpose: the sentence around it is localised, and a
51
+ * number with a colon needs no translation — spelling out a unit would put a
52
+ * second copy of it in both dictionaries for no gain. Tabular figures are
53
+ * applied at the call site so the digits do not jitter as they change.
54
+ *
55
+ * @param seconds - seconds remaining; negative reads as zero.
56
+ */
57
+ export declare function formatCountdown(seconds: number): string;
58
+ //# sourceMappingURL=card-state.d.ts.map