@huaweidevtools/aishell-dsh-client-credentials 0.0.7 → 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.
@@ -0,0 +1,101 @@
1
+ /**
2
+ * One browser login at a time, and what the browser half is told about it.
3
+ *
4
+ * ## The shape of a login
5
+ *
6
+ * probe() borrow a port, let the page fetch it, give it back
7
+ * | -> whether a browser here can reach this host at all
8
+ * v
9
+ * begin(provider) bind a port, fetch the plan, start serving
10
+ * | -> where to send the browser
11
+ * v
12
+ * (the person signs in at the cloud, in their browser, for up to 10 minutes)
13
+ * v
14
+ * the cloud posts the credential to the loopback listener
15
+ * v
16
+ * verify against IAM -> store -> record the outcome for the browser half
17
+ *
18
+ * Probe and login are separate operations on purpose — see `./login.ts` for
19
+ * why. The probe answers a question about the access route and holds a port
20
+ * for seconds; the login binds its own and holds it for as long as the person
21
+ * takes.
22
+ *
23
+ * The outcome does not come back as a return value, because there is nothing
24
+ * waiting on it: the person may take minutes, and an HTTP request held open
25
+ * that long is a request a proxy will cut. So the outcome is *recorded* — in
26
+ * the entry's settings document, which the browser half already subscribes to
27
+ * — and the browser half reads it when it changes. That is the same channel
28
+ * the credential form request already travels on, and the same reasoning.
29
+ *
30
+ * ## Why one at a time
31
+ *
32
+ * The shipped provider's callback carries no correlation string (`correlation:
33
+ * "none"`), so two concurrent logins on two ports could not be told apart by
34
+ * anything but the port itself. The service's own contract states the
35
+ * constraint in the same terms: one login occupies one port. Refusing the
36
+ * second is honest; queueing it would be a promise the flow cannot keep.
37
+ *
38
+ * ## Why a cancel is not a timeout
39
+ *
40
+ * A person who dismisses the form gets the listener closed immediately and no
41
+ * outcome recorded beyond the dismissal. A person who simply walks away leaves
42
+ * the listener bound until either the credential arrives or `expires_in`
43
+ * passes, at which point the cloud will not post and the port is released. The
44
+ * two are distinguished because only the first is a decision.
45
+ *
46
+ * @module @huaweidevtools/aishell-dsh-client-credentials/out-of-band/flow
47
+ */
48
+ import { type ContractDeps, type MappedCredential, type ProviderInfo } from './contract.ts';
49
+ import { type LoginStartResult } from './routes.ts';
50
+ import type { LoginOutcome } from '../login-status.ts';
51
+ /** Collaborators the flow runs against; injected so it is testable. */
52
+ export interface LoginFlowDeps {
53
+ /**
54
+ * Verify one credential against IAM, returning the account it belongs to.
55
+ *
56
+ * The flow calls this before it stores anything, and treats a rejection as
57
+ * the end of the login. See `./login.ts` for why it is not optional.
58
+ *
59
+ * The name it returns is what the outcome reports: the store's own account
60
+ * hint is written by the reconcile loop on its next tick, so reading it here
61
+ * would report whatever was there *before* this login.
62
+ */
63
+ readonly verify: (credential: MappedCredential) => Promise<string>;
64
+ /** Write a verified credential to the store. */
65
+ readonly store: (credential: MappedCredential) => Promise<void>;
66
+ /** Record the non-secret status the browser half reads. */
67
+ readonly recordError: (error: string) => void;
68
+ /** Record a completed login for the browser half, or clear it. */
69
+ readonly recordOutcome: (outcome: LoginOutcome | undefined) => void;
70
+ /** Transport overrides for the contract calls. */
71
+ readonly contract?: ContractDeps | undefined;
72
+ }
73
+ /** The browser-login flow. */
74
+ export interface LoginFlow {
75
+ /** Look up a provider; `undefined` when the service does not offer it. */
76
+ readonly findProvider: (providerId: string) => Promise<ProviderInfo | undefined>;
77
+ /**
78
+ * Borrow a loopback port and hand back a URL the page can fetch.
79
+ *
80
+ * Reaching it is the whole test, and the page is the one that learns the
81
+ * answer — see `./listener.ts`. The port is released as soon as it is
82
+ * reached, or after a short window if the page never gets there, so a card
83
+ * left open holds nothing.
84
+ */
85
+ readonly probe: () => Promise<{
86
+ probeUrl: string;
87
+ }>;
88
+ /** Begin a login. Rejects when one is already running. */
89
+ readonly begin: (provider: ProviderInfo) => Promise<LoginStartResult>;
90
+ /** Abandon the login in progress, if any. Safe to call with none. */
91
+ readonly cancel: () => void;
92
+ /** Whether a login is running. */
93
+ readonly inProgress: () => boolean;
94
+ }
95
+ /**
96
+ * Build the flow.
97
+ *
98
+ * @param deps - the collaborators above.
99
+ */
100
+ export declare function createLoginFlow(deps: LoginFlowDeps): LoginFlow;
101
+ //# sourceMappingURL=flow.d.ts.map
@@ -0,0 +1,233 @@
1
+ /**
2
+ * The loopback listener: the callback door, and the probe that proves it opens.
3
+ *
4
+ * ## What it is for
5
+ *
6
+ * In the out-of-band flow the cloud itself posts the credential, from the
7
+ * browser, to `127.0.0.1:<port>` — the host is never in that path. So the host
8
+ * must be listening on that port, on the machine the browser runs on, before
9
+ * the browser goes anywhere. This module owns that listener end to end.
10
+ *
11
+ * ## Why binding and serving are separate steps
12
+ *
13
+ * The port has to be known before the login service can be asked to project a
14
+ * redirect URI — one provider takes only the port out of it, and rejects a URI
15
+ * with none. But the plan that says which path and origins to honour only
16
+ * arrives from that same call. So the socket binds first and starts honouring
17
+ * a plan second.
18
+ *
19
+ * Nothing can reach the listener in between: the URL containing the port has
20
+ * been disclosed to nobody yet. A request that arrives anyway is answered
21
+ * `503`, which is honest — the door exists and is not yet open for business.
22
+ *
23
+ * ## Why the probe lives here
24
+ *
25
+ * The listener already has to exist for the callback. The probe reuses it
26
+ * rather than adding a second port, and — more to the point — it exercises
27
+ * *the same machinery* the callback will: a cross-origin request from a page
28
+ * to a loopback address, which means the same preflight, the same PNA
29
+ * handling, and the same response headers. A probe on a throwaway port would
30
+ * prove nothing about whether the real one works.
31
+ *
32
+ * The alternative was inferring reachability — from the socket address of the
33
+ * `/api` request, or from `location.hostname` in the page. Both are wrong in
34
+ * both directions. An SSH-forwarded session makes a distant browser look like
35
+ * loopback to the host, and makes a distant host look like `localhost` to the
36
+ * page; a LAN-addressed browser on the same machine looks remote to both.
37
+ * Only an actual request answers the actual question, so this asks one.
38
+ *
39
+ * ## What makes it hard (every item here is a silent failure)
40
+ *
41
+ * - **Listen on the plan's path, not a guess.** The callback goes to the
42
+ * path the plan names, which for one provider is `/` — a listener mounted
43
+ * anywhere else never receives it.
44
+ * - **Echo one origin, never the list, and never `*`.** An
45
+ * `Access-Control-Allow-Origin` header takes a single value. Writing `*`
46
+ * would let any page on the internet post a forged credential here.
47
+ * - **Send `Vary: Origin`.** Without it a cache can serve one origin's
48
+ * answer to another.
49
+ * - **Answer the Private Network Access preflight, when the plan says so.**
50
+ * A public page reaching loopback triggers a preflight carrying
51
+ * `Access-Control-Request-Private-Network`, and a response lacking the
52
+ * matching allow header makes the browser drop the real request. This
53
+ * never reproduces in local development — only in a real browser, where it
54
+ * looks like a login page that spins forever. The plan carries
55
+ * `requires_private_network_access`; the listener also requires the
56
+ * browser to have actually asked, so it never grants more than was
57
+ * requested.
58
+ * - **Cap the body.** The port is in a URL, so it is not a secret: any local
59
+ * process can post to it. A bound keeps that from becoming memory growth.
60
+ * - **Close after one payload.** It narrows the replay window, and a second
61
+ * post must not overwrite a credential that already arrived.
62
+ *
63
+ * ## The one thing this does not fix
64
+ *
65
+ * A local process can post here with any `Origin` it likes — CORS is a browser
66
+ * policy and does not constrain a process. The service's own documentation
67
+ * records this as unfixable at the receiving end. The defense is that the
68
+ * credential is verified against the cloud before it is stored (see
69
+ * `./login.ts`), which is why nothing here is treated as proof of anything.
70
+ * This listener decides *whether a payload arrived*, never whether it is
71
+ * trustworthy — and the probe is a diagnostic, an authorization check it is
72
+ * not.
73
+ *
74
+ * @module @huaweidevtools/aishell-dsh-client-credentials/out-of-band/listener
75
+ */
76
+ import type { CallbackPlan } from './contract.ts';
77
+ /** Largest callback body accepted. A credential is a few fields; 64 KiB is generous. */
78
+ export declare const MAX_CALLBACK_BYTES: number;
79
+ /**
80
+ * A bound socket that has not been told what to honour yet.
81
+ *
82
+ * Exists only between the bind and the plan arriving; see the module note.
83
+ */
84
+ export interface BoundListener {
85
+ /** Host address bound, always loopback. */
86
+ readonly host: string;
87
+ /** Port the OS assigned — never assume a value. */
88
+ readonly port: number;
89
+ /** `host:port`, for the `redirect_uri` and for comparison against the plan. */
90
+ readonly address: string;
91
+ /**
92
+ * Begin honouring a callback plan and a probe.
93
+ *
94
+ * @param plan - the provider's callback requirements.
95
+ * @param probe - how to answer a reachability probe, or `undefined` for none.
96
+ * @returns the serving listener.
97
+ */
98
+ readonly serve: (plan: CallbackPlan, probe?: ProbeConfig) => CallbackListener;
99
+ /** Stop listening without ever having served. */
100
+ readonly close: () => void;
101
+ }
102
+ /**
103
+ * Borrow a loopback port, answer one probe, and give it back.
104
+ *
105
+ * ## What this is for
106
+ *
107
+ * The cloud posts a credential to `127.0.0.1` **as the browser's machine
108
+ * resolves it**, so a browser login works only when that browser can reach a
109
+ * listener on this host. Neither side can tell by looking — an SSH-forwarded
110
+ * session makes a distant browser look local to the host and a distant host
111
+ * look local to the page — so the page fetches a URL and the fetch is the
112
+ * answer. A fetch that resolves means the page reached a socket here.
113
+ *
114
+ * ## How it ends
115
+ *
116
+ * Two ways, whichever comes first:
117
+ *
118
+ * - **Someone reaches it.** The response is written, and the socket closes
119
+ * immediately after — the question has been answered, so the port has no
120
+ * further use.
121
+ * - **{@link PROBE_WINDOW_MS} passes.** Nobody came, which is itself an
122
+ * answer (this browser cannot reach loopback), and the socket closes.
123
+ *
124
+ * Either way the port is held for seconds at most. A probe borrowed to ask one
125
+ * question must not outlive the asking — a card left open would otherwise keep
126
+ * a socket for the life of the page, which is what the earlier design did.
127
+ *
128
+ * ## Why the nonce
129
+ *
130
+ * The probe answers whatever origin asks, because the page's own origin is by
131
+ * definition not one of the cloud's. That is only safe with a secret: without
132
+ * one, any page that swept local ports would get an answer, making this a
133
+ * fingerprinting beacon for the plugin's presence. A caller without the nonce
134
+ * is answered exactly as an empty port would be.
135
+ *
136
+ * ## What the caller gets, and what it does not
137
+ *
138
+ * A URL and nothing else. The caller cannot observe the port closing — it
139
+ * closes on its own, either on being reached or when the window runs out — and
140
+ * a promise for that would be a handle no caller has a use for. Awaiting it
141
+ * would also mean a route waiting up to the whole window before answering,
142
+ * which is precisely what the page cannot afford.
143
+ *
144
+ * @param path - the path the probe is served on.
145
+ * @returns the URL to hand the page.
146
+ */
147
+ export declare function probeLoopback(path: string): Promise<{
148
+ readonly probeUrl: string;
149
+ }>;
150
+ /**
151
+ * Detach a timer from the event loop, when the runtime has that notion.
152
+ *
153
+ * Node's timer objects carry `unref`; a browser's are numbers. This package's
154
+ * tsconfig compiles against the DOM signature (the browser half is most of
155
+ * it), so the method is reached through a narrow cast rather than declared.
156
+ *
157
+ * Exported because the login's deadline needs the same treatment, and two
158
+ * copies of a three-line cast is how they drift.
159
+ *
160
+ * @param timer - the timer handle, of whichever shape this runtime uses.
161
+ */
162
+ export declare function unrefIfPossible(timer: ReturnType<typeof setTimeout> | undefined): void;
163
+ /**
164
+ * How long a probe port is held.
165
+ *
166
+ * Generous for a request that takes under a millisecond when it works, because
167
+ * the cost of the wait is a bound port and the cost of being too quick is
168
+ * calling a working route unsupported. A page that is slow to get going —
169
+ * a large bundle still parsing — still gets its answer.
170
+ */
171
+ export declare const PROBE_WINDOW_MS = 30000;
172
+ /** How the probe asks for a pass. */
173
+ export interface ProbeConfig {
174
+ /**
175
+ * Path the probe is answered on.
176
+ *
177
+ * Distinct from the callback path on purpose: the probe carries no
178
+ * credential, and a probe landing on the callback path would either be
179
+ * treated as one or block the real one.
180
+ */
181
+ readonly path: string;
182
+ /**
183
+ * Secret the probe must present.
184
+ *
185
+ * The probe is answered from whatever origin asks, because the page's own
186
+ * origin is by definition not one of the cloud's callback origins. Echoing
187
+ * an arbitrary origin is only safe because of this value: without it the
188
+ * listener would answer any page that guessed the port, turning it into a
189
+ * local-service fingerprinting beacon. With it, only a caller already
190
+ * holding the nonce — which only the host and its own page ever see — gets
191
+ * an answer.
192
+ */
193
+ readonly nonce: string;
194
+ /**
195
+ * Called when the probe has been answered, so the socket can be given back.
196
+ *
197
+ * Fired after the response is written, which is what makes the answer true:
198
+ * the page's fetch resolved, so it reached a socket here.
199
+ */
200
+ readonly onAnswered?: () => void;
201
+ }
202
+ /** A listener honouring a plan, and the one credential it will accept. */
203
+ export interface CallbackListener {
204
+ /** The address it bound to. */
205
+ readonly address: string;
206
+ /**
207
+ * Resolves with the decoded payload of the first accepted post.
208
+ *
209
+ * Rejects if the listener is closed or errors before a payload arrives.
210
+ * Settles at most once.
211
+ */
212
+ readonly accepted: Promise<Record<string, unknown>>;
213
+ /**
214
+ * Stop listening and drop any pending wait.
215
+ *
216
+ * Idempotent, and safe from a cleanup path that may run after the listener
217
+ * already closed itself on receipt.
218
+ */
219
+ readonly close: () => void;
220
+ }
221
+ /**
222
+ * Bind a loopback port, without yet honouring any plan.
223
+ *
224
+ * Binds before anything else happens, deliberately: the port appears in the
225
+ * redirect URI and is therefore not a secret, so a local process could take it
226
+ * first. Binding early and handing the actual port back is what makes the
227
+ * ordering correct by construction rather than by care.
228
+ *
229
+ * @returns the bound socket.
230
+ * @throws when the port cannot be bound.
231
+ */
232
+ export declare function bindLoopback(): Promise<BoundListener>;
233
+ //# sourceMappingURL=listener.d.ts.map
@@ -0,0 +1,123 @@
1
+ /**
2
+ * The browser-login flow, as two separate operations.
3
+ *
4
+ * ## Why two, and not one
5
+ *
6
+ * The card has to answer "can the browser reach a listener here?" before
7
+ * offering the button, and answering it requires binding a loopback socket —
8
+ * the question is whether the browser can reach a listener here, and nothing
9
+ * weaker answers it. That lives in `./listener.ts` as `probeLoopback`.
10
+ *
11
+ * A login is a different thing: fetch a URL for a specific port, send the
12
+ * person there, wait for the cloud to post a credential back. That is
13
+ * {@link startBrowserLogin}, and it binds **its own** port.
14
+ *
15
+ * These were one function, and it was wrong in two ways that only show up when
16
+ * a person takes their time:
17
+ *
18
+ * - **The port was held from the moment the card opened.** The probe binds a
19
+ * socket to answer its question and now releases it immediately; keeping it
20
+ * until someone clicked meant anyone who read the card and walked away held
21
+ * a port for as long as the page lived.
22
+ * - **The login window started before the person did.** The `login_url` names
23
+ * the port it was projected for and the service states how long it stays
24
+ * valid. Both were fixed at probe time, so a card left open for a while
25
+ * offered a URL that had already expired — and a countdown ran down on a
26
+ * sign-in nobody had begun.
27
+ *
28
+ * So each operation binds what it needs and releases it when its own job ends.
29
+ * The probe's port is closed as soon as the browser has answered; the login's
30
+ * port lives exactly as long as the login does, and the URL is fetched at the
31
+ * moment it is about to be opened.
32
+ *
33
+ * ## Why verification is not optional
34
+ *
35
+ * `credential` resolves with a credential already proven against the cloud, or
36
+ * it rejects. A caller cannot get an unverified credential out of it, because
37
+ * the one failure mode that matters — a forged credential reaching the store —
38
+ * is the one this exists to prevent, and a boolean flag is something a caller
39
+ * can forget to check.
40
+ *
41
+ * ## What verification does not catch
42
+ *
43
+ * It proves the credential is *valid*, not that it belongs to the account the
44
+ * person meant to sign in as. A local attacker posting their own real
45
+ * credential passes it. That is the residual risk the service's own docs
46
+ * record as unfixable at the receiving end, and the reason the account is
47
+ * reported back to the person rather than silently stored.
48
+ *
49
+ * @module @huaweidevtools/aishell-dsh-client-credentials/out-of-band/login
50
+ */
51
+ import { type ContractDeps, type MappedCredential, type ProviderInfo } from './contract.ts';
52
+ /**
53
+ * A credential that has been proven against the cloud, and whose account is
54
+ * therefore known.
55
+ *
56
+ * The two travel together because the same call establishes both: verification
57
+ * proves the credential and names the account it belongs to. Separating them
58
+ * would leave the caller to look the name up again, reading the store before
59
+ * the reconcile loop has caught up with the write.
60
+ */
61
+ export interface VerifiedCredential {
62
+ readonly credential: MappedCredential;
63
+ /** The account the credential belongs to, as IAM reported it. */
64
+ readonly accountName: string;
65
+ }
66
+ /** A login in flight. */
67
+ export interface BrowserLogin {
68
+ /** The address the callback listener bound to, `host:port`. */
69
+ readonly address: string;
70
+ /** Where to send the browser. */
71
+ readonly loginUrl: string;
72
+ /** The credential, once the person has finished and the cloud accepted it. */
73
+ readonly credential: Promise<VerifiedCredential>;
74
+ /** How long the login stays valid, in seconds — the service's own figure. */
75
+ readonly expiresInSeconds: number;
76
+ /** Abandon the login: close the listener and reject anything pending. */
77
+ readonly cancel: () => void;
78
+ }
79
+ /** Transport and provider facts both operations need. */
80
+ export interface LoginContext {
81
+ /** The provider, as the service describes it — including its `credential_schema`. */
82
+ readonly provider: ProviderInfo;
83
+ /** Transport overrides for the contract calls. */
84
+ readonly contract?: ContractDeps | undefined;
85
+ }
86
+ /** Options for {@link startBrowserLogin}. */
87
+ export interface StartLoginOptions extends LoginContext {
88
+ /**
89
+ * Proves a credential works, and names the account it belongs to.
90
+ *
91
+ * Called before anything is returned, and a rejection ends the login — a
92
+ * throw is the only way to say no, so there is no boolean a caller could
93
+ * forget to check. The resolved name is what a successful login reports.
94
+ */
95
+ readonly verify: (credential: MappedCredential) => Promise<unknown>;
96
+ }
97
+ /**
98
+ * Find the provider to sign in with, and the schema its credentials use.
99
+ *
100
+ * Needs no socket, so the card can ask "is this even on offer, and what am I
101
+ * signing in to?" before anything binds.
102
+ *
103
+ * @param providerId - the provider to look for.
104
+ * @param deps - transport overrides.
105
+ * @returns the provider, or `undefined` when the service does not offer it.
106
+ * @throws {AuthContractError} when the service is unreachable or answers unusably.
107
+ */
108
+ export declare function findProvider(providerId: string, deps?: ContractDeps): Promise<ProviderInfo | undefined>;
109
+ /**
110
+ * Begin a browser login.
111
+ *
112
+ * Binds its own listener and fetches a login URL projected for it, so both are
113
+ * as fresh as the moment the person clicked — see the module note for why that
114
+ * matters. Everything except `credential` is settled by the time this returns;
115
+ * a failure to bind, reach the service, or match the plan throws instead.
116
+ *
117
+ * @param options - the provider and the verifier.
118
+ * @returns the running login.
119
+ * @throws {AuthContractError} when the port cannot be bound, the service
120
+ * cannot be reached, or the plan names an address this machine is not on.
121
+ */
122
+ export declare function startBrowserLogin(options: StartLoginOptions): Promise<BrowserLogin>;
123
+ //# sourceMappingURL=login.d.ts.map
@@ -0,0 +1,136 @@
1
+ /**
2
+ * The host-side routes the browser half drives a browser login through.
3
+ *
4
+ * ## Why the flow lives on the host
5
+ *
6
+ * None of it can live in the browser half: the credential arrives at a
7
+ * loopback socket only the host can bind, the plan comes from a service the
8
+ * host reaches, and verification needs the signer. So the host owns the flow
9
+ * and the browser half asks for each step.
10
+ *
11
+ * ## The three routes, and why there is no fourth
12
+ *
13
+ * POST .../login/probe -> borrow a port, answer with where to fetch it
14
+ * POST .../login/start -> bind, fetch the plan, start serving; answer with
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).
22
+ *
23
+ * There is deliberately no `finish`. The outcome arrives on its own schedule —
24
+ * whenever the person finishes signing in, up to ten minutes later — so
25
+ * polling for it would mean a long-held HTTP request, which proxies time out
26
+ * and which this codebase already has a better channel for: the entry's
27
+ * settings document, which the browser half subscribes to. See
28
+ * `./login-status.ts`. The host stores the credential and records the outcome
29
+ * there; nothing needs to ask.
30
+ *
31
+ * ## What `start` does and does not guarantee
32
+ *
33
+ * It returns once a listener is bound and a plan is honoured. It says nothing
34
+ * about whether the browser can *reach* that listener — only a request from
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.
38
+ *
39
+ * @module @huaweidevtools/aishell-dsh-client-credentials/out-of-band/routes
40
+ */
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";
44
+ /** Path the browser half posts to, to begin a login. */
45
+ export declare const LOGIN_START_PATH = "/api/aishell/credentials/login/start";
46
+ /** Path the browser half posts to, to abandon a login. */
47
+ export declare const LOGIN_CANCEL_PATH = "/api/aishell/credentials/login/cancel";
48
+ /**
49
+ * Path the probe is served on.
50
+ *
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.
55
+ */
56
+ export declare const LOGIN_PROBE_PATH = "/__aishell_probe";
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
+ */
64
+ export interface LoginStartResult {
65
+ readonly ok: true;
66
+ /** URL to open in the browser, projected for the port this login bound. */
67
+ readonly loginUrl: string;
68
+ /** Provider being signed in with, for the copy the form shows. */
69
+ readonly providerName: string;
70
+ /**
71
+ * Seconds until the login stops being completable.
72
+ *
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
+ */
76
+ readonly expiresInSeconds: number;
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
+ }
95
+ /** Host-side operations the routes delegate to, injected so they are testable. */
96
+ export interface LoginRouteDeps {
97
+ /**
98
+ * Look up a provider by id.
99
+ *
100
+ * @param providerId - the provider the browser half asked for.
101
+ * @returns the provider, or `undefined` when the service does not offer it.
102
+ */
103
+ readonly findProvider: (providerId: string) => Promise<ProviderInfo | undefined>;
104
+ /**
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.
117
+ *
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
120
+ * settings document rather than as this call's result.
121
+ *
122
+ * @param provider - the provider to sign in with.
123
+ */
124
+ readonly begin: (provider: ProviderInfo) => Promise<LoginStartResult>;
125
+ /** Abandon any login in progress and release its port. */
126
+ readonly cancel: () => void;
127
+ /** Whether a login is already in progress. */
128
+ readonly inProgress: () => boolean;
129
+ }
130
+ /** The login routes, bound to their collaborators. */
131
+ export declare function createLoginRoutes(deps: LoginRouteDeps): {
132
+ probe: () => Promise<Response>;
133
+ start: (request: Request) => Promise<Response>;
134
+ cancel: () => Promise<Response>;
135
+ };
136
+ //# sourceMappingURL=routes.d.ts.map
@@ -0,0 +1,78 @@
1
+ /**
2
+ * Credential prefill from the environment.
3
+ *
4
+ * ## What this is for
5
+ *
6
+ * A machine that already carries `HW_ACCESS_KEY`, `HW_SECRET_KEY` and
7
+ * `HW_SECURITY_TOKEN` in its environment has the credentials; the person just
8
+ * has to move them into the store. Typing three values that are already on the
9
+ * machine is work nobody should do, so the form opens with them filled in.
10
+ *
11
+ * ## Why the values come from the host
12
+ *
13
+ * The browser half cannot read `process.env` — it is browser code, and the
14
+ * environment it would see is not the host's. So the host reads the variables
15
+ * and serves them over a route the form calls before it renders its fields.
16
+ *
17
+ * ## Why that is acceptable here
18
+ *
19
+ * The values travel from the host to the page it is serving, over the same
20
+ * authenticated channel and the same origin as the credential route the form
21
+ * already posts to. Nothing new is exposed: a page that could read this route
22
+ * could also submit that form.
23
+ *
24
+ * They are **not** written to the settings document, the session, or a log —
25
+ * the route is the whole journey, and it is called once per form open.
26
+ *
27
+ * ## Why it returns nothing rather than a partial set
28
+ *
29
+ * A form filled with an access key and no secret key looks broken. Either the
30
+ * environment carries a usable pair, or the form starts empty and the person
31
+ * enters what they have. The token is separate: it is optional, and a lone
32
+ * token with no pair is dropped for the same reason.
33
+ *
34
+ * ## Why the form says so
35
+ *
36
+ * The person did not type these values. Saying where they came from is what
37
+ * lets them decide whether to trust them — a credential silently appearing in
38
+ * a field is worse than an empty one.
39
+ *
40
+ * @module @huaweidevtools/aishell-dsh-client-credentials/prefill
41
+ */
42
+ /** Route the form reads prefills from. */
43
+ export declare const PREFILL_PATH = "/api/aishell/credentials/prefill";
44
+ /**
45
+ * A credential set read out of the environment.
46
+ *
47
+ * All fields optional, because "nothing to prefill" is the ordinary answer —
48
+ * most machines have no credential in their environment. The form treats an
49
+ * empty object as empty fields, which is exactly its behaviour without this
50
+ * feature at all.
51
+ */
52
+ export interface CredentialPrefill {
53
+ readonly accessKeyId?: string;
54
+ readonly secretAccessKey?: string;
55
+ /** Present only when the environment carries one. */
56
+ readonly securityToken?: string;
57
+ }
58
+ /**
59
+ * Read an environment for a usable credential set.
60
+ *
61
+ * Pure, and the environment is a parameter: this package compiles without Node
62
+ * type definitions (the browser half is most of it), so `process` is not in
63
+ * scope and the caller supplies what to read.
64
+ *
65
+ * ## What these values do, and do not, do
66
+ *
67
+ * They fill the form's fields. The form still opens, every field is still
68
+ * editable, and submitting or cancelling still works the way it always did —
69
+ * the person saves the step of copying three values out of their shell, and
70
+ * nothing else. In particular nothing is stored on their behalf: a prefill is a
71
+ * starting point, not a credential.
72
+ *
73
+ * @param env - the environment to read.
74
+ * @returns the pair (and token, when present), or `undefined` when either half
75
+ * of the pair is missing.
76
+ */
77
+ export declare function readEnvPrefill(env: Record<string, string | undefined>): CredentialPrefill | undefined;
78
+ //# sourceMappingURL=prefill.d.ts.map