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

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.
@@ -8,11 +8,17 @@
8
8
  * host reaches, and verification needs the signer. So the host owns the flow
9
9
  * and the browser half asks for each step.
10
10
  *
11
- * ## The two routes, and why there is no third
11
+ * ## The three routes, and why there is no fourth
12
12
  *
13
+ * POST .../login/probe -> borrow a port, answer with where to fetch it
13
14
  * POST .../login/start -> bind, fetch the plan, start serving; answer with
14
- * where to send the browser and where to probe
15
- * POST .../login/cancel -> the person dismissed the form
15
+ * where to send the browser
16
+ * POST .../login/cancel -> the person dismissed the form
17
+ *
18
+ * The probe is separate from the start because they answer different questions
19
+ * at different times: *can this browser reach this host at all* (asked when the
20
+ * card opens, and holding a port for seconds) versus *begin a login* (asked on
21
+ * a click, and holding a port for as long as the person takes).
16
22
  *
17
23
  * There is deliberately no `finish`. The outcome arrives on its own schedule —
18
24
  * whenever the person finishes signing in, up to ten minutes later — so
@@ -26,55 +32,66 @@
26
32
  *
27
33
  * It returns once a listener is bound and a plan is honoured. It says nothing
28
34
  * about whether the browser can *reach* that listener — only a request from
29
- * the browser answers that, which is what `probeUrl` is for. The page fetches
30
- * it and decides; the host is not told the result, because the page's decision
31
- * is the only thing that uses it.
35
+ * the browser answers that, which is what the probe route is for. The page
36
+ * fetches the URL the probe hands it and decides; the host is not told the
37
+ * result, because the page's decision is the only thing that uses it.
32
38
  *
33
39
  * @module @huaweidevtools/aishell-dsh-client-credentials/out-of-band/routes
34
40
  */
35
41
  import type { ProviderInfo } from './contract.ts';
42
+ /** Path the browser half posts to, to ask whether the browser route works here. */
43
+ export declare const LOGIN_PROBE_ROUTE = "/api/aishell/credentials/login/probe";
36
44
  /** Path the browser half posts to, to begin a login. */
37
45
  export declare const LOGIN_START_PATH = "/api/aishell/credentials/login/start";
38
46
  /** Path the browser half posts to, to abandon a login. */
39
47
  export declare const LOGIN_CANCEL_PATH = "/api/aishell/credentials/login/cancel";
40
48
  /**
41
- * Path the probe is served on, on the callback listener.
49
+ * Path the probe is served on.
42
50
  *
43
- * On the listener rather than the host's `/api` route deliberately: the
44
- * question is whether the browser can reach *that* socket, so the probe has to
45
- * be answered there. Under a name no provider will use as a callback path —
46
- * the shipped provider posts to the root, so anything else is free.
51
+ * On the borrowed listener rather than the host's `/api` route: the question is
52
+ * whether the browser can reach *that* socket, so the probe has to be answered
53
+ * there. Under a name no provider will use as a callback path — the shipped
54
+ * provider posts to the root, so anything else is free.
47
55
  */
48
56
  export declare const LOGIN_PROBE_PATH = "/__aishell_probe";
49
- /** What the browser half is told when a login starts. */
57
+ /**
58
+ * What the browser half is told when a login starts.
59
+ *
60
+ * No probe URL here. Whether a browser can reach a loopback listener depends
61
+ * on how the page is reached, not on any login, and is asked once when the card
62
+ * opens. See {@link ProbeAnswer}.
63
+ */
50
64
  export interface LoginStartResult {
51
65
  readonly ok: true;
52
- /** URL to open in the browser. */
66
+ /** URL to open in the browser, projected for the port this login bound. */
53
67
  readonly loginUrl: string;
54
- /**
55
- * URL the page fetches to test whether it can reach the callback listener.
56
- *
57
- * Fetching it is the whole test. A page that cannot reach it will not be
58
- * able to receive the cloud's callback either, which is the case this
59
- * reports early instead of after a ten-minute cloud login.
60
- *
61
- * What it does *not* test: the cloud's own post. That comes from a different
62
- * origin and so exercises CORS and Private Network Access differently. This
63
- * answers only the precondition — is the port reachable from where the
64
- * browser is — which is the part that varies by deployment.
65
- */
66
- readonly probeUrl: string;
67
68
  /** Provider being signed in with, for the copy the form shows. */
68
69
  readonly providerName: string;
69
70
  /**
70
71
  * Seconds until the login stops being completable.
71
72
  *
72
- * The waiting card counts down to this so the person can see how long they
73
- * have, instead of watching an open-ended spinner that will eventually just
74
- * stop.
73
+ * The card counts down to this so the person can see how long they have,
74
+ * instead of watching a wait that will eventually just stop.
75
75
  */
76
76
  readonly expiresInSeconds: number;
77
77
  }
