@udibo/oauth2 0.4.0 → 0.5.0

package/esm/utils/basic-auth.js

@@ -30,9 +30,8 @@ function formUrlDecode(value) {
  * trip. A segment that is not valid percent-encoding is taken verbatim, so a
  * client that sends such characters un-encoded still authenticates.
  *
- * @param authorization The Authorization header value
- * @returns The parsed credentials
- * @throws {InvalidClientError} If the header is missing or malformed
+ * @throws {InvalidClientError} If the header is missing, not `Basic`, not
+ * valid base64, or does not decode to `name:pass` with a non-empty name.
  * @see https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1
  */
 export function parseBasicAuth(authorization) {
@@ -68,21 +67,15 @@ export function parseBasicAuth(authorization) {
  * only of `A-Z`, `a-z`, `0-9`, `-`, `_`, `.` and `*` encode byte-identically to
  * their raw form; every other character, `~` included, is percent-encoded.
  *
- * @param clientId The client ID
- * @param clientSecret The client secret
- * @returns The encoded Authorization header value
+ * @returns The `Basic …` Authorization header value.
  * @see https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1
  */
 export function encodeBasicAuth(clientId, clientSecret) {
     return `Basic ${btoa(`${formUrlEncode(clientId)}:${formUrlEncode(clientSecret)}`)}`;
 }
 /**
- * Tries to parse basic authentication credentials from an Authorization header.
- * Returns undefined if the header is missing or not Basic auth. Decodes both
- * segments the same way {@link parseBasicAuth} does.
- *
- * @param authorization The Authorization header value
- * @returns The parsed credentials or undefined
+ * Non-throwing {@link parseBasicAuth}: returns `undefined` wherever that would
+ * throw — a missing, non-`Basic`, badly encoded or malformed header.
  */
 export function tryParseBasicAuth(authorization) {
     if (!authorization)

package/esm/utils/crypto.d.ts

@@ -70,7 +70,8 @@ export declare function randomToken(bytes?: number): string;
  * secret is persisted (e.g. as a lookup key) — use {@link deriveSealKey} so the
  * sealing key is independent of that stored hash.
  *
- * @throws if the secret has fewer than 16 bytes of entropy (32+ recommended).
+ * @throws {Error} if the secret is shorter than 16 bytes. Length is all that is
+ * checked; supply 32+ bytes of real entropy.
  */
 export declare function deriveAesKey(secret: string | Uint8Array): Promise<CryptoKey>;
 /**

package/esm/utils/crypto.js

@@ -88,7 +88,8 @@ export function randomToken(bytes = 32) {
  * secret is persisted (e.g. as a lookup key) — use {@link deriveSealKey} so the
  * sealing key is independent of that stored hash.
  *
- * @throws if the secret has fewer than 16 bytes of entropy (32+ recommended).
+ * @throws {Error} if the secret is shorter than 16 bytes. Length is all that is
+ * checked; supply 32+ bytes of real entropy.
  */
 export async function deriveAesKey(secret) {
     const raw = toBytes(secret);

package/esm/utils/text.d.ts

@@ -1,24 +1,17 @@
 /**
  * Bounding and flattening for text a remote server chose.
  *
- * Lives in `utils/` rather than beside either caller because both ladders that
- * turn a server's bytes into an error message — the client's `_http.ts` and
- * the connectors' `_token-exchange.ts` — must sanitize identically, and the
- * client cannot reach up into `identity/external/`.
- *
  * @module
  */
 /** Characters of remote-supplied text kept in an error message. */
 export declare const PROVIDER_TEXT_MAX_LENGTH = 200;
 /**
  * Bounds and flattens a remote-supplied string for inclusion in an error
- * message. Control characters become spaces so a hostile `error_description`
+ * message. Each run of C0/C1 control characters becomes one space (and the
+ * result is trimmed) so a hostile `error_description`
  * cannot forge a log line or inject an ANSI escape in a consumer's console,
  * the result is capped at {@link PROVIDER_TEXT_MAX_LENGTH}, and a surrogate
  * pair split by that cap is repaired rather than left lone. Use this on
  * every byte a remote server chose that reaches a message.
- *
- * @param value The remote-supplied text.
- * @returns The flattened, capped, well-formed text.
  */
 export declare function sanitizeProviderText(value: string): string;

package/esm/utils/text.js

@@ -1,25 +1,18 @@
 /**
  * Bounding and flattening for text a remote server chose.
  *
- * Lives in `utils/` rather than beside either caller because both ladders that
- * turn a server's bytes into an error message — the client's `_http.ts` and
- * the connectors' `_token-exchange.ts` — must sanitize identically, and the
- * client cannot reach up into `identity/external/`.
- *
  * @module
  */
 /** Characters of remote-supplied text kept in an error message. */
 export const PROVIDER_TEXT_MAX_LENGTH = 200;
 /**
  * Bounds and flattens a remote-supplied string for inclusion in an error
- * message. Control characters become spaces so a hostile `error_description`
+ * message. Each run of C0/C1 control characters becomes one space (and the
+ * result is trimmed) so a hostile `error_description`
  * cannot forge a log line or inject an ANSI escape in a consumer's console,
  * the result is capped at {@link PROVIDER_TEXT_MAX_LENGTH}, and a surrogate
  * pair split by that cap is repaired rather than left lone. Use this on
  * every byte a remote server chose that reaches a message.
- *
- * @param value The remote-supplied text.
- * @returns The flattened, capped, well-formed text.
  */
 export function sanitizeProviderText(value) {
     // deno-lint-ignore no-control-regex

package/esm/utils/url.d.ts

@@ -38,8 +38,8 @@ export declare function safeReturnTo(value: string | null | undefined, fallback?
 export interface LoginContinuationOptions {
     /**
      * The authorization endpoint (absolute URL or path). When `returnTo` points at
-     * it, the flow is **resumed** (the in-flight authorize request already has a
-     * PKCE `state`). Omit it and every `returnTo` starts a fresh login.
+     * it, the flow is **resumed** (the in-flight authorize request already carries
+     * its `state`). Omit it and every `returnTo` starts a fresh login.
      */
     authorizeEndpoint?: string;
     /** The login path to start a fresh login. Defaults to `"/auth/login"`. */

package/esm/utils/url.js

@@ -79,8 +79,6 @@ export function safeReturnTo(value, fallback = "/") {
 export function loginContinuation(returnTo, options = {}) {
     const safe = safeReturnTo(returnTo, options.defaultReturnTo ?? "/");
     if (options.authorizeEndpoint) {
-        // Compare path only so the in-flight authorize query (client_id, state, …)
-        // is preserved; the base lets absolute and relative inputs both resolve.
         const base = "http://login.continuation.local";
         const authorizePath = new URL(options.authorizeEndpoint, base).pathname;
         if (new URL(safe, base).pathname === authorizePath)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A flexible OAuth2 toolkit: framework-agnostic authorization & resource servers, a typed client, Hono adapters (including a backend-for-frontend), and React bindings.",
   "repository": {
     "type": "git",