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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,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 MCP server process, not in DSH. A Host route relays to
5
- * it over the plugin's own MCP connection; this module owns the fetch and the
6
- * state hook so the composer chip and the hero chip cannot drift apart.
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
@@ -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
- * Session waiting for credentials, or `''` when none is.
34
+ * A pending request to open the credential form, or `''`.
35
35
  *
36
- * The session id rather than a boolean because the browser needs both facts
37
- * and they arrive together: "show the form" and "show it in this
38
- * conversation". `conversation.composer` is session-scoped, so a form without
39
- * a session has nowhere to render. Empty string rather than `undefined` so
40
- * the setting stays one string type across the wire.
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
- credentialRequestSession: Volatile<string>;
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
- credentialRequestSession: z<string, string, "volatile-defined">;
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
- credentialRequestSession: z<string, string, "volatile-defined">;
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 hold a
126
- * snapshot of them (the MCP subprocess env) can rebuild. Called only after
127
- * the store actually changed — a rejected save stores nothing and stays silent.
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