78
+ /**
79
+ * What the browser half is told when it asks whether the route works.
80
+ *
81
+ * Only a URL. The browser fetches it and learns the answer itself: a fetch that
82
+ * resolves means a page on this machine reached a loopback listener, and one
83
+ * that rejects means it did not. Routing that answer back through the host
84
+ * would be a second round trip to learn something the caller already knows.
85
+ *
86
+ * The listener behind the URL closes as soon as it has been reached, or after
87
+ * {@link PROBE_WINDOW_MS} if it never is — a port borrowed to ask one question
88
+ * must not outlive the asking.
89
+ */
90
+ export interface ProbeAnswer {
91
+ readonly ok: true;
92
+ /** URL to fetch, on the listener bound for this probe. */
93
+ readonly probeUrl: string;
94
+ }
78
95
  /** Host-side operations the routes delegate to, injected so they are testable. */
79
96
  export interface LoginRouteDeps {
80
97
  /**
@@ -85,14 +102,24 @@ export interface LoginRouteDeps {
85
102
  */
86
103
  readonly findProvider: (providerId: string) => Promise<ProviderInfo | undefined>;
87
104
  /**
88
- * Bind a listener, fetch the plan, and start serving.
105
+ * Borrow a loopback port and hand back a URL to fetch.
106
+ *
107
+ * The caller's browser fetches it and learns the answer itself; the port is
108
+ * released once it has been reached, or after a short window. Needs no
109
+ * provider: whether a socket here is reachable is a fact about the
110
+ * access route, not about any cloud.
111
+ */
112
+ readonly probe: () => Promise<{
113
+ probeUrl: string;
114
+ }>;
115
+ /**
116
+ * Bind a listener and fetch a login URL projected for it.
89
117
  *
90
- * Resolves once both URLs are known. The credential is not awaited here —
91
- * it arrives whenever the person finishes, and is delivered through the
118
+ * Resolves once the URL is known. The credential is not awaited here — it
119
+ * arrives whenever the person finishes, and is delivered through the
92
120
  * settings document rather than as this call's result.
93
121
  *
94
122
  * @param provider - the provider to sign in with.
95
- * @returns where to send the browser, and where to probe.
96
123
  */
97
124
  readonly begin: (provider: ProviderInfo) => Promise<LoginStartResult>;
98
125
  /** Abandon any login in progress and release its port. */
@@ -102,6 +129,7 @@ export interface LoginRouteDeps {
102
129
  }
103
130
  /** The login routes, bound to their collaborators. */
104
131
  export declare function createLoginRoutes(deps: LoginRouteDeps): {
132
+ probe: () => Promise<Response>;
105
133
  start: (request: Request) => Promise<Response>;
106
134
  cancel: () => Promise<Response>;
107
135
  };
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.8",
4
+ "version": "0.0.9",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
@@ -41,7 +41,7 @@
41
41
  },
42
42
  "license": "Apache-2.0",
43
43
  "dependencies": {
44
- "@huaweidevtools/aishell-dsh-credentials-store": "0.0.8"
44
+ "@huaweidevtools/aishell-dsh-credentials-store": "0.0.9"
45
45
  },
