@o3co/auth-provider-foundation 0.9.0 → 0.10.0

package/README.ja.md

@@ -41,6 +41,7 @@ class HttpUserRepository implements UserRepository {
     authenticateUrl: string;        // ユーザー名・パスワード認証用の POST エンドポイント
     authenticateByTokenUrl: string; // トークン認証用の POST エンドポイント
     timeout: number;                // リクエストタイムアウト（ミリ秒）
+    maxResponseBytes?: number;      // レスポンスボディの上限、デフォルト 1 MiB
   });
 
   // authenticateUrl に対して { email, password } を POST
@@ -53,6 +54,21 @@ class HttpUserRepository implements UserRepository {
 
 - HTTP 401 または 403 の場合は `null` を返す。
 - その他の非 OK ステータスの場合はエラーをスローする。
+- 上流が 2xx で `User`（`{ id: string, username: string, … }`）以外の JSON を返した場合もスローする — 「ユーザーが見つからない」ではなく「上流が壊れている」ケースのため。
+
+### コンストラクタでの検証
+
+すべてのオプションは**コンストラクタ**で検証される。設定を誤ったデプロイは最初のログイン時ではなく起動時に失敗する。
+
+**両方の URL は `https://` でなければならない。** これらは平文のユーザー資格情報（`authenticateUrl` にはパスワード、`authenticateByTokenUrl` にはトークン）を運ぶため、`http://` は接続を弱めるだけでなく、経路上のすべてのホップに資格情報を公開する。
+
+**唯一の例外は loopback。** ホストが `localhost`、`127.0.0.0/8` 内のアドレス、`[::1]` のいずれかであれば `http://` を許可する。この通信はマシンの外に出ないため、ローカル開発およびインプロセスのテストフィクスチャは証明書を必要としない。それ以外のホストは**プライベートレンジのアドレスやコンテナネットワークのサービス名を含めて** `https://` が必須（`http://10.0.0.5/…`、`http://user-service/…` は拒否される）。これらはデプロイが端から端まで制御していないネットワークを越えるものであり、「内部」は「暗号化済み」の同義語ではない。URL に資格情報を埋め込んだもの（`https://user:pass@…`）も拒否する。
+
+これは [`@o3co/auth-provider-core`](../core/README.ja.md) の `oauth.jwt.issuer` と同じルールで、例外の範囲を `127.0.0.1` 単一アドレスから `127.0.0.0/8` ブロック全体へ広げ、クエリ文字列を許可している（issuer は持てないが、POST エンドポイントは正当に持ちうる）。
+
+**`timeout` は `2147483647` ミリ秒以下の正の整数でなければならない。** `0`・負数・`NaN` は `setTimeout` ではいずれも「即時発火」に丸められ（＝すべてのリクエストが中断される）、Node のタイマー範囲を超える値は 1ms に丸められるため、「長めに待つ」つもりの設定が最短のタイムアウトになってしまう。デッドラインは**ボディ読み取りを含む**やり取り全体に適用される。ボディ読み取りは abort signal 頼みではなくデッドラインとの race で打ち切る — 実行中の `read()` は abort では確実に中断されないため。これはヘッダだけ即座に返してボディを止める slow-loris の形であり、race がなければ永久にハングする。超過したリクエストはエンドポイント名を含む `timed out after <n>ms` エラーで reject される。
+
+**`maxResponseBytes` は正の整数でなければならない。** デフォルトは `DEFAULT_MAX_RESPONSE_BYTES`（1 MiB）。上限は `Content-Length` に対してもストリーム読み取り中にも適用されるため、ヘッダを省略する（あるいは偽る）上流も途中で打ち切られ、メモリを食い潰すことはできない。
 
 ## 使い方
 

package/README.md

@@ -41,6 +41,7 @@ class HttpUserRepository implements UserRepository {
     authenticateUrl: string;        // POST endpoint for username/password auth
     authenticateByTokenUrl: string; // POST endpoint for token-based auth
     timeout: number;                // request timeout in milliseconds
+    maxResponseBytes?: number;      // response body cap, default 1 MiB
   });
 
   // POST authenticateUrl with body: { email, password }
