@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.
- package/LICENSE +1 -1
- package/lib/client.js +915 -259
- package/lib/index.js +1577 -109
- package/lib/types/auth-tool.d.ts +108 -0
- package/lib/types/client/AishellAccountHint.d.ts +1 -1
- package/lib/types/client/CredentialFormInteraction.d.ts +2 -19
- package/lib/types/client/CredentialRequestForm.d.ts +64 -41
- package/lib/types/client/card-state.d.ts +58 -0
- package/lib/types/client/credential-form-visibility.d.ts +25 -58
- package/lib/types/client/index.d.ts +1 -1
- package/lib/types/client/locales.d.ts +42 -12
- package/lib/types/client/login-flow.d.ts +134 -0
- package/lib/types/client/permission-mode.d.ts +3 -3
- package/lib/types/form-request.d.ts +118 -0
- package/lib/types/index.d.ts +28 -50
- package/lib/types/login-status.d.ts +62 -0
- package/lib/types/out-of-band/contract.d.ts +199 -0
- package/lib/types/out-of-band/flow.d.ts +101 -0
- package/lib/types/out-of-band/listener.d.ts +233 -0
- package/lib/types/out-of-band/login.d.ts +123 -0
- package/lib/types/out-of-band/routes.d.ts +136 -0
- package/lib/types/prefill.d.ts +78 -0
- package/lib/types/reconcile.d.ts +3 -11
- package/package.json +5 -3
|
@@ -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
|