@huaweidevtools/aishell-dsh-client-credentials 0.0.1-beta.6 → 0.0.1-beta.8

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,156 @@
1
+ /**
2
+ * The loopback listener: the callback door, and the probe that proves it opens.
3
+ *
4
+ * ## What it is for
5
+ *
6
+ * In the out-of-band flow the cloud itself posts the credential, from the
7
+ * browser, to `127.0.0.1:<port>` — the host is never in that path. So the host
8
+ * must be listening on that port, on the machine the browser runs on, before
9
+ * the browser goes anywhere. This module owns that listener end to end.
10
+ *
11
+ * ## Why binding and serving are separate steps
12
+ *
13
+ * The port has to be known before the login service can be asked to project a
14
+ * redirect URI — one provider takes only the port out of it, and rejects a URI
15
+ * with none. But the plan that says which path and origins to honour only
16
+ * arrives from that same call. So the socket binds first and starts honouring
17
+ * a plan second.
18
+ *
19
+ * Nothing can reach the listener in between: the URL containing the port has
20
+ * been disclosed to nobody yet. A request that arrives anyway is answered
21
+ * `503`, which is honest — the door exists and is not yet open for business.
22
+ *
23
+ * ## Why the probe lives here
24
+ *
25
+ * The listener already has to exist for the callback. The probe reuses it
26
+ * rather than adding a second port, and — more to the point — it exercises
27
+ * *the same machinery* the callback will: a cross-origin request from a page
28
+ * to a loopback address, which means the same preflight, the same PNA
29
+ * handling, and the same response headers. A probe on a throwaway port would
30
+ * prove nothing about whether the real one works.
31
+ *
32
+ * The alternative was inferring reachability — from the socket address of the
33
+ * `/api` request, or from `location.hostname` in the page. Both are wrong in
34
+ * both directions. An SSH-forwarded session makes a distant browser look like
35
+ * loopback to the host, and makes a distant host look like `localhost` to the
36
+ * page; a LAN-addressed browser on the same machine looks remote to both.
37
+ * Only an actual request answers the actual question, so this asks one.
38
+ *
39
+ * ## What makes it hard (every item here is a silent failure)
40
+ *
41
+ * - **Listen on the plan's path, not a guess.** The callback goes to the
42
+ * path the plan names, which for one provider is `/` — a listener mounted
43
+ * anywhere else never receives it.
44
+ * - **Echo one origin, never the list, and never `*`.** An
45
+ * `Access-Control-Allow-Origin` header takes a single value. Writing `*`
46
+ * would let any page on the internet post a forged credential here.
47
+ * - **Send `Vary: Origin`.** Without it a cache can serve one origin's
48
+ * answer to another.
49
+ * - **Answer the Private Network Access preflight, when the plan says so.**
50
+ * A public page reaching loopback triggers a preflight carrying
51
+ * `Access-Control-Request-Private-Network`, and a response lacking the
52
+ * matching allow header makes the browser drop the real request. This
53
+ * never reproduces in local development — only in a real browser, where it
54
+ * looks like a login page that spins forever. The plan carries
55
+ * `requires_private_network_access`; the listener also requires the
56
+ * browser to have actually asked, so it never grants more than was
57
+ * requested.
58
+ * - **Cap the body.** The port is in a URL, so it is not a secret: any local
59
+ * process can post to it. A bound keeps that from becoming memory growth.
60
+ * - **Close after one payload.** It narrows the replay window, and a second
61
+ * post must not overwrite a credential that already arrived.
62
+ *
63
+ * ## The one thing this does not fix
64
+ *
65
+ * A local process can post here with any `Origin` it likes — CORS is a browser
66
+ * policy and does not constrain a process. The service's own documentation
67
+ * records this as unfixable at the receiving end. The defense is that the
68
+ * credential is verified against the cloud before it is stored (see
69
+ * `./login.ts`), which is why nothing here is treated as proof of anything.
70
+ * This listener decides *whether a payload arrived*, never whether it is
71
+ * trustworthy — and the probe is a diagnostic, an authorization check it is
72
+ * not.
73
+ *
74
+ * @module @huaweidevtools/aishell-dsh-client-credentials/out-of-band/listener
75
+ */
76
+ import type { CallbackPlan } from './contract.ts';
77
+ /** Largest callback body accepted. A credential is a few fields; 64 KiB is generous. */
78
+ export declare const MAX_CALLBACK_BYTES: number;
79
+ /**
80
+ * A bound socket that has not been told what to honour yet.
81
+ *
82
+ * Exists only between the bind and the plan arriving; see the module note.
83
+ */
84
+ export interface BoundListener {
85
+ /** Host address bound, always loopback. */
86
+ readonly host: string;
87
+ /** Port the OS assigned — never assume a value. */
88
+ readonly port: number;
89
+ /** `host:port`, for the `redirect_uri` and for comparison against the plan. */
90
+ readonly address: string;
91
+ /**
92
+ * Begin honouring a callback plan and a probe.
93
+ *
94
+ * @param plan - the provider's callback requirements.
95
+ * @param probe - how to answer a reachability probe, or `undefined` for none.
96
+ * @returns the serving listener.
97
+ */
98
+ readonly serve: (plan: CallbackPlan, probe?: ProbeConfig) => CallbackListener;
99
+ /** Stop listening without ever having served. */
100
+ readonly close: () => void;
101
+ }
102
+ /** How the probe asks for a pass. */
103
+ export interface ProbeConfig {
104
+ /**
105
+ * Path the probe is answered on.
106
+ *
107
+ * Distinct from the callback path on purpose: the probe carries no
108
+ * credential, and a probe landing on the callback path would either be
109
+ * treated as one or block the real one.
110
+ */
111
+ readonly path: string;
112
+ /**
113
+ * Secret the probe must present.
114
+ *
115
+ * The probe is answered from whatever origin asks, because the page's own
116
+ * origin is by definition not one of the cloud's callback origins. Echoing
117
+ * an arbitrary origin is only safe because of this value: without it the
118
+ * listener would answer any page that guessed the port, turning it into a
119
+ * local-service fingerprinting beacon. With it, only a caller already
120
+ * holding the nonce — which only the host and its own page ever see — gets
121
+ * an answer.
122
+ */
123
+ readonly nonce: string;
124
+ }
125
+ /** A listener honouring a plan, and the one credential it will accept. */
126
+ export interface CallbackListener {
127
+ /** The address it bound to. */
128
+ readonly address: string;
129
+ /**
130
+ * Resolves with the decoded payload of the first accepted post.
131
+ *
132
+ * Rejects if the listener is closed or errors before a payload arrives.
133
+ * Settles at most once.
134
+ */
135
+ readonly accepted: Promise<Record<string, unknown>>;
136
+ /**
137
+ * Stop listening and drop any pending wait.
138
+ *
139
+ * Idempotent, and safe from a cleanup path that may run after the listener
140
+ * already closed itself on receipt.
141
+ */
142
+ readonly close: () => void;
143
+ }
144
+ /**
145
+ * Bind a loopback port, without yet honouring any plan.
146
+ *
147
+ * Binds before anything else happens, deliberately: the port appears in the
148
+ * redirect URI and is therefore not a secret, so a local process could take it
149
+ * first. Binding early and handing the actual port back is what makes the
150
+ * ordering correct by construction rather than by care.
151
+ *
152
+ * @returns the bound socket.
153
+ * @throws when the port cannot be bound.
154
+ */
155
+ export declare function bindLoopback(): Promise<BoundListener>;
156
+ //# sourceMappingURL=listener.d.ts.map
@@ -0,0 +1,144 @@
1
+ /**
2
+ * One browser login, start to finish.
3
+ *
4
+ * ## What this module does
5
+ *
6
+ * The whole out-of-band flow, in the order the constraints force:
7
+ *
8
+ * 1. Bind the loopback port. **First**, because the port is not a secret — a
9
+ * local process could take it — and because the redirect URI cannot be
10
+ * formed without the port the OS just assigned.
11
+ * 2. Ask the login service where the browser should go, and what callback to
12
+ * expect. That answer is the only thing that knows the provider's quirks.
13
+ * 3. Check the plan's address against what actually bound. A plan naming a
14
+ * different port would leave the person signing in while nothing here
15
+ * could ever receive the result, and the symptom would be a bare timeout.
16
+ * 4. Start serving the plan, and answer the reachability probe so a
17
+ * deployment where the callback cannot arrive says so immediately instead
18
+ * of after the person has been through a cloud login.
19
+ * 5. Hand the browser URL back so the caller can open it.
20
+ * 6. Wait for the payload, then map it through the provider's
21
+ * `credential_schema`.
22
+ * 7. **Verify before returning.** The payload's origin cannot be
23
+ * authenticated — a local process can post to the port and forge the
24
+ * `Origin` header — so the only defense is asking the cloud whether the
25
+ * credential works. See the module note in `./listener.ts`.
26
+ *
27
+ * ## Why verification is not optional
28
+ *
29
+ * `credential` is the contract of this module: it resolves with a credential
30
+ * that has already been proven against the cloud, or it rejects. A caller
31
+ * cannot get an unverified credential out of it, because the one failure mode
32
+ * that matters — a forged credential sailing into the store — is the one this
33
+ * exists to prevent, and a boolean flag is something a caller can forget to
34
+ * check.
35
+ *
36
+ * ## What verification does not catch
37
+ *
38
+ * It proves the credential is *valid*, not that it belongs to the account the
39
+ * person meant to sign in as. A local attacker posting their own real
40
+ * credential passes it. That is the residual risk the service's own docs
41
+ * record as unfixable at the receiving end, and the reason the account is
42
+ * reported back to the person rather than silently stored.
43
+ *
44
+ * @module @huaweidevtools/aishell-dsh-client-credentials/out-of-band/login
45
+ */
46
+ import { type ContractDeps, type MappedCredential, type ProviderInfo } from './contract.ts';
47
+ /**
48
+ * A credential that has been proven against the cloud, and whose account is
49
+ * therefore known.
50
+ *
51
+ * The two travel together because they are established by the same call:
52
+ * verification both proves the credential and names the account it belongs to,
53
+ * so separating them would leave the caller to look the name up again — which
54
+ * is the bug this pairing avoids.
55
+ */
56
+ export interface VerifiedCredential {
57
+ readonly credential: MappedCredential;
58
+ /** The account the credential belongs to, as IAM reported it. */
59
+ readonly accountName: string;
60
+ }
61
+ /**
62
+ * A run of the browser-login flow.
63
+ *
64
+ * The two promises are separate rather than one: `loginUrl` resolves as soon
65
+ * as there is somewhere to send the browser, and `credential` resolves much
66
+ * later, when the person has finished. A single promise would make the caller
67
+ * wait for a URL it needs in order to start the wait.
68
+ */
69
+ export interface BrowserLogin {
70
+ /** The address the callback listener bound to, `host:port`. */
71
+ readonly address: string;
72
+ /**
73
+ * URL to fetch from the page to test whether it can reach the listener.
74
+ *
75
+ * Known as soon as the login starts — the port and nonce are both fixed by
76
+ * then — so it is a plain value rather than a promise.
77
+ */
78
+ readonly probeUrl: string;
79
+ /** Where to send the browser. */
80
+ readonly loginUrl: string;
81
+ /**
82
+ * How long the login stays valid, in seconds — the service's own figure.
83
+ *
84
+ * Sent to the browser half so the waiting card can count down to the moment
85
+ * the callback stops being possible, rather than showing an open-ended
86
+ * spinner.
87
+ */
88
+ readonly expiresInSeconds: number;
89
+ /** The verified credential, or a rejection explaining why there is none. */
90
+ readonly credential: Promise<VerifiedCredential>;
91
+ /** Abandon the login: close the listener and reject anything pending. */
92
+ readonly cancel: () => void;
93
+ }
94
+ /**
95
+ * Find the provider to sign in with, and the schema its credentials use.
96
+ *
97
+ * Separate from {@link startBrowserLogin} because it needs no socket: the
98
+ * browser half can ask "is this even available, and what am I signing in to?"
99
+ * before anything binds.
100
+ *
101
+ * @param providerId - the provider to look for.
102
+ * @param deps - transport overrides.
103
+ * @returns the provider, or `undefined` when the service does not offer it.
104
+ * @throws {AuthContractError} when the service is unreachable or answers unusably.
105
+ */
106
+ export declare function findProvider(providerId: string, deps?: ContractDeps): Promise<ProviderInfo | undefined>;
107
+ /** Options for {@link startBrowserLogin}. */
108
+ export interface StartLoginOptions {
109
+ /** The provider, as the service describes it — including its `credential_schema`. */
110
+ readonly provider: ProviderInfo;
111
+ /**
112
+ * Proves a credential works, and names the account it belongs to.
113
+ *
114
+ * Called before anything is returned, and a rejection ends the login — a
115
+ * throw is the only way to say no, so there is no boolean a caller could
116
+ * forget to check. The resolved name is what a successful login reports.
117
+ */
118
+ readonly verify: (credential: MappedCredential) => Promise<unknown>;
119
+ /**
120
+ * Path the reachability probe is answered on.
121
+ *
122
+ * Supplied by the caller because the browser half must be told the same
123
+ * value, and it is the browser half that sends the probe.
124
+ */
125
+ readonly probePath: string;
126
+ /** Transport overrides for the contract calls. */
127
+ readonly contract?: ContractDeps | undefined;
128
+ }
129
+ /**
130
+ * Begin a browser login.
131
+ *
132
+ * Everything it returns is settled by the time it returns except `credential`,
133
+ * which resolves when the person finishes signing in. The bind, the plan fetch
134
+ * and the plan check all happen first, so a caller that gets a login back
135
+ * knows there is a listener and somewhere to send the browser — a failure in
136
+ * any of those throws instead.
137
+ *
138
+ * @param options - provider, verifier, and the probe path.
139
+ * @returns the running login.
140
+ * @throws {AuthContractError} when the port cannot be bound, the service
141
+ * cannot be reached, or the plan names an address this machine is not on.
142
+ */
143
+ export declare function startBrowserLogin(options: StartLoginOptions): Promise<BrowserLogin>;
144
+ //# sourceMappingURL=login.d.ts.map
@@ -0,0 +1,108 @@
1
+ /**
2
+ * The host-side routes the browser half drives a browser login through.
3
+ *
4
+ * ## Why the flow lives on the host
5
+ *
6
+ * None of it can live in the browser half: the credential arrives at a
7
+ * loopback socket only the host can bind, the plan comes from a service the
8
+ * host reaches, and verification needs the signer. So the host owns the flow
9
+ * and the browser half asks for each step.
10
+ *
11
+ * ## The two routes, and why there is no third
12
+ *
13
+ * POST .../login/start -> bind, fetch the plan, start serving; answer with
14
+ * where to send the browser and where to probe
15
+ * POST .../login/cancel -> the person dismissed the form
16
+ *
17
+ * There is deliberately no `finish`. The outcome arrives on its own schedule —
18
+ * whenever the person finishes signing in, up to ten minutes later — so
19
+ * polling for it would mean a long-held HTTP request, which proxies time out
20
+ * and which this codebase already has a better channel for: the entry's
21
+ * settings document, which the browser half subscribes to. See
22
+ * `./login-status.ts`. The host stores the credential and records the outcome
23
+ * there; nothing needs to ask.
24
+ *
25
+ * ## What `start` does and does not guarantee
26
+ *
27
+ * It returns once a listener is bound and a plan is honoured. It says nothing
28
+ * about whether the browser can *reach* that listener — only a request from
29
+ * the browser answers that, which is what `probeUrl` is for. The page fetches
30
+ * it and decides; the host is not told the result, because the page's decision
31
+ * is the only thing that uses it.
32
+ *
33
+ * @module @huaweidevtools/aishell-dsh-client-credentials/out-of-band/routes
34
+ */
35
+ import type { ProviderInfo } from './contract.ts';
36
+ /** Path the browser half posts to, to begin a login. */
37
+ export declare const LOGIN_START_PATH = "/api/aishell/credentials/login/start";
38
+ /** Path the browser half posts to, to abandon a login. */
39
+ export declare const LOGIN_CANCEL_PATH = "/api/aishell/credentials/login/cancel";
40
+ /**
41
+ * Path the probe is served on, on the callback listener.
42
+ *
43
+ * On the listener rather than the host's `/api` route deliberately: the
44
+ * question is whether the browser can reach *that* socket, so the probe has to
45
+ * be answered there. Under a name no provider will use as a callback path —
46
+ * the shipped provider posts to the root, so anything else is free.
47
+ */
48
+ export declare const LOGIN_PROBE_PATH = "/__aishell_probe";
49
+ /** What the browser half is told when a login starts. */
50
+ export interface LoginStartResult {
51
+ readonly ok: true;
52
+ /** URL to open in the browser. */
53
+ readonly loginUrl: string;
54
+ /**
55
+ * URL the page fetches to test whether it can reach the callback listener.
56
+ *
57
+ * Fetching it is the whole test. A page that cannot reach it will not be
58
+ * able to receive the cloud's callback either, which is the case this
59
+ * reports early instead of after a ten-minute cloud login.
60
+ *
61
+ * What it does *not* test: the cloud's own post. That comes from a different
62
+ * origin and so exercises CORS and Private Network Access differently. This
63
+ * answers only the precondition — is the port reachable from where the
64
+ * browser is — which is the part that varies by deployment.
65
+ */
66
+ readonly probeUrl: string;
67
+ /** Provider being signed in with, for the copy the form shows. */
68
+ readonly providerName: string;
69
+ /**
70
+ * Seconds until the login stops being completable.
71
+ *
72
+ * The waiting card counts down to this so the person can see how long they
73
+ * have, instead of watching an open-ended spinner that will eventually just
74
+ * stop.
75
+ */
76
+ readonly expiresInSeconds: number;
77
+ }
78
+ /** Host-side operations the routes delegate to, injected so they are testable. */
79
+ export interface LoginRouteDeps {
80
+ /**
81
+ * Look up a provider by id.
82
+ *
83
+ * @param providerId - the provider the browser half asked for.
84
+ * @returns the provider, or `undefined` when the service does not offer it.
85
+ */
86
+ readonly findProvider: (providerId: string) => Promise<ProviderInfo | undefined>;
87
+ /**
88
+ * Bind a listener, fetch the plan, and start serving.
89
+ *
90
+ * Resolves once both URLs are known. The credential is not awaited here —
91
+ * it arrives whenever the person finishes, and is delivered through the
92
+ * settings document rather than as this call's result.
93
+ *
94
+ * @param provider - the provider to sign in with.
95
+ * @returns where to send the browser, and where to probe.
96
+ */
97
+ readonly begin: (provider: ProviderInfo) => Promise<LoginStartResult>;
98
+ /** Abandon any login in progress and release its port. */
99
+ readonly cancel: () => void;
100
+ /** Whether a login is already in progress. */
101
+ readonly inProgress: () => boolean;
102
+ }
103
+ /** The login routes, bound to their collaborators. */
104
+ export declare function createLoginRoutes(deps: LoginRouteDeps): {
105
+ start: (request: Request) => Promise<Response>;
106
+ cancel: () => Promise<Response>;
107
+ };
108
+ //# sourceMappingURL=routes.d.ts.map
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@huaweidevtools/aishell-dsh-client-credentials",
3
3
  "description": "AI Shell credentials — chip-opened web form for storing Huawei Cloud AK/SK in the credential store",
4
- "version": "0.0.1-beta.6",
4
+ "version": "0.0.1-beta.8",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
@@ -41,7 +41,7 @@
41
41
  },
42
42
  "license": "Apache-2.0",
43
43
  "dependencies": {
44
- "@huaweidevtools/aishell-dsh-credentials-store": "0.0.1-beta.6"
44
+ "@huaweidevtools/aishell-dsh-credentials-store": "0.0.1-beta.8"
45
45
  },
46
46
  "peerDependencies": {
47
47
  "@deepseek-ai/cordis": "^4.0.4",