@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,134 @@
|
|
|
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 the browser reach the host from where it is?** Answered by the
|
|
9
|
+
* probe, on demand, 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
|
+
* A browser login works only when the browser can reach a listener on the
|
|
17
|
+
* host. Neither side can tell by looking: an SSH-forwarded session makes a
|
|
18
|
+
* distant browser look local to the host, and a distant host look local to the
|
|
19
|
+
* page. So the browser asks a question only it can ask — *can I reach the
|
|
20
|
+
* host's listener?* — by fetching it. See {@link probeBrowserRoute}.
|
|
21
|
+
*
|
|
22
|
+
* ## The cost of asking
|
|
23
|
+
*
|
|
24
|
+
* The probe borrows a loopback port on the host, is answered once, and gives
|
|
25
|
+
* the port back. It does not begin a login: a card read and abandoned holds
|
|
26
|
+
* nothing. Clicking the button is what binds a port for real, through
|
|
27
|
+
* {@link startBrowserLogin}.
|
|
28
|
+
*
|
|
29
|
+
* @module @huaweidevtools/aishell-dsh-client-credentials/client/login-flow
|
|
30
|
+
*/
|
|
31
|
+
/**
|
|
32
|
+
* A browser login the host has begun and the browser can reach.
|
|
33
|
+
*
|
|
34
|
+
* Holding this means a listener is bound and waiting, so it must be released —
|
|
35
|
+
* see {@link BrowserLoginHandle.cancel} — when the form closes without using
|
|
36
|
+
* it.
|
|
37
|
+
*/
|
|
38
|
+
export interface BrowserLoginHandle {
|
|
39
|
+
/** URL to open when the person chooses this path. */
|
|
40
|
+
readonly loginUrl: string;
|
|
41
|
+
/** Provider's display name, for the copy that names it. */
|
|
42
|
+
readonly providerName: string;
|
|
43
|
+
/**
|
|
44
|
+
* Seconds until the login stops being completable, as the service stated it.
|
|
45
|
+
*
|
|
46
|
+
* The waiting card counts down to this. The host enforces the same number on
|
|
47
|
+
* its listener, so what the person sees and what the port does agree.
|
|
48
|
+
*/
|
|
49
|
+
readonly expiresInSeconds: number;
|
|
50
|
+
/** Release the host's listener; the login will not complete. */
|
|
51
|
+
readonly cancel: () => void;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Ask whether a browser here can reach a loopback listener.
|
|
55
|
+
*
|
|
56
|
+
* ## What it tests, and why only this can
|
|
57
|
+
*
|
|
58
|
+
* The cloud posts a credential to `127.0.0.1` **as the browser's machine
|
|
59
|
+
* resolves it**, so the flow works only when that browser can reach a listener
|
|
60
|
+
* on this host. Neither side can tell by looking: an SSH-forwarded session
|
|
61
|
+
* makes a distant browser look local to the host, and a distant host look local
|
|
62
|
+
* to the page. So the host borrows a port, this page fetches it, and the fetch
|
|
63
|
+
* *is* the answer — resolving means a socket here was reached, rejecting means
|
|
64
|
+
* it was not.
|
|
65
|
+
*
|
|
66
|
+
* The port is released by the host as soon as it is reached, or after a short
|
|
67
|
+
* window. Nothing is kept for the login that may follow: that binds its own
|
|
68
|
+
* port, so a card read and abandoned holds nothing.
|
|
69
|
+
*
|
|
70
|
+
* ## Why the request carries a header
|
|
71
|
+
*
|
|
72
|
+
* The header makes it a non-simple request, so the browser sends a CORS
|
|
73
|
+
* preflight first and only proceeds if the answer is right. The cloud's
|
|
74
|
+
* callback is a JSON POST and therefore *always* preflights, so a plain GET
|
|
75
|
+
* would test a path the callback never takes — and could pass on a route where
|
|
76
|
+
* the real preflight fails, which is the one wrong answer this must not
|
|
77
|
+
* give.
|
|
78
|
+
*
|
|
79
|
+
* @returns whether the route works here. Answered once per page, except when
|
|
80
|
+
* the host could not be reached — see {@link routeProbe}.
|
|
81
|
+
*/
|
|
82
|
+
export declare function probeBrowserRoute(signal?: AbortSignal): Promise<boolean>;
|
|
83
|
+
/**
|
|
84
|
+
* Drop the remembered probe answer.
|
|
85
|
+
*
|
|
86
|
+
* For tests, which need each case to probe for itself. Not called in
|
|
87
|
+
* production: the answer is deliberately kept for the life of the page, and
|
|
88
|
+
* discarding it would only make the next card ask again.
|
|
89
|
+
*/
|
|
90
|
+
export declare function __resetRouteProbe(): void;
|
|
91
|
+
/**
|
|
92
|
+
* Begin a login, now that the person has asked for one.
|
|
93
|
+
*
|
|
94
|
+
* Binds a port and fetches a URL projected for it at this moment, which is why
|
|
95
|
+
* the URL is not stale however long the card sat open before the click.
|
|
96
|
+
*
|
|
97
|
+
* @returns a handle for the login in flight, or `undefined` when the host
|
|
98
|
+
* could not start one.
|
|
99
|
+
*/
|
|
100
|
+
export declare function startBrowserLogin(): Promise<BrowserLoginHandle | undefined>;
|
|
101
|
+
/**
|
|
102
|
+
* Open a blank tab now, and point it at the login page once there is one.
|
|
103
|
+
*
|
|
104
|
+
* ## Why the window is opened before the URL exists
|
|
105
|
+
*
|
|
106
|
+
* A popup is only allowed while the user gesture is live, and a gesture does
|
|
107
|
+
* not survive an `await`. Fetching the login URL first — which is what this
|
|
108
|
+
* has to do, because the URL names a port the host has not bound yet — would
|
|
109
|
+
* spend the gesture, and a blocker would then refuse the tab. Opening the tab
|
|
110
|
+
* synchronously and navigating it a moment later keeps the gesture intact.
|
|
111
|
+
*
|
|
112
|
+
* ## Why the opener reference is severed afterwards
|
|
113
|
+
*
|
|
114
|
+
* `window.open` returns `null` whenever `noopener` appears in its features
|
|
115
|
+
* string — by specification, not as a failure — so passing it there would make
|
|
116
|
+
* every successful open look blocked. The reference is cut immediately after
|
|
117
|
+
* instead, which is the same protection without losing the success signal.
|
|
118
|
+
*
|
|
119
|
+
* @returns a handle whose `navigate` shows the login page, or `undefined` when
|
|
120
|
+
* the browser refused to open a tab at all.
|
|
121
|
+
*/
|
|
122
|
+
export interface LoginWindow {
|
|
123
|
+
/** Point the tab at the login page. */
|
|
124
|
+
readonly navigate: (url: string) => void;
|
|
125
|
+
/** Close the blank tab, when the login could not be started. */
|
|
126
|
+
readonly close: () => void;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Open a blank tab, subject to the current user gesture.
|
|
130
|
+
*
|
|
131
|
+
* @returns the handle, or `undefined` when a blocker refused.
|
|
132
|
+
*/
|
|
133
|
+
export declare function openLoginWindow(): LoginWindow | undefined;
|
|
134
|
+
//# sourceMappingURL=login-flow.d.ts.map
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Client half of the permission-mode switch, shared by both chips.
|
|
3
3
|
*
|
|
4
|
-
* The mode lives in the
|
|
5
|
-
* it
|
|
6
|
-
*
|
|
4
|
+
* The mode lives in the host process (`aishell-deploy`). A Host route reads and
|
|
5
|
+
* writes it; this module owns the fetch and the state hook so the composer chip
|
|
6
|
+
* and the hero chip cannot drift apart.
|
|
7
7
|
*
|
|
8
8
|
* @module @huaweidevtools/aishell-dsh-client-credentials/client/permission-mode
|
|
9
9
|
*/
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The credential form's Host-side control.
|
|
3
|
+
*
|
|
4
|
+
* ## What this is for
|
|
5
|
+
*
|
|
6
|
+
* `aishell__auth` needs credentials that are not there. It cannot collect them
|
|
7
|
+
* — a credential a tool returns is a credential in the transcript — so it asks
|
|
8
|
+
* for the form to be put on screen, the person fills it, and the model calls
|
|
9
|
+
* `auth` again.
|
|
10
|
+
*
|
|
11
|
+
* ## Why the settings document carries the request
|
|
12
|
+
*
|
|
13
|
+
* The two halves live apart: the tool runs on the host, the form is browser
|
|
14
|
+
* code. The host cannot reach the browser over the fetch channel — that channel
|
|
15
|
+
* is browser→host only — so the request has to ride something the browser
|
|
16
|
+
* already watches. The settings document is exactly that: the browser half
|
|
17
|
+
* subscribes to this entry's config through `configForms`, and a volatile field
|
|
18
|
+
* written by the host shows up there.
|
|
19
|
+
*
|
|
20
|
+
* The document carries **only** a request token and a session id. Never a
|
|
21
|
+
* credential, never a verdict — those travel the other way, over the
|
|
22
|
+
* credential route, and the browser never receives a stored secret at all.
|
|
23
|
+
*
|
|
24
|
+
* ## Why the token, not a boolean
|
|
25
|
+
*
|
|
26
|
+
* The browser has to tell "a new request" from "the request it already opened".
|
|
27
|
+
* With a boolean, a second `auth` failure while the form is up would look
|
|
28
|
+
* identical to the first and the form would not re-open after the person
|
|
29
|
+
* cancelled it. The token changes on every request, and the browser compares it
|
|
30
|
+
* to the last one it acted on.
|
|
31
|
+
*
|
|
32
|
+
* ## Why nothing is awaited
|
|
33
|
+
*
|
|
34
|
+
* The tool cannot wait for the person — a tool call has no way to be paused for
|
|
35
|
+
* a human. So `auth` fails, the form appears, and the model calls again. That
|
|
36
|
+
* round trip is the whole protocol, and it is why the failure message and the
|
|
37
|
+
* form are worded as a pair.
|
|
38
|
+
*
|
|
39
|
+
* @module @huaweidevtools/aishell-dsh-client-credentials/form-request
|
|
40
|
+
*/
|
|
41
|
+
/** Field of this entry's config that carries one pending request. */
|
|
42
|
+
export declare const FORM_REQUEST_FIELD = "credentialFormRequest";
|
|
43
|
+
/** What the browser reads out of that field. */
|
|
44
|
+
export interface CredentialFormRequest {
|
|
45
|
+
/**
|
|
46
|
+
* Identity of this request; a fresh value means "open the form again even if
|
|
47
|
+
* you opened one before".
|
|
48
|
+
*/
|
|
49
|
+
readonly token: string;
|
|
50
|
+
/** Conversation to render the form in. */
|
|
51
|
+
readonly sessionId: string;
|
|
52
|
+
}
|
|
53
|
+
/** Writes one path-addressed edit into this entry's settings document. */
|
|
54
|
+
export type RecordField = (value: string) => void;
|
|
55
|
+
/**
|
|
56
|
+
* How one form request ended.
|
|
57
|
+
*
|
|
58
|
+
* `submitted` carries no credential: the form posts to the credential route,
|
|
59
|
+
* which verifies and writes the store, so the tool reads the store afterwards.
|
|
60
|
+
* Nothing about this answer is secret, which is what lets it cross the host
|
|
61
|
+
* without a second review of the leak surface.
|
|
62
|
+
*/
|
|
63
|
+
export type FormOutcome =
|
|
64
|
+
/** The person submitted. The store may or may not hold a usable pair. */
|
|
65
|
+
{
|
|
66
|
+
readonly kind: 'submitted';
|
|
67
|
+
}
|
|
68
|
+
/** The person cancelled. */
|
|
69
|
+
| {
|
|
70
|
+
readonly kind: 'cancelled';
|
|
71
|
+
};
|
|
72
|
+
/**
|
|
73
|
+
* Build a request for one session, minting its token.
|
|
74
|
+
*
|
|
75
|
+
* The token is minted here rather than by the caller so a request cannot be
|
|
76
|
+
* recorded without one — the browser's "is this new?" test would then be
|
|
77
|
+
* comparing against nothing, and the form would not reopen after a cancel.
|
|
78
|
+
*
|
|
79
|
+
* @param sessionId - the conversation the form should render in.
|
|
80
|
+
* @returns the request, and its encoded form for the settings document.
|
|
81
|
+
*/
|
|
82
|
+
export declare function formRequest(sessionId: string): PendingFormRequest;
|
|
83
|
+
/**
|
|
84
|
+
* One request, and the promise its waiting caller is blocked on.
|
|
85
|
+
*
|
|
86
|
+
* The token is what a submit or a cancel names when it answers, so an answer
|
|
87
|
+
* for a superseded request cannot settle the current one.
|
|
88
|
+
*/
|
|
89
|
+
export interface PendingFormRequest {
|
|
90
|
+
readonly request: CredentialFormRequest;
|
|
91
|
+
readonly encoded: string;
|
|
92
|
+
/** Resolves when the person submits or cancels. */
|
|
93
|
+
readonly outcome: Promise<FormOutcome>;
|
|
94
|
+
/** Answer this request. Idempotent: a second call is ignored by `Promise`. */
|
|
95
|
+
readonly settle: (outcome: FormOutcome) => void;
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* Serialize a request for the settings document.
|
|
99
|
+
*
|
|
100
|
+
* The document holds strings — a volatile `string` field is what the browser
|
|
101
|
+
* half reads through `configForms` — so the request is JSON. Encoding rather
|
|
102
|
+
* than reshaping the config into several fields keeps the request atomic: the
|
|
103
|
+
* browser cannot observe a new token with an old session.
|
|
104
|
+
*
|
|
105
|
+
* @param request - the request to encode.
|
|
106
|
+
*/
|
|
107
|
+
export declare function encodeRequest(request: CredentialFormRequest): string;
|
|
108
|
+
/**
|
|
109
|
+
* Read a request back out of the document.
|
|
110
|
+
*
|
|
111
|
+
* Anything unreadable reads as no request: a corrupt field should show nothing,
|
|
112
|
+
* not open a form bound to a session that does not exist.
|
|
113
|
+
*
|
|
114
|
+
* @param raw - the stored string, if any.
|
|
115
|
+
* @returns the request, or `undefined` when there is none usable.
|
|
116
|
+
*/
|
|
117
|
+
export declare function decodeRequest(raw: string | undefined): CredentialFormRequest | undefined;
|
|
118
|
+
//# sourceMappingURL=form-request.d.ts.map
|
package/lib/types/index.d.ts
CHANGED
|
@@ -31,15 +31,28 @@ export interface Config {
|
|
|
31
31
|
/** Readable verification failure the client form displays; set when the IAM check rejects. */
|
|
32
32
|
lastError: Volatile<string>;
|
|
33
33
|
/**
|
|
34
|
-
*
|
|
34
|
+
* A pending request to open the credential form, or `''`.
|
|
35
35
|
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
36
|
+
* Written by `aishell__auth` when it finds no credentials; read by the
|
|
37
|
+
* browser half, which opens the form in the named session. A JSON token plus
|
|
38
|
+
* session id — see `./form-request.ts` for why it is a token and not a
|
|
39
|
+
* boolean, and why it travels the settings document rather than the fetch
|
|
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
|
|
@@ -50,50 +63,15 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
|
|
|
50
63
|
credentialsStored: z<boolean, boolean, "volatile-defined">;
|
|
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
|
-
/**
|
|
61
|
-
* What the credential form collects, as the asking package expects it back.
|
|
62
|
-
*
|
|
63
|
-
* Declared here rather than imported from `aishell-ops-deploy`: the two
|
|
64
|
-
* packages communicate over a Cordis event, not an import (see the event
|
|
65
|
-
* declaration below), and the form has no business depending on the MCP
|
|
66
|
-
* plugin's types. The shape is the contract; both sides state it.
|
|
67
|
-
*
|
|
68
|
-
* No region: the credential store holds none, and the region belongs to
|
|
69
|
-
* whoever is calling. The asking package adds its own when the answer reaches
|
|
70
|
-
* it.
|
|
71
|
-
*/
|
|
72
|
-
interface SuppliedCredentials {
|
|
73
|
-
readonly ak: string;
|
|
74
|
-
readonly sk: string;
|
|
75
|
-
/** Present only for STS credentials. */
|
|
76
|
-
readonly securityToken?: string;
|
|
77
|
-
}
|
|
78
|
-
declare module '@deepseek-ai/cordis' {
|
|
79
|
-
interface Events {
|
|
80
|
-
/**
|
|
81
|
-
* The MCP server asked for credentials and the store has none: show the
|
|
82
|
-
* form, and call `settle` when the person is done.
|
|
83
|
-
*
|
|
84
|
-
* Declared (not imported) on both sides because it is the whole interface
|
|
85
|
-
* between the credentials UI and the MCP plugin — the same shape the
|
|
86
|
-
* permission switch's route uses, one step less direct.
|
|
87
|
-
*
|
|
88
|
-
* @mode emit
|
|
89
|
-
*/
|
|
90
|
-
'aishell/credential-request'(request: {
|
|
91
|
-
readonly settle: (credentials: SuppliedCredentials | undefined) => void;
|
|
92
|
-
readonly signal: AbortSignal | undefined;
|
|
93
|
-
readonly sessionId: string | undefined;
|
|
94
|
-
}): void;
|
|
95
|
-
}
|
|
96
|
-
}
|
|
97
75
|
declare module '@deepseek-ai/cordis' {
|
|
98
76
|
interface Events {
|
|
99
77
|
/**
|
|
@@ -122,9 +100,10 @@ export interface CredentialRoutesDeps {
|
|
|
122
100
|
/** Reads the cached account-name hint for the status response. */
|
|
123
101
|
readonly hint: () => string;
|
|
124
102
|
/**
|
|
125
|
-
* Announces that the stored credentials changed, so consumers that
|
|
126
|
-
*
|
|
127
|
-
* the store actually changed — a rejected save
|
|
103
|
+
* Announces that the stored credentials changed, so consumers that cached
|
|
104
|
+
* something derived from them (a resolved account identity, a sandbox key)
|
|
105
|
+
* can drop it. Called only after the store actually changed — a rejected save
|
|
106
|
+
* stores nothing and stays silent.
|
|
128
107
|
*/
|
|
129
108
|
readonly notifyChanged: () => void;
|
|
130
109
|
}
|
|
@@ -144,5 +123,4 @@ export declare function createCredentialRoutes(deps: CredentialRoutesDeps): {
|
|
|
144
123
|
export declare const name = "aishell-client-credentials";
|
|
145
124
|
export declare const inject: string[];
|
|
146
125
|
export declare function apply(ctx: Context, config: Config): void;
|
|
147
|
-
export {};
|
|
148
126
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -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 on the loopback fetch, the host's listener must allow it in
|
|
29
|
+
* its preflight answer, and a mismatch between the two is a probe that fails
|
|
30
|
+
* on a route that 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
|