@@ -53,6 +54,49 @@ class HttpUserRepository implements UserRepository {
 
 - Returns `null` on HTTP 401 or 403.
 - Throws an error on any other non-OK HTTP status.
+- Throws when the upstream returns 2xx with a body that is not a JSON `User`
+  (`{ id: string, username: string, … }`) — an upstream failure, not a
+  "user not found".
+
+### Constructor validation
+
+Every option is validated in the **constructor**, so a misconfigured deployment
+fails at boot rather than at the first login attempt.
+
+**Both URLs must use `https://`.** They carry plaintext user credentials — a
+password on `authenticateUrl`, a token on `authenticateByTokenUrl` — so an
+`http://` URL does not merely weaken the connection, it publishes the credential
+to every hop on the path.
+
+**The one carve-out is loopback:** `http://` is accepted when the host is
+`localhost`, an address in `127.0.0.0/8`, or `[::1]`. That traffic never leaves
+the machine, so local development and in-process test fixtures need no
+certificate. Every other host must use `https://`, **including private-range
+addresses and container-network service names** (`http://10.0.0.5/…`,
+`http://user-service/…` are refused): those cross a network the deployment does
+not control end to end, and "internal" is not a synonym for "encrypted". URLs
+embedding credentials (`https://user:pass@…`) are refused as well.
+
+This is the same rule `oauth.jwt.issuer` applies in
+[`@o3co/auth-provider-core`](../core/README.md), with the carve-out widened from
+the single address `127.0.0.1` to the whole `127.0.0.0/8` block, and query
+strings allowed (an issuer may not carry one; a POST endpoint legitimately may).
+
+**`timeout` must be a positive integer** no greater than `2147483647`
+milliseconds. `0`, a negative number, and `NaN` all clamp to "fire immediately"
+in `setTimeout` — which would abort every request — and a value above Node's
+timer range clamps to 1ms, turning "be patient" into the most impatient setting
+available. The deadline covers the whole exchange, **body included**: the body
+read is raced against it rather than relying on the abort signal, because
+aborting a request does not reliably interrupt a read already in flight. That is
+the slow-loris shape — headers arrive promptly, then the body dribbles or stops
+— and without the race it hangs forever. A request that outlives the deadline
+rejects with a `timed out after <n>ms` error naming the endpoint.
+
+**`maxResponseBytes` must be a positive integer**, defaulting to
+`DEFAULT_MAX_RESPONSE_BYTES` (1 MiB). The cap is enforced against
+`Content-Length` *and* while streaming, so a Store that omits the header — or
+lies in it — is still cut off rather than allowed to exhaust memory.
 
 ## Usage Example
 

package/dist/endpointUrl.d.mts

@@ -0,0 +1,59 @@
+/**
+ * Transport validation for the Store endpoints `HttpUserRepository` posts to.
+ *
+ * These endpoints receive **plaintext user credentials** — a password on
+ * `authenticateUrl`, a bearer-ish token on `authenticateByTokenUrl`. An
+ * `http://` URL therefore does not merely weaken the connection, it publishes
+ * the credential to every hop on the path. A single mistyped environment
+ * variable was enough to do that, and nothing anywhere refused it (#285).
+ *
+ * ## The loopback carve-out
+ *
+ * `http://` is accepted for **loopback hosts only** — `localhost`, anything in
+ * `127.0.0.0/8`, and `[::1]`. Traffic to a loopback address never leaves the
+ * machine, so there is no path to eavesdrop on, and requiring TLS there would
+ * force every local development setup and every in-process test fixture to
+ * provision a certificate for no security gain. Any other host — including a
+ * private-range address such as `10.0.0.5` or a service name on a container
+ * network — must use `https://`: those cross a network the deployment does not
+ * control end to end, and "internal" is not a synonym for "encrypted".
+ *
+ * The rule matches `oauth.jwt.issuer`'s (`checkCanonicalIssuer` in
+ * `@o3co/auth-provider-core`) so operators meet one policy, not two. It is kept
+ * separate rather than reused because the constraints genuinely differ: an
+ * issuer may not carry a query string or fragment (OIDC Discovery derives the
+ * metadata URL from it), while a Store endpoint is an ordinary POST target for
+ * which `?tenant=acme` is legitimate. The loopback *predicate* the carve-out
+ * runs on, though, is shared vocabulary: `isLoopbackHostname` comes from
+ * `@o3co/auth-provider-core` (`net/loopback`, #364), the same definition the
+ * session redirect policy consumes, so the carve-outs cannot drift apart.
+ */
+import { isLoopbackHostname } from "@o3co/auth-provider-core";
+export { isLoopbackHostname };
+/** Why a candidate endpoint was rejected, phrased for a boot-time error. */
+export type EndpointRejection = "not-a-string" | "empty" | "not-absolute-url" | "unsupported-scheme" | "insecure-scheme" | "has-credentials";
+/**
+ * Returns `null` when `value` is a usable Store endpoint, otherwise the reason
+ * it is not. See the module comment for the loopback carve-out.
+ */
+export declare function checkSecureEndpoint(value: unknown): EndpointRejection | null;
+/**
+ * Operator-facing explanation for each rejection reason.
+ *
+ * This is what an operator reads at boot when their Store URL is refused, so
+ * every message states the **actual** rule rather than a simplification of it.
+ * In particular both scheme messages name the loopback carve-out: saying only
+ * "must use https" would contradict a policy that does accept `http://` on
+ * loopback, and send someone hunting for a certificate they do not need.
+ */
+export declare function describeEndpointRejection(reason: EndpointRejection): string;
+/**
+ * Returns `value` when it is a usable Store endpoint, otherwise throws naming
+ * `field` and the reason.
+ *
+ * The rejected value is deliberately **not** echoed into the message: it is
+ * operator-supplied configuration that may embed a secret, and a boot error
+ * lands in logs.
+ */
+export declare function assertSecureEndpoint(value: unknown, field: string): string;
+//# sourceMappingURL=endpointUrl.d.mts.map

package/dist/endpointUrl.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpointUrl.d.mts","sourceRoot":"","sources":["../src/endpointUrl.mts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAK9D,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAE9B,4EAA4E;AAC5E,MAAM,MAAM,iBAAiB,GAC1B,cAAc,GACd,OAAO,GACP,kBAAkB,GAClB,oBAAoB,GACpB,iBAAiB,GACjB,iBAAiB,CAAC;AAKrB;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAyB5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAwB3E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAS1E"}

package/dist/endpointUrl.mjs

@@ -0,0 +1,129 @@
+/*
+ * Copyright 2026 1o1 Co. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Transport validation for the Store endpoints `HttpUserRepository` posts to.
+ *
+ * These endpoints receive **plaintext user credentials** — a password on
+ * `authenticateUrl`, a bearer-ish token on `authenticateByTokenUrl`. An
+ * `http://` URL therefore does not merely weaken the connection, it publishes
+ * the credential to every hop on the path. A single mistyped environment
+ * variable was enough to do that, and nothing anywhere refused it (#285).
+ *
+ * ## The loopback carve-out
+ *
+ * `http://` is accepted for **loopback hosts only** — `localhost`, anything in
+ * `127.0.0.0/8`, and `[::1]`. Traffic to a loopback address never leaves the
+ * machine, so there is no path to eavesdrop on, and requiring TLS there would
+ * force every local development setup and every in-process test fixture to
+ * provision a certificate for no security gain. Any other host — including a
+ * private-range address such as `10.0.0.5` or a service name on a container
+ * network — must use `https://`: those cross a network the deployment does not
+ * control end to end, and "internal" is not a synonym for "encrypted".
+ *
+ * The rule matches `oauth.jwt.issuer`'s (`checkCanonicalIssuer` in
+ * `@o3co/auth-provider-core`) so operators meet one policy, not two. It is kept
+ * separate rather than reused because the constraints genuinely differ: an
+ * issuer may not carry a query string or fragment (OIDC Discovery derives the
+ * metadata URL from it), while a Store endpoint is an ordinary POST target for
+ * which `?tenant=acme` is legitimate. The loopback *predicate* the carve-out
+ * runs on, though, is shared vocabulary: `isLoopbackHostname` comes from
+ * `@o3co/auth-provider-core` (`net/loopback`, #364), the same definition the
+ * session redirect policy consumes, so the carve-outs cannot drift apart.
+ */
+import { isLoopbackHostname } from "@o3co/auth-provider-core";
+// Re-exported unchanged: this module's callers (and its tests) read the
+// predicate as part of the endpoint-validation surface. The definition lives
+// in core (#364) — re-exporting is the sanctioned way to surface it.
+export { isLoopbackHostname };
+/** Matches `scheme://` — the shape that distinguishes an absolute URL from a bare host. */
+const ABSOLUTE_URL_PREFIX = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//;
+/**
+ * Returns `null` when `value` is a usable Store endpoint, otherwise the reason
+ * it is not. See the module comment for the loopback carve-out.
+ */
+export function checkSecureEndpoint(value) {
+    if (typeof value !== "string")
+        return "not-a-string";
+    if (value === "")
+        return "empty";
+    // `new URL("users.example.com:3000")` succeeds with `users.example.com:` as
+    // the scheme and no host, so a bare host is reported as the missing-scheme
+    // mistake it is rather than as an exotic scheme.
+    if (!ABSOLUTE_URL_PREFIX.test(value))
+        return "not-absolute-url";
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return "not-absolute-url";
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        return "unsupported-scheme";
+    // No empty-host check is needed below: `http` and `https` are "special"
+    // schemes, for which the WHATWG parser requires a non-empty host — a
+    // host-less `https://` or `https://:8080/x` throws above and is reported as
+    // `not-absolute-url` rather than reaching here with `hostname === ""`.
+    if (url.protocol === "http:" && !isLoopbackHostname(url.hostname))
+        return "insecure-scheme";
+    if (url.username !== "" || url.password !== "")
+        return "has-credentials";
+    return null;
+}
+/**
+ * Operator-facing explanation for each rejection reason.
+ *
+ * This is what an operator reads at boot when their Store URL is refused, so
+ * every message states the **actual** rule rather than a simplification of it.
+ * In particular both scheme messages name the loopback carve-out: saying only
+ * "must use https" would contradict a policy that does accept `http://` on
+ * loopback, and send someone hunting for a certificate they do not need.
+ */
+export function describeEndpointRejection(reason) {
+    switch (reason) {
+        case "not-a-string":
+            return "must be a string";
+        case "empty":
+            return 'must not be empty (an unset or blank environment variable substitutes as "")';
+        case "not-absolute-url":
+            return ("must be an absolute URL with a host (e.g. https://users.example.com/authenticate), " +
+                "not a bare host or a path");
+        case "unsupported-scheme":
+            return ("must use https, or http for a loopback host (localhost, 127.0.0.0/8, [::1]) — " +
+                "no other scheme is accepted");
+        case "insecure-scheme":
+            return ("must use https — it carries plaintext user credentials; http is accepted only for " +
+                "a loopback host (localhost, 127.0.0.0/8, [::1])");
+        case "has-credentials":
+            return "must not embed credentials in the URL";
+    }
+}
+/**
+ * Returns `value` when it is a usable Store endpoint, otherwise throws naming
+ * `field` and the reason.
+ *
+ * The rejected value is deliberately **not** echoed into the message: it is
+ * operator-supplied configuration that may embed a secret, and a boot error
+ * lands in logs.
+ */
+export function assertSecureEndpoint(value, field) {
+    const rejection = checkSecureEndpoint(value);
+    if (rejection !== null) {
+        throw new Error(`HttpUserRepository: "${field}" ${describeEndpointRejection(rejection)} ` +
+            `(reason: ${rejection})`);
+    }
+    return value;
+}

package/dist/index.d.mts

@@ -2,5 +2,5 @@ import type { AdapterFactory, UserRepository } from "@o3co/auth-provider-core";
 export declare const registerBuiltinAdapters: (factories: {
     userFactory: AdapterFactory<UserRepository>;
 }) => void;
-export { HttpUserRepository } from "./repositories/HttpUserRepository.mjs";
+export { DEFAULT_MAX_RESPONSE_BYTES, HttpUserRepository, } from "./repositories/HttpUserRepository.mjs";
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/E,eAAO,MAAM,uBAAuB,GAAI,WAAW;IAClD,WAAW,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC;CAC5C,KAAG,IAyBH,CAAC;AAEF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AA6B/E,eAAO,MAAM,uBAAuB,GAAI,WAAW;IAClD,WAAW,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC;CAC5C,KAAG,IAkBH,CAAC;AAEF,OAAO,EACN,0BAA0B,EAC1B,kBAAkB,GAClB,MAAM,uCAAuC,CAAC"}

package/dist/index.mjs

@@ -13,7 +13,31 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { HttpUserRepository } from "./repositories/HttpUserRepository.mjs";
+import { DEFAULT_MAX_RESPONSE_BYTES, HttpUserRepository, } from "./repositories/HttpUserRepository.mjs";
+/** Default request deadline, in milliseconds, when the config names none. */
+const DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * Coerces a numeric config value that may arrive as a string.
+ *
+ * HOCON environment substitution yields strings, so `CLIENT_USER_TIMEOUT=1234`
+ * reaches the builder as `"1234"`. An *absent* key takes `fallback`; anything
+ * present but unreadable becomes `NaN` and is rejected by the constructor,
+ * which owns the range rules and names the field in its message.
+ *
+ * The distinction matters because HOCON substitutes a **blank** environment
+ * variable as `""` — a very ordinary shape in a `.env` file or an empty
+ * ConfigMap key — and `Number("")` is `0`. This used to fall back to the
+ * default, hiding the misconfiguration; it is now a boot failure (#285).
+ */
+const toNumber = (value, fallback) => {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "string")
+        return Number(value.trim());
+    return Number.NaN;
+};
 export const registerBuiltinAdapters = (factories) => {
     factories.userFactory.register("http", (config) => {
         if (typeof config.authenticateUrl !== "string") {
@@ -22,22 +46,15 @@ export const registerBuiltinAdapters = (factories) => {
         if (typeof config.authenticateByTokenUrl !== "string") {
             throw new Error('HttpUserRepository requires "authenticateByTokenUrl" in config');
         }
+        // Every remaining check — https-or-loopback, positive-integer timeout,
+        // positive-integer cap — lives in the constructor, so a repository built
+        // by hand is validated exactly as one built from config.
         return new HttpUserRepository({
             authenticateUrl: config.authenticateUrl,
             authenticateByTokenUrl: config.authenticateByTokenUrl,
-            timeout: (() => {
-                if (typeof config.timeout === "number" && Number.isFinite(config.timeout)) {
-                    return config.timeout;
-                }
-                if (typeof config.timeout === "string") {
-                    const n = Number(config.timeout);
-                    if (Number.isFinite(n) && n > 0) {
-                        return n;
-                    }
-                }
-                return 5000;
-            })(),
+            timeout: toNumber(config.timeout, DEFAULT_TIMEOUT_MS),
+            maxResponseBytes: toNumber(config.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES),
         });
     });
 };
-export { HttpUserRepository } from "./repositories/HttpUserRepository.mjs";
+export { DEFAULT_MAX_RESPONSE_BYTES, HttpUserRepository, } from "./repositories/HttpUserRepository.mjs";

package/dist/repositories/HttpUserRepository.d.mts

@@ -1,12 +1,31 @@
 import type { User, UserRepository } from "@o3co/auth-provider-core";
+/**
+ * Default ceiling on an upstream response body, in bytes.
+ *
+ * A `User` record is a few hundred bytes; 1 MiB is generous for one carrying
+ * custom claims and small enough that a hostile or broken Store cannot walk the
+ * process out of memory one login at a time (#285).
+ */
+export declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+/**
+ * `UserRepository` backed by an upstream HTTP user service ("the Store").
+ *
+ * Both endpoints receive plaintext user credentials, so both are validated at
+ * **construction**: a deployment configured with an `http://` Store URL fails
+ * at boot rather than leaking the first user's password (#285). `http://` is
+ * accepted for loopback hosts only — see `src/endpointUrl.mts` for the
+ * carve-out and its rationale.
+ */
 export declare class HttpUserRepository implements UserRepository {
     private authenticateUrl;
     private authenticateByTokenUrl;
     private timeout;
-    constructor({ authenticateUrl, authenticateByTokenUrl, timeout, }: {
+    private maxResponseBytes;
+    constructor({ authenticateUrl, authenticateByTokenUrl, timeout, maxResponseBytes, }: {
         authenticateUrl: string;
         authenticateByTokenUrl: string;
         timeout: number;
+        maxResponseBytes?: number;
     });
     authenticate(username: string, password: string): Promise<User | null>;
     authenticateByToken(token: string): Promise<User | null>;

package/dist/repositories/HttpUserRepository.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"HttpUserRepository.d.mts","sourceRoot":"","sources":["../../src/repositories/HttpUserRepository.mts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAuBrE,qBAAa,kBAAmB,YAAW,cAAc;IACxD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,OAAO,CAAS;gBAEZ,EACX,eAAe,EACf,sBAAsB,EACtB,OAAO,GACP,EAAE;QACF,eAAe,EAAE,MAAM,CAAC;QACxB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,OAAO,EAAE,MAAM,CAAC;KAChB;IAMK,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAItE,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;YAIhD,IAAI;CAiClB"}
+{"version":3,"file":"HttpUserRepository.d.mts","sourceRoot":"","sources":["../../src/repositories/HttpUserRepository.mts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAGrE;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAAc,CAAC;AAkItD;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IACxD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,gBAAgB,CAAS;gBAErB,EACX,eAAe,EACf,sBAAsB,EACtB,OAAO,EACP,gBAA6C,GAC7C,EAAE;QACF,eAAe,EAAE,MAAM,CAAC;QACxB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC1B;IAqBK,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAItE,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;YAIhD,IAAI;CAqElB"}

package/dist/repositories/HttpUserRepository.mjs

@@ -13,6 +13,21 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { assertSecureEndpoint } from "../endpointUrl.mjs";
+/**
+ * Default ceiling on an upstream response body, in bytes.
+ *
+ * A `User` record is a few hundred bytes; 1 MiB is generous for one carrying
+ * custom claims and small enough that a hostile or broken Store cannot walk the
+ * process out of memory one login at a time (#285).
+ */
+export const DEFAULT_MAX_RESPONSE_BYTES = 1024 * 1024;
+/**
+ * Largest delay Node's timer subsystem represents. Anything above it is
+ * silently clamped to 1ms — so an operator writing a very large number meaning
+ * "be patient" would otherwise get the most impatient timeout possible.
+ */
+const MAX_TIMEOUT_MS = 2_147_483_647;
 /**
  * Runtime guard for the upstream user-service response. The previous
  * `(await res.json()) as User` was a compile-time cast only — a malformed
@@ -34,14 +49,120 @@ function isUser(v) {
     const o = v;
     return typeof o.id === "string" && typeof o.username === "string";
 }
+/** Whether `value` is a positive integer that fits `bound`. */
+function isPositiveIntegerWithin(value, bound) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= bound;
+}
+/**
+ * Releases a response body we are not going to read.
+ *
+ * Without this an error or 401 leaves the body unconsumed, and undici holds the
+ * socket until the response is garbage collected rather than returning it to
+ * the keep-alive pool — a slow leak on the failure path, which is exactly the
+ * path a struggling deployment spends its time on.
+ *
+ * Deliberately not awaited: cancelling is a signal to the transport, and how
+ * long the peer takes to act on it is the peer's business. Awaiting would hand
+ * a hostile Store a second way to stall the caller — the one the request
+ * deadline exists to close — and some interceptors never settle it at all.
+ */
+function discardBody(res) {
+    res.body?.cancel().catch(() => {
+        // Already consumed, already errored, or aborted — nothing to release.
+    });
+}
+/**
+ * Reads at most `limit` bytes of `res` and returns them as text, throwing once
+ * the limit is passed.
+ *
+ * `Content-Length` is checked first so an honest oversized response is refused
+ * before a byte of it is read, but the streaming count is the load-bearing
+ * half: a hostile Store simply omits the header (or lies), and chunked transfer
+ * encoding has none to omit.
+ */
+async function readBodyCapped(res, limit, url, deadline) {
+    const declared = Number(res.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > limit) {
+        discardBody(res);
+        throw new Error(`HttpUserRepository: upstream ${url} response exceeds the ${limit}-byte cap ` +
+            `(Content-Length: ${declared})`);
+    }
+    if (res.body === null)
+        return "";
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let text = "";
+    let read = 0;
+    try {
+        for (;;) {
+            // Raced against the deadline rather than relying on `signal` alone:
+            // aborting a request does not reliably interrupt a `read()` already
+            // in flight, which is exactly the slow-loris shape — headers arrive
+            // promptly, then the body dribbles or stops. One absolute deadline
+            // for the whole exchange, not a fresh one per chunk.
+            const { done, value } = await Promise.race([reader.read(), deadline]);
+            if (done)
+                break;
+            read += value.byteLength;
+            if (read > limit) {
+                throw new Error(`HttpUserRepository: upstream ${url} response exceeds the ${limit}-byte cap`);
+            }
+            text += decoder.decode(value, { stream: true });
+        }
+    }
+    finally {
+        // Tears down the connection when we bail out early; a no-op once the
+        // stream has completed on its own. Not awaited, for the reason given on
+        // `discardBody`.
+        reader.cancel().catch(() => { });
+    }
+    return text + decoder.decode();
+}
+/**
+ * Whether `err` is the abort our own deadline raised on the `fetch` itself —
+ * the case where the response headers never arrive.
+ *
+ * A deliberately shallow check. An aborted `fetch` rejects with the
+ * `AbortError` directly; the wrapping that `fetch` does apply is for network
+ * failures, which are not aborts. If some runtime did wrap one, the request
+ * still fails — it would simply surface the runtime's message instead of ours,
+ * which is a cosmetic difference and not worth an untestable `cause` walk.
+ * A stalled *body* is not covered here at all: that is the deadline race in
+ * `readBodyCapped`, which does not depend on abort semantics.
+ */
+function isAbortError(err) {
+    // Optional chaining rather than a `typeof` guard: it covers `null`,
+    // `undefined` and a thrown primitive in the same expression, with no
+    // branch that only a contrived throw could reach.
+    const name = err?.name;
+    return name === "AbortError" || name === "TimeoutError";
+}
+/**
+ * `UserRepository` backed by an upstream HTTP user service ("the Store").
+ *
+ * Both endpoints receive plaintext user credentials, so both are validated at
+ * **construction**: a deployment configured with an `http://` Store URL fails
+ * at boot rather than leaking the first user's password (#285). `http://` is
+ * accepted for loopback hosts only — see `src/endpointUrl.mts` for the
+ * carve-out and its rationale.
+ */
 export class HttpUserRepository {
     authenticateUrl;
     authenticateByTokenUrl;
     timeout;
-    constructor({ authenticateUrl, authenticateByTokenUrl, timeout, }) {
-        this.authenticateUrl = authenticateUrl;
-        this.authenticateByTokenUrl = authenticateByTokenUrl;
+    maxResponseBytes;
+    constructor({ authenticateUrl, authenticateByTokenUrl, timeout, maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES, }) {
+        this.authenticateUrl = assertSecureEndpoint(authenticateUrl, "authenticateUrl");
+        this.authenticateByTokenUrl = assertSecureEndpoint(authenticateByTokenUrl, "authenticateByTokenUrl");
+        if (!isPositiveIntegerWithin(timeout, MAX_TIMEOUT_MS)) {
+            throw new Error(`HttpUserRepository: "timeout" must be a positive integer no greater than ` +
+                `${MAX_TIMEOUT_MS} milliseconds`);
+        }
         this.timeout = timeout;
+        if (!isPositiveIntegerWithin(maxResponseBytes, Number.MAX_SAFE_INTEGER)) {
+            throw new Error('HttpUserRepository: "maxResponseBytes" must be a positive integer');
+        }
+        this.maxResponseBytes = maxResponseBytes;
     }
     async authenticate(username, password) {
         return this.post(this.authenticateUrl, { email: username, password });
@@ -51,7 +172,22 @@ export class HttpUserRepository {
     }
     async post(url, body) {
         const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), this.timeout);
+        let timedOut = false;
+        // One absolute deadline for the whole exchange, expressed twice: as the
+        // abort signal `fetch` understands, and as a promise the body read can be
+        // raced against. `.catch` is attached up front so an exchange that
+        // finishes first — the overwhelmingly common case, where the timer is
+        // cleared and this never rejects — cannot leave an unhandled rejection.
+        let fireDeadline = () => { };
+        const deadline = new Promise((_resolve, reject) => {
+            fireDeadline = () => reject(new Error(`HttpUserRepository: request to ${url} timed out after ${this.timeout}ms`));
+        });
+        deadline.catch(() => { });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+            fireDeadline();
+        }, this.timeout);
         try {
             const res = await fetch(url, {
                 method: "POST",
@@ -60,7 +196,17 @@ export class HttpUserRepository {
                 signal: controller.signal,
             });
             if (res.ok) {
-                const parsed = await res.json();
+                const raw = await readBodyCapped(res, this.maxResponseBytes, url, deadline);
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    // Same class of failure as the shape check below: the Store is
+                    // broken, not the credential. Reported as ours rather than as a
+                    // bare SyntaxError with no indication of where it came from.
+                    throw new Error(`HttpUserRepository: upstream ${url} returned a non-JSON body`);
+                }
                 if (!isUser(parsed)) {
                     // Upstream returned 2xx with an unexpected shape — this is an
                     // "upstream is broken" case, not a "user not found" case, so
@@ -70,11 +216,18 @@ export class HttpUserRepository {
                 }
                 return parsed;
             }
+            discardBody(res);
             if (res.status === 401 || res.status === 403) {
                 return null;
             }
             throw new Error(`Unexpected HTTP status ${res.status} from ${url}`);
         }
+        catch (err) {
+            if (timedOut && isAbortError(err)) {
+                throw new Error(`HttpUserRepository: request to ${url} timed out after ${this.timeout}ms`);
+            }
+            throw err;
+        }
         finally {
             clearTimeout(timer);
         }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@o3co/auth-provider-foundation",
   "description": "Production HTTP user-authentication adapter for auth.provider",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=18.19.0"
+    "node": ">=22.0.0"
   },
   "type": "module",
   "main": "./dist/index.mjs",
@@ -35,12 +35,12 @@
     "@o3co/auth-provider-core": "^0.0.0"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
-    "msw": "^2.14.6",
+    "@types/node": "^26.2.0",
+    "msw": "^2.15.0",
     "pino": "^10.3.1",
-    "vitest": "^4.1.8",
-    "@vitest/coverage-v8": "^4.1.6",
-    "@o3co/auth-provider-core": "0.9.0"
+    "vitest": "^4.1.10",
+    "@vitest/coverage-v8": "^4.1.10",
+    "@o3co/auth-provider-core": "0.10.0"
   },
   "scripts": {
     "prebuild": "rimraf dist",