46
46
  "peerDependencies": {
47
47
  "@deepseek-ai/cordis": "^4.0.4",
@@ -1,32 +0,0 @@
1
- /**
2
- * The waiting spinner's keyframes.
3
- *
4
- * ## Why not inline styles
5
- *
6
- * A rotation needs `@keyframes`, which no inline style can express. The two
7
- * options are a CSS module (this package's client build does not run one) or a
8
- * tag installed at runtime — and this repo already has the second pattern for
9
- * exactly this: `installChipStyles` in `./huawei-mark.ts`, whose module note
10
- * records why an `id`-guarded module-level install is wrong (the client loader
11
- * sweeps `style[data-plugin]` on teardown, so an outliving tag makes a reload
12
- * keep the *old* rule for the life of the tab).
13
- *
14
- * So: one `ctx.effect` per sheet, a disposer that removes the tag, and the
15
- * same `data-plugin` / `data-plugin-css` markers.
16
- *
17
- * @module @huaweidevtools/aishell-dsh-client-credentials/client/spinner
18
- */
19
- import type { Context as ClientContext } from '@deepseek-ai/cordis';
20
- /** Class the waiting spinner carries. */
21
- export declare const SPINNER_CLASS = "aishell-spinner";
22
- /**
23
- * Install the spinner keyframes for the lifetime of the plugin fiber.
24
- *
25
- * Respects `prefers-reduced-motion`: a continuous rotation is exactly the kind
26
- * of motion that setting exists to suppress, and the countdown beside it still
27
- * conveys that work is in progress.
28
- *
29
- * @param ctx - the client context, for `ctx.effect`.
30
- */
31
- export declare function installSpinnerStyles(ctx: ClientContext): void;
32
- //# sourceMappingURL=spinner.d.ts.map
@@ -1,61 +0,0 @@
1
- /**
2
- * Which page the credential card opens on.
3
- *
4
- * ## Why this is its own module
5
- *
6
- * The decision is three booleans wide and was previously spelled inline in the
7
- * component, where it could only be observed by rendering — which this package
8
- * has no test dependency for, so it was not observed at all. The rule that
9
- * matters is easy to state and easy to get subtly wrong: a card opened by
10
- * somebody who already has a credential must not ask them how they would like
11
- * to obtain one.
12
- *
13
- * Kept as a pure function over values rather than a hook or a method, so the
14
- * whole table can be driven from a spec.
15
- *
16
- * ## The two facts it turns on
17
- *
18
- * - **Is a credential already stored?** Someone who has one is asking a
19
- * different question — "which account am I on, and how do I change it" —
20
- * than someone who has none. The card opens on the form for them, which is
21
- * where the account name and the clear button live.
22
- * - **Did the reachability probe find a browser route?** With no browser
23
- * route there is nothing to choose between, so the choice page does not
24
- * exist on that deployment and the form is the only page there is.
25
- *
26
- * @module @huaweidevtools/aishell-dsh-client-credentials/client/start-page
27
- */
28
- /** A page the credential card can be showing. */
29
- export type CredentialPage = 'choose' | 'manual' | 'waiting';
30
- /**
31
- * The page a card opens on.
32
- *
33
- * `undefined` means the probe has not answered yet, and is the honest value for
34
- * that moment: rendering either page then is what makes the fields appear and
35
- * get replaced a moment later.
36
- *
37
- * @param options - the two facts the decision turns on.
38
- * @param options.browserAvailable - whether a browser login is possible here;
39
- * `undefined` while the probe is still running.
40
- * @param options.alreadyConfigured - whether a credential is already stored.
41
- * @returns the page to show, or `undefined` while the answer is unknown.
42
- */
43
- export declare function startPage(options: {
44
- readonly browserAvailable: boolean | undefined;
45
- readonly alreadyConfigured: boolean;
46
- }): CredentialPage | undefined;
47
- /**
48
- * The page after a credential is cleared.
49
- *
50
- * Clearing puts the person back where someone with no credential stands, so the
51
- * question is once again "how would you like to authenticate" — which is the
52
- * choice page. It is also the only route to the browser login from the form, so
53
- * a person who came here to switch methods lands where that is offered.
54
- *
55
- * @param options - the same facts {@link startPage} takes.
56
- * @returns the page to show; never `undefined`, since this is not a first render.
57
- */
58
- export declare function afterClear(options: {
59
- readonly browserAvailable: boolean | undefined;
60
- }): CredentialPage;
61
- //# sourceMappingURL=start-page.d.ts.map