@huaweidevtools/aishell-dsh-client-credentials 0.0.1-beta.5 → 0.0.1-beta.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/client.js +705 -128
- package/lib/index.js +977 -5
- package/lib/types/client/CredentialRequestForm.d.ts +26 -0
- package/lib/types/client/locales.d.ts +22 -2
- package/lib/types/client/login-flow.d.ts +98 -0
- package/lib/types/client/spinner.d.ts +32 -0
- package/lib/types/index.d.ts +15 -0
- 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 +82 -0
- package/lib/types/out-of-band/listener.d.ts +156 -0
- package/lib/types/out-of-band/login.d.ts +144 -0
- package/lib/types/out-of-band/routes.d.ts +108 -0
- package/lib/types/prefill.d.ts +78 -0
- package/package.json +2 -2
|
@@ -34,6 +34,8 @@ import { type ReactNode } from 'react';
|
|
|
34
34
|
import type { InjectFace, PropsRuntime, PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
|
|
35
35
|
import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
|
|
36
36
|
import { type CredentialStatus, type SaveVerdict } from './credential-status.ts';
|
|
37
|
+
import type { BrowserLoginHandle } from './login-flow.ts';
|
|
38
|
+
import type { CredentialPrefill } from '../prefill.ts';
|
|
37
39
|
import type { CredentialFormInteraction } from './CredentialFormInteraction.ts';
|
|
38
40
|
declare module '@deepseek-ai/dsh-client-ui-session/client' {
|
|
39
41
|
interface SessionPendingInteractionMap {
|
|
@@ -45,9 +47,33 @@ export interface CredentialRequestFormInjected {
|
|
|
45
47
|
hooks: {
|
|
46
48
|
/** Credential presence + account hint, rebound by the renderer as useCredentials. */
|
|
47
49
|
credentials: SnapshotStore<CredentialStatus>;
|
|
50
|
+
/** The last browser login's outcome, rebound as useLoginOutcome. */
|
|
51
|
+
loginOutcome: SnapshotStore<string>;
|
|
48
52
|
};
|
|
49
53
|
/** Store AK/SK/SecurityToken through the Host credential route. */
|
|
50
54
|
save: (accessKeyId: string, secretAccessKey: string, securityToken?: string) => Promise<SaveVerdict>;
|
|
55
|
+
/**
|
|
56
|
+
* Begin a browser login, if this deployment can complete one.
|
|
57
|
+
*
|
|
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.
|
|
62
|
+
*
|
|
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.
|
|
66
|
+
*
|
|
67
|
+
* @returns a started login, or `undefined` when the path is unavailable.
|
|
68
|
+
*/
|
|
69
|
+
startBrowserLogin: () => Promise<BrowserLoginHandle | undefined>; /**
|
|
70
|
+
* Values the host already has, to start the fields with.
|
|
71
|
+
*
|
|
72
|
+
* Fills the inputs; it does not submit, does not hide the form, and every
|
|
73
|
+
* field stays editable. The point is to save the person copying three values
|
|
74
|
+
* out of their shell — not to skip the form.
|
|
75
|
+
*/
|
|
76
|
+
readPrefill: () => Promise<CredentialPrefill>;
|
|
51
77
|
/**
|
|
52
78
|
* Clear the stored credentials.
|
|
53
79
|
*
|
|
@@ -20,8 +20,8 @@ export declare const zh: {
|
|
|
20
20
|
readonly 'section.credentials.hint.link': "API Explorer";
|
|
21
21
|
readonly 'section.credentials.hint.suffix': "获取临时凭据,避免使用永久凭据。";
|
|
22
22
|
readonly 'section.credentials.saving': "保存中…";
|
|
23
|
-
readonly 'form.title': "需要华为云凭据";
|
|
24
23
|
readonly 'form.title.manual': "配置华为云凭据";
|
|
24
|
+
readonly 'form.prefilledFromEnv': "检测到环境变量,已填入表单";
|
|
25
25
|
readonly 'form.submit': "提交";
|
|
26
26
|
readonly 'form.dismiss': "取消";
|
|
27
27
|
readonly 'form.failed': "保存凭据失败";
|
|
@@ -29,6 +29,16 @@ export declare const zh: {
|
|
|
29
29
|
readonly 'form.clearing': "清除中…";
|
|
30
30
|
readonly 'form.clear.failed': "清除凭据失败";
|
|
31
31
|
readonly 'error.unreachable': "无法连接宿主凭据服务:";
|
|
32
|
+
readonly 'form.intro': "需要进行华为云 IAM 认证";
|
|
33
|
+
readonly 'form.browser.action': "浏览器登录";
|
|
34
|
+
readonly 'form.browser.aksk': "我有AK/SK";
|
|
35
|
+
readonly 'form.browser.decline': "暂不认证";
|
|
36
|
+
readonly 'form.browser.waiting': "正在等待浏览器完成登录…";
|
|
37
|
+
readonly 'form.browser.countdown': "剩余 {time}";
|
|
38
|
+
readonly 'form.browser.reopen': "重新打开";
|
|
39
|
+
readonly 'form.back': "返回";
|
|
40
|
+
readonly 'form.browser.blocked': "浏览器拦截了新标签页,请允许弹出窗口后重试。";
|
|
41
|
+
readonly 'form.browser.failed': "浏览器登录未完成:";
|
|
32
42
|
readonly 'section.field.accessKey': "Access Key";
|
|
33
43
|
readonly 'section.field.accessKey.placeholder': "华为云 Access Key";
|
|
34
44
|
readonly 'section.field.accessKey.hint': "Access Key 与 Secret Key 须同时填写,只填其一时不会保存。";
|
|
@@ -54,8 +64,8 @@ export declare const en: {
|
|
|
54
64
|
readonly 'section.credentials.hint.link': "API Explorer";
|
|
55
65
|
readonly 'section.credentials.hint.suffix': "and avoid permanent ones.";
|
|
56
66
|
readonly 'section.credentials.saving': "Saving…";
|
|
57
|
-
readonly 'form.title': "Huawei Cloud credentials required";
|
|
58
67
|
readonly 'form.title.manual': "Configure Huawei Cloud credentials";
|
|
68
|
+
readonly 'form.prefilledFromEnv': "Detected environment variables — filled in from them";
|
|
59
69
|
readonly 'form.submit': "Submit";
|
|
60
70
|
readonly 'form.dismiss': "Cancel";
|
|
61
71
|
readonly 'form.failed': "Could not save credentials";
|
|
@@ -63,6 +73,16 @@ export declare const en: {
|
|
|
63
73
|
readonly 'form.clearing': "Clearing…";
|
|
64
74
|
readonly 'form.clear.failed': "Could not clear credentials";
|
|
65
75
|
readonly 'error.unreachable': "Could not reach the host credential service: ";
|
|
76
|
+
readonly 'form.intro': "Huawei Cloud IAM authentication is required";
|
|
77
|
+
readonly 'form.browser.action': "Sign in with a browser";
|
|
78
|
+
readonly 'form.browser.aksk': "I have one";
|
|
79
|
+
readonly 'form.browser.decline': "Not now";
|
|
80
|
+
readonly 'form.browser.waiting': "Waiting for the browser sign-in to finish…";
|
|
81
|
+
readonly 'form.browser.countdown': "{time} left";
|
|
82
|
+
readonly 'form.browser.reopen': "Reopen";
|
|
83
|
+
readonly 'form.back': "Back";
|
|
84
|
+
readonly 'form.browser.blocked': "The browser blocked the new tab. Allow pop-ups for this page, then try again.";
|
|
85
|
+
readonly 'form.browser.failed': "The browser sign-in did not complete: ";
|
|
66
86
|
readonly 'section.field.accessKey': "Access Key";
|
|
67
87
|
readonly 'section.field.accessKey.placeholder': "Huawei Access Key";
|
|
68
88
|
readonly 'section.field.accessKey.hint': "Access Key and Secret Key are stored as a pair; one without the other is not saved.";
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Browser-login support, as the form sees it.
|
|
3
|
+
*
|
|
4
|
+
* ## What the form needs to know
|
|
5
|
+
*
|
|
6
|
+
* Two things, and they arrive by different routes:
|
|
7
|
+
*
|
|
8
|
+
* - **Can this deployment do it at all?** Answered by the probe, on demand,
|
|
9
|
+
* because only the browser can answer it. See below.
|
|
10
|
+
* - **How did the last attempt end?** Read from the entry's settings
|
|
11
|
+
* document, which the host writes when the credential lands — the person
|
|
12
|
+
* may be at the cloud for minutes, so there is nothing to await.
|
|
13
|
+
*
|
|
14
|
+
* ## Why the capability is probed rather than assumed
|
|
15
|
+
*
|
|
16
|
+
* The cloud posts the credential to `127.0.0.1` *as the browser's machine
|
|
17
|
+
* resolves it*, so the flow only works when the browser and the host are the
|
|
18
|
+
* same machine. That is not knowable from either side: an SSH-forwarded
|
|
19
|
+
* session makes a distant browser look local to the host, and a distant host
|
|
20
|
+
* look local to the page. So the browser asks a question only it can ask —
|
|
21
|
+
* *can I reach the host's listener?* — by fetching it.
|
|
22
|
+
*
|
|
23
|
+
* This is also why the capability is never cached. Reachability depends on
|
|
24
|
+
* things that change under the user's feet (a VPN, a tunnel, a port taken
|
|
25
|
+
* between attempts), and a cached "no" would keep the entry hidden after
|
|
26
|
+
* someone fixed their setup.
|
|
27
|
+
*
|
|
28
|
+
* ## The cost of asking
|
|
29
|
+
*
|
|
30
|
+
* `start` binds a loopback port on the host and fetches the provider's
|
|
31
|
+
* callback plan. That work is not wasted when the answer is yes — it is the
|
|
32
|
+
* login, already begun, and clicking the entry only opens the URL it returned.
|
|
33
|
+
* When the answer is no, the port is released immediately.
|
|
34
|
+
*
|
|
35
|
+
* @module @huaweidevtools/aishell-dsh-client-credentials/client/login-flow
|
|
36
|
+
*/
|
|
37
|
+
/**
|
|
38
|
+
* A browser login the host has begun and the browser can reach.
|
|
39
|
+
*
|
|
40
|
+
* Holding this means a listener is bound and waiting, so it must be released —
|
|
41
|
+
* see {@link BrowserLoginHandle.cancel} — when the form closes without using
|
|
42
|
+
* it.
|
|
43
|
+
*/
|
|
44
|
+
export interface BrowserLoginHandle {
|
|
45
|
+
/** URL to open when the person chooses this path. */
|
|
46
|
+
readonly loginUrl: string;
|
|
47
|
+
/** Provider's display name, for the copy that names it. */
|
|
48
|
+
readonly providerName: string;
|
|
49
|
+
/**
|
|
50
|
+
* Seconds until the login stops being completable, as the service stated it.
|
|
51
|
+
*
|
|
52
|
+
* The waiting card counts down to this. The host enforces the same number on
|
|
53
|
+
* its listener, so what the person sees and what the port does agree.
|
|
54
|
+
*/
|
|
55
|
+
readonly expiresInSeconds: number;
|
|
56
|
+
/** Release the host's listener; the login will not complete. */
|
|
57
|
+
readonly cancel: () => void;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Reachability check, then login.
|
|
61
|
+
*
|
|
62
|
+
* Starts a login on the host and then proves this page can reach the listener
|
|
63
|
+
* it bound. The probe request goes from this browser to loopback, which is the
|
|
64
|
+
* same journey the cloud's callback will make.
|
|
65
|
+
*
|
|
66
|
+
* ## Why the probe is not a plain GET
|
|
67
|
+
*
|
|
68
|
+
* It carries a custom header, which makes it a non-simple request: the browser
|
|
69
|
+
* must send a CORS preflight first, and only proceeds if the answer is right.
|
|
70
|
+
* The cloud's callback is a JSON POST and therefore *always* preflights, so a
|
|
71
|
+
* plain GET would test a path the callback never takes — and could pass on a
|
|
72
|
+
* deployment where the real preflight fails (a missing Private Network Access
|
|
73
|
+
* allow header, say), which is the one wrong answer this check must not give.
|
|
74
|
+
*
|
|
75
|
+
* @returns a handle when the login is reachable, or `undefined` when it is
|
|
76
|
+
* not — the ordinary outcome on a deployment where the browser is elsewhere.
|
|
77
|
+
*/
|
|
78
|
+
export declare function startBrowserLogin(): Promise<BrowserLoginHandle | undefined>;
|
|
79
|
+
/**
|
|
80
|
+
* Open a login URL in a new tab.
|
|
81
|
+
*
|
|
82
|
+
* A separate tab rather than a redirect: the form has unsaved state and the
|
|
83
|
+
* person may come back to paste a key instead, and a login that navigated away
|
|
84
|
+
* from the conversation would lose it.
|
|
85
|
+
*
|
|
86
|
+
* ## Why `noopener` is set after opening, not passed in
|
|
87
|
+
*
|
|
88
|
+
* `window.open` returns `null` whenever `noopener` appears in its features
|
|
89
|
+
* string — by specification, not as a failure. Passing it there would make
|
|
90
|
+
* every successful open look blocked, so the tab is opened plainly and the
|
|
91
|
+
* opener reference is severed immediately afterwards, which is the same
|
|
92
|
+
* protection without losing the success signal.
|
|
93
|
+
*
|
|
94
|
+
* @param url - the URL the host returned.
|
|
95
|
+
* @returns whether the browser opened it; a popup blocker says no.
|
|
96
|
+
*/
|
|
97
|
+
export declare function openLoginWindow(url: string): boolean;
|
|
98
|
+
//# sourceMappingURL=login-flow.d.ts.map
|
|
@@ -0,0 +1,32 @@
|
|
|
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
|
package/lib/types/index.d.ts
CHANGED
|
@@ -40,6 +40,19 @@ export interface Config {
|
|
|
40
40
|
* channel.
|
|
41
41
|
*/
|
|
42
42
|
credentialFormRequest: Volatile<string>;
|
|
43
|
+
/**
|
|
44
|
+
* How the last browser login ended, or `''` when none has.
|
|
45
|
+
*
|
|
46
|
+
* Written by the host when the credential arrives and is stored; read by the
|
|
47
|
+
* browser half, which shows the outcome and stops waiting. An outcome is
|
|
48
|
+
* recorded rather than returned because the person may spend minutes at the
|
|
49
|
+
* cloud, and an HTTP request held open that long is one a proxy will cut —
|
|
50
|
+
* see `./out-of-band/flow.ts`.
|
|
51
|
+
*
|
|
52
|
+
* JSON, not several fields, so the browser half never observes a half-written
|
|
53
|
+
* outcome. Carries no credential: only a kind and a name or a message.
|
|
54
|
+
*/
|
|
55
|
+
loginOutcome: Volatile<string>;
|
|
43
56
|
}
|
|
44
57
|
/**
|
|
45
58
|
* Settings schema for this entry. Secrets are deliberately absent: they travel
|
|
@@ -51,11 +64,13 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
|
|
|
51
64
|
accessKeyIdHint: z<string, string, "volatile-defined">;
|
|
52
65
|
lastError: z<string, string, "volatile-defined">;
|
|
53
66
|
credentialFormRequest: z<string, string, "volatile-defined">;
|
|
67
|
+
loginOutcome: z<string, string, "volatile-defined">;
|
|
54
68
|
}>>, Schemastery.ObjectT<NoInfer<{
|
|
55
69
|
credentialsStored: z<boolean, boolean, "volatile-defined">;
|
|
56
70
|
accessKeyIdHint: z<string, string, "volatile-defined">;
|
|
57
71
|
lastError: z<string, string, "volatile-defined">;
|
|
58
72
|
credentialFormRequest: z<string, string, "volatile-defined">;
|
|
73
|
+
loginOutcome: z<string, string, "volatile-defined">;
|
|
59
74
|
}>>, "plain">;
|
|
60
75
|
declare module '@deepseek-ai/cordis' {
|
|
61
76
|
interface Events {
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The vocabulary the two halves share about a browser login in progress.
|
|
3
|
+
*
|
|
4
|
+
* ## Why it is its own module
|
|
5
|
+
*
|
|
6
|
+
* Both halves need these names and neither owns them: the host writes the
|
|
7
|
+
* outcome into the settings document, the browser half reads it and drives the
|
|
8
|
+
* form the login opens in. A module the two import is the only place the
|
|
9
|
+
* contract can live without one half depending on the other's internals —
|
|
10
|
+
* the same reasoning `../form-request.ts` follows for the credential form.
|
|
11
|
+
*
|
|
12
|
+
* ## What travels, and what does not
|
|
13
|
+
*
|
|
14
|
+
* A login's outcome is a kind and, at most, an account name or a message. No
|
|
15
|
+
* credential ever crosses this channel in either direction: the credential
|
|
16
|
+
* arrives at a loopback socket the host owns, is verified there, and is stored
|
|
17
|
+
* there. The browser half learns only that it worked, and as whom.
|
|
18
|
+
*
|
|
19
|
+
* @module @huaweidevtools/aishell-dsh-client-credentials/login-status
|
|
20
|
+
*/
|
|
21
|
+
/** Field of this entry's config carrying the last login's outcome. */
|
|
22
|
+
export declare const LOGIN_OUTCOME_FIELD = "loginOutcome";
|
|
23
|
+
/**
|
|
24
|
+
* Header the reachability probe sends, to force a CORS preflight.
|
|
25
|
+
*
|
|
26
|
+
* Any non-safelisted header would do it; this one names why. Declared here
|
|
27
|
+
* because both halves need the same string and neither owns it: the browser
|
|
28
|
+
* half sends it, the host's listener must allow it in its preflight answer,
|
|
29
|
+
* and a mismatch between the two is a probe that fails on a deployment that
|
|
30
|
+
* would actually work — the entry hidden for no reason.
|
|
31
|
+
*/
|
|
32
|
+
export declare const PROBE_HEADER = "x-aishell-probe";
|
|
33
|
+
/** How a browser login ended. */
|
|
34
|
+
export type LoginOutcome =
|
|
35
|
+
/** The credential verified against IAM and was stored. */
|
|
36
|
+
{
|
|
37
|
+
readonly kind: 'succeeded';
|
|
38
|
+
readonly accountName: string;
|
|
39
|
+
}
|
|
40
|
+
/** It did not, with copy the person can act on. */
|
|
41
|
+
| {
|
|
42
|
+
readonly kind: 'failed';
|
|
43
|
+
readonly error: string;
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* Serialize an outcome for the settings document.
|
|
47
|
+
*
|
|
48
|
+
* @param outcome - the outcome, or `undefined` to clear the field.
|
|
49
|
+
* @returns the encoded value, or `''` to clear it.
|
|
50
|
+
*/
|
|
51
|
+
export declare function encodeOutcome(outcome: LoginOutcome | undefined): string;
|
|
52
|
+
/**
|
|
53
|
+
* Read an outcome back out of the document.
|
|
54
|
+
*
|
|
55
|
+
* Anything unreadable reads as no outcome: a corrupt field should show
|
|
56
|
+
* nothing, not a spurious success.
|
|
57
|
+
*
|
|
58
|
+
* @param raw - the stored string, if any.
|
|
59
|
+
* @returns the outcome, or `undefined` when there is none usable.
|
|
60
|
+
*/
|
|
61
|
+
export declare function decodeOutcome(raw: string | undefined): LoginOutcome | undefined;
|
|
62
|
+
//# sourceMappingURL=login-status.d.ts.map
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The aishell-auth contract, as this plugin consumes it.
|
|
3
|
+
*
|
|
4
|
+
* ## What this module is
|
|
5
|
+
*
|
|
6
|
+
* A client for one stateless service that answers a single question: *where
|
|
7
|
+
* should the browser go to sign in, and how does the credential come back?*
|
|
8
|
+
* It stores nothing, holds no credential, and has no user system — the cloud
|
|
9
|
+
* posts the credential straight to the caller.
|
|
10
|
+
*
|
|
11
|
+
* ## Why the contract is read, not hardcoded
|
|
12
|
+
*
|
|
13
|
+
* Every quirk of the cloud's callback is in the response: the listen path, the
|
|
14
|
+
* accepted origins, whether a correlation string exists, what to do with the
|
|
15
|
+
* payload. The service's own README says the point is that the caller "does
|
|
16
|
+
* not need to hardcode anything provider-specific" — so this module hardcodes
|
|
17
|
+
* none of it either. That is what makes a second provider a config change here
|
|
18
|
+
* rather than a rewrite, and it is why the types below mirror the wire exactly
|
|
19
|
+
* instead of modelling what Huawei happens to do today.
|
|
20
|
+
*
|
|
21
|
+
* ## Why field mapping is schema-driven
|
|
22
|
+
*
|
|
23
|
+
* `credential_schema` names the payload fields per provider. Mapping by those
|
|
24
|
+
* names rather than by literal keys means a provider that calls its fields
|
|
25
|
+
* something else still lands in the right store slots, and a provider that
|
|
26
|
+
* renames one is a server-side change the caller follows for free.
|
|
27
|
+
*
|
|
28
|
+
* ## No exception, after all
|
|
29
|
+
*
|
|
30
|
+
* Private Network Access is in the contract as
|
|
31
|
+
* `requires_private_network_access`: a browser on a public origin reaching
|
|
32
|
+
* loopback sends a preflight carrying `Access-Control-Request-Private-Network`,
|
|
33
|
+
* and a response without the matching allow header makes it drop the real
|
|
34
|
+
* request — invisibly, in production only, with no error anywhere. The
|
|
35
|
+
* contract carries that fact now, so this module hardcodes nothing about it.
|
|
36
|
+
* See `./listener.ts` for how the flag and the browser's own request header
|
|
37
|
+
* are combined.
|
|
38
|
+
*
|
|
39
|
+
* @module @huaweidevtools/aishell-dsh-client-credentials/out-of-band/contract
|
|
40
|
+
*/
|
|
41
|
+
/**
|
|
42
|
+
* Base URL of the login-dispatch service.
|
|
43
|
+
*
|
|
44
|
+
* A constant rather than a setting: it identifies one deployment of a shared
|
|
45
|
+
* service, the same way a cloud endpoint would, and every caller of this
|
|
46
|
+
* plugin in an organisation points at the same one. A deployment that needs a
|
|
47
|
+
* different address is a code change here, which is the honest representation
|
|
48
|
+
* — this is not something an end user picks.
|
|
49
|
+
*/
|
|
50
|
+
export declare const AUTH_SERVICE_BASE = "https://public.aishell.openbuildlab.com";
|
|
51
|
+
/** How the credential reaches the caller. */
|
|
52
|
+
export type Delivery =
|
|
53
|
+
/** The cloud posts the credential directly to the caller's listener. */
|
|
54
|
+
'out_of_band'
|
|
55
|
+
/** The cloud posts a code; the caller exchanges it for the credential. */
|
|
56
|
+
| 'brokered';
|
|
57
|
+
/** What a callback carries that the caller can use to recognise its own request. */
|
|
58
|
+
export type Correlation =
|
|
59
|
+
/** Nothing — the caller can only match on port and timing. */
|
|
60
|
+
'none'
|
|
61
|
+
/** A `code`, which pairs with a PKCE verifier for a strong binding. */
|
|
62
|
+
| 'pkce';
|
|
63
|
+
/**
|
|
64
|
+
* Where to listen and how to answer — the provider's quirks, resolved.
|
|
65
|
+
*
|
|
66
|
+
* Every field here replaces something the caller would otherwise have to know
|
|
67
|
+
* about a specific cloud.
|
|
68
|
+
*/
|
|
69
|
+
export interface CallbackPlan {
|
|
70
|
+
/** Address to listen on, e.g. `127.0.0.1:39821`. */
|
|
71
|
+
readonly address: string;
|
|
72
|
+
/** Path the cloud posts to — whose own name and shape are the provider's business. */
|
|
73
|
+
readonly path: string;
|
|
74
|
+
/** HTTP method of the post. */
|
|
75
|
+
readonly method: string;
|
|
76
|
+
/** When set, the post carries this Content-Type and so triggers a preflight. */
|
|
77
|
+
readonly content_type?: string;
|
|
78
|
+
/**
|
|
79
|
+
* Origins that must be accepted for the callback, exactly.
|
|
80
|
+
*
|
|
81
|
+
* A list because one cloud can post from several (a main site, a regional
|
|
82
|
+
* variant, an embedding host). A response header takes a single value, so
|
|
83
|
+
* the listener echoes the one that matched. Empty means no CORS applies —
|
|
84
|
+
* a top-level navigation rather than a cross-origin fetch.
|
|
85
|
+
*/
|
|
86
|
+
readonly allow_origins?: readonly string[];
|
|
87
|
+
/**
|
|
88
|
+
* Whether the cloud's post arrives as a private-network request.
|
|
89
|
+
*
|
|
90
|
+
* When true the preflight carries `Access-Control-Request-Private-Network`
|
|
91
|
+
* and the response must carry the matching allow header, or the browser
|
|
92
|
+
* drops the real request. Absent and false are equivalent — an older service
|
|
93
|
+
* that does not report it, and a provider whose callback is not cross-origin
|
|
94
|
+
* to a public page, both land there.
|
|
95
|
+
*/
|
|
96
|
+
readonly requires_private_network_access?: boolean;
|
|
97
|
+
/** What the callback carries for correlation; `none` means it carries nothing. */
|
|
98
|
+
readonly correlation: Correlation;
|
|
99
|
+
}
|
|
100
|
+
/** One provider the service can dispatch a login for. */
|
|
101
|
+
export interface ProviderInfo {
|
|
102
|
+
readonly id: string;
|
|
103
|
+
readonly display_name: string;
|
|
104
|
+
readonly delivery: Delivery;
|
|
105
|
+
/** Name of the credential this provider issues, e.g. `ak_sk_sts`. */
|
|
106
|
+
readonly credential_type: string;
|
|
107
|
+
/**
|
|
108
|
+
* Payload field name to type, for the credential the cloud will post.
|
|
109
|
+
*
|
|
110
|
+
* This is the mapping the caller applies — the reason no field name appears
|
|
111
|
+
* as a literal elsewhere in this plugin.
|
|
112
|
+
*/
|
|
113
|
+
readonly credential_schema: Readonly<Record<string, string>>;
|
|
114
|
+
}
|
|
115
|
+
/** Where the browser goes, and how the credential comes back. */
|
|
116
|
+
export interface LoginTarget {
|
|
117
|
+
readonly provider: string;
|
|
118
|
+
readonly delivery: Delivery;
|
|
119
|
+
/** URL to open in the browser. */
|
|
120
|
+
readonly login_url: string;
|
|
121
|
+
readonly callback: CallbackPlan;
|
|
122
|
+
/** Seconds the login remains valid, after which the callback will not arrive. */
|
|
123
|
+
readonly expires_in: number;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* A response this client could not use.
|
|
127
|
+
*
|
|
128
|
+
* Its own type so a caller can tell "the service said no" from "the network
|
|
129
|
+
* failed": both mean the browser-login entry is unavailable, but only the
|
|
130
|
+
* first is worth logging with the service's own words.
|
|
131
|
+
*/
|
|
132
|
+
export declare class AuthContractError extends Error {
|
|
133
|
+
readonly name = "AuthContractError";
|
|
134
|
+
}
|
|
135
|
+
/** Services the client needs, injected so its behavior is testable without a network. */
|
|
136
|
+
export interface ContractDeps {
|
|
137
|
+
/** Performs the request; defaults to the ambient `fetch`. */
|
|
138
|
+
readonly fetch?: typeof fetch;
|
|
139
|
+
/** Service base URL; defaults to {@link AUTH_SERVICE_BASE}. */
|
|
140
|
+
readonly base?: string;
|
|
141
|
+
}
|
|
142
|
+
/**
|
|
143
|
+
* List the providers the service can dispatch for.
|
|
144
|
+
*
|
|
145
|
+
* @param deps - transport overrides.
|
|
146
|
+
* @returns every provider, in the service's order.
|
|
147
|
+
* @throws {AuthContractError} when the service is unreachable or answers unusably.
|
|
148
|
+
*/
|
|
149
|
+
export declare function listProviders(deps?: ContractDeps): Promise<readonly ProviderInfo[]>;
|
|
150
|
+
/**
|
|
151
|
+
* Find one provider by id.
|
|
152
|
+
*
|
|
153
|
+
* @param providerId - the provider to look for.
|
|
154
|
+
* @param deps - transport overrides.
|
|
155
|
+
* @returns the provider, or `undefined` when the service does not offer it.
|
|
156
|
+
* @throws {AuthContractError} when the service is unreachable or answers unusably.
|
|
157
|
+
*/
|
|
158
|
+
export declare function findProvider(providerId: string, deps?: ContractDeps): Promise<ProviderInfo | undefined>;
|
|
159
|
+
/**
|
|
160
|
+
* Ask where the browser should go for one provider.
|
|
161
|
+
*
|
|
162
|
+
* @param providerId - the provider to sign in with.
|
|
163
|
+
* @param redirectUri - the address the caller will listen on. Its host must be
|
|
164
|
+
* loopback and its port explicit; a provider may reject anything else, and
|
|
165
|
+
* the service reports that as a `400` rather than silently adjusting it.
|
|
166
|
+
* @param deps - transport overrides.
|
|
167
|
+
* @returns the browser URL and the callback plan to honour.
|
|
168
|
+
* @throws {AuthContractError} when the service is unreachable, rejects the
|
|
169
|
+
* redirect URI, or answers unusably.
|
|
170
|
+
*/
|
|
171
|
+
export declare function requestLogin(providerId: string, redirectUri: string, deps?: ContractDeps): Promise<LoginTarget>;
|
|
172
|
+
/** Field names this plugin's store understands, as they appear in a `credential_schema`. */
|
|
173
|
+
export interface MappedCredential {
|
|
174
|
+
readonly accessKeyId: string;
|
|
175
|
+
readonly secretAccessKey: string;
|
|
176
|
+
/** Present only when the provider issued one. */
|
|
177
|
+
readonly securityToken?: string;
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* Apply a provider's `credential_schema` to a callback payload.
|
|
181
|
+
*
|
|
182
|
+
* The schema maps a payload key to a type; this pulls the string values out
|
|
183
|
+
* under the names the store uses. A payload missing a field the schema
|
|
184
|
+
* promises is a malformed callback, not a credential — returning `undefined`
|
|
185
|
+
* lets the caller treat it as "nothing arrived" instead of storing half a
|
|
186
|
+
* pair, which is the failure the store's single-record design exists to
|
|
187
|
+
* prevent.
|
|
188
|
+
*
|
|
189
|
+
* A `securitytoken` absent from both the schema and the payload is ordinary —
|
|
190
|
+
* a permanent key has none — so it is optional even though the schema lists
|
|
191
|
+
* it.
|
|
192
|
+
*
|
|
193
|
+
* @param schema - the provider's `credential_schema`.
|
|
194
|
+
* @param payload - the decoded callback body.
|
|
195
|
+
* @returns the credential under this plugin's names, or `undefined` when the
|
|
196
|
+
* payload does not satisfy the schema.
|
|
197
|
+
*/
|
|
198
|
+
export declare function mapCredential(schema: Readonly<Record<string, string>>, payload: Readonly<Record<string, unknown>>): MappedCredential | undefined;
|
|
199
|
+
//# sourceMappingURL=contract.d.ts.map
|
|
@@ -0,0 +1,82 @@
|
|
|
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
|
+
* begin(provider) bind a port, fetch the plan, start serving
|
|
7
|
+
* | -> where to send the browser, where to probe
|
|
8
|
+
* v
|
|
9
|
+
* (the person signs in at the cloud, in their browser, for up to 10 minutes)
|
|
10
|
+
* v
|
|
11
|
+
* the cloud posts the credential to the loopback listener
|
|
12
|
+
* v
|
|
13
|
+
* verify against IAM -> store -> record the outcome for the browser half
|
|
14
|
+
*
|
|
15
|
+
* The outcome does not come back as a return value, because there is nothing
|
|
16
|
+
* waiting on it: the person may take minutes, and an HTTP request held open
|
|
17
|
+
* that long is a request a proxy will cut. So the outcome is *recorded* — in
|
|
18
|
+
* the entry's settings document, which the browser half already subscribes to
|
|
19
|
+
* — and the browser half reads it when it changes. That is the same channel
|
|
20
|
+
* the credential form request already travels on, and the same reasoning.
|
|
21
|
+
*
|
|
22
|
+
* ## Why one at a time
|
|
23
|
+
*
|
|
24
|
+
* The shipped provider's callback carries no correlation string (`correlation:
|
|
25
|
+
* "none"`), so two concurrent logins on two ports could not be told apart by
|
|
26
|
+
* anything but the port itself. The service's own contract states the
|
|
27
|
+
* constraint in the same terms: one login occupies one port. Refusing the
|
|
28
|
+
* second is honest; queueing it would be a promise the flow cannot keep.
|
|
29
|
+
*
|
|
30
|
+
* ## Why a cancel is not a timeout
|
|
31
|
+
*
|
|
32
|
+
* A person who dismisses the form gets the listener closed immediately and no
|
|
33
|
+
* outcome recorded beyond the dismissal. A person who simply walks away leaves
|
|
34
|
+
* the listener bound until either the credential arrives or `expires_in`
|
|
35
|
+
* passes, at which point the cloud will not post and the port is released. The
|
|
36
|
+
* two are distinguished because only the first is a decision.
|
|
37
|
+
*
|
|
38
|
+
* @module @huaweidevtools/aishell-dsh-client-credentials/out-of-band/flow
|
|
39
|
+
*/
|
|
40
|
+
import { type ContractDeps, type MappedCredential, type ProviderInfo } from './contract.ts';
|
|
41
|
+
import { type LoginStartResult } from './routes.ts';
|
|
42
|
+
import type { LoginOutcome } from '../login-status.ts';
|
|
43
|
+
/** Collaborators the flow runs against; injected so it is testable. */
|
|
44
|
+
export interface LoginFlowDeps {
|
|
45
|
+
/**
|
|
46
|
+
* Verify one credential against IAM, returning the account it belongs to.
|
|
47
|
+
*
|
|
48
|
+
* The flow calls this before it stores anything, and treats a rejection as
|
|
49
|
+
* the end of the login. See `./login.ts` for why it is not optional.
|
|
50
|
+
*
|
|
51
|
+
* The name it returns is what the outcome reports: the store's own account
|
|
52
|
+
* hint is written by the reconcile loop on its next tick, so reading it here
|
|
53
|
+
* would report whatever was there *before* this login.
|
|
54
|
+
*/
|
|
55
|
+
readonly verify: (credential: MappedCredential) => Promise<string>;
|
|
56
|
+
/** Write a verified credential to the store. */
|
|
57
|
+
readonly store: (credential: MappedCredential) => Promise<void>;
|
|
58
|
+
/** Record the non-secret status the browser half reads. */
|
|
59
|
+
readonly recordError: (error: string) => void;
|
|
60
|
+
/** Record a completed login for the browser half, or clear it. */
|
|
61
|
+
readonly recordOutcome: (outcome: LoginOutcome | undefined) => void;
|
|
62
|
+
/** Transport overrides for the contract calls. */
|
|
63
|
+
readonly contract?: ContractDeps | undefined;
|
|
64
|
+
}
|
|
65
|
+
/** The browser-login flow. */
|
|
66
|
+
export interface LoginFlow {
|
|
67
|
+
/** Look up a provider; `undefined` when the service does not offer it. */
|
|
68
|
+
readonly findProvider: (providerId: string) => Promise<ProviderInfo | undefined>;
|
|
69
|
+
/** Begin a login. Rejects when one is already running. */
|
|
70
|
+
readonly begin: (provider: ProviderInfo) => Promise<LoginStartResult>;
|
|
71
|
+
/** Abandon the login in progress, if any. Safe to call with none. */
|
|
72
|
+
readonly cancel: () => void;
|
|
73
|
+
/** Whether a login is running. */
|
|
74
|
+
readonly inProgress: () => boolean;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Build the flow.
|
|
78
|
+
*
|
|
79
|
+
* @param deps - the collaborators above.
|
|
80
|
+
*/
|
|
81
|
+
export declare function createLoginFlow(deps: LoginFlowDeps): LoginFlow;
|
|
82
|
+
//# sourceMappingURL=flow.d.ts.map
|