@udibo/oauth2 0.4.1 → 0.5.0

package/esm/utils/_buffer.js

@@ -4,8 +4,9 @@
  * @module
  */
 /**
- * Copy to a standalone `ArrayBuffer` to satisfy `BufferSource` on runtimes that
- * narrow `Uint8Array<ArrayBufferLike>` away from `ArrayBuffer`.
+ * Copies the viewed bytes into a standalone `ArrayBuffer`, for passing a
+ * `Uint8Array<ArrayBufferLike>` where Web Crypto's `BufferSource` type does not
+ * accept it.
  */
 export function toArrayBuffer(bytes) {
     return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);

package/esm/utils/_timing-safe.d.ts

@@ -1,13 +1,15 @@
 /**
- * Internal constant-time matching shared by the MFA and BFF code paths.
+ * Internal timing-safe matching for secret candidates.
  *
  * @module
  */
 /**
- * Constant-time scan for `target` among `candidates`: every candidate is
- * compared (no early exit), so timing reveals neither whether nor where a
- * match occurred. Returns the index of the *last* matching candidate, or
- * `undefined` when none match — order candidates least- to most-preferred so
- * a duplicate resolves to the preferred entry.
+ * Compares `target` against every candidate with no early exit, so the scan's
+ * duration does not reveal where a match occurred. Each comparison is
+ * {@link timingSafeEqualString}, which returns early on a byte-length mismatch,
+ * so candidates of a different length than `target` are distinguishable by
+ * timing. Returns the index of the *last* matching candidate, or `undefined`
+ * when none match — order candidates least- to most-preferred so a duplicate
+ * resolves to the preferred entry.
  */
 export declare function timingSafeMatchIndex(candidates: string[], target: string): number | undefined;

package/esm/utils/_timing-safe.js

@@ -1,15 +1,17 @@
 /**
- * Internal constant-time matching shared by the MFA and BFF code paths.
+ * Internal timing-safe matching for secret candidates.
  *
  * @module
  */
 import { timingSafeEqualString } from "./crypto.js";
 /**
- * Constant-time scan for `target` among `candidates`: every candidate is
- * compared (no early exit), so timing reveals neither whether nor where a
- * match occurred. Returns the index of the *last* matching candidate, or
- * `undefined` when none match — order candidates least- to most-preferred so
- * a duplicate resolves to the preferred entry.
+ * Compares `target` against every candidate with no early exit, so the scan's
+ * duration does not reveal where a match occurred. Each comparison is
+ * {@link timingSafeEqualString}, which returns early on a byte-length mismatch,
+ * so candidates of a different length than `target` are distinguishable by
+ * timing. Returns the index of the *last* matching candidate, or `undefined`
+ * when none match — order candidates least- to most-preferred so a duplicate
+ * resolves to the preferred entry.
  */
 export function timingSafeMatchIndex(candidates, target) {
     let index;

package/esm/utils/basic-auth.d.ts

@@ -18,9 +18,8 @@ export interface BasicAuth {
  * 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 declare function parseBasicAuth(authorization: string | null): BasicAuth;
@@ -33,18 +32,12 @@ export declare function parseBasicAuth(authorization: string | null): BasicAuth;
  * 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 declare function encodeBasicAuth(clientId: string, clientSecret: string): string;
 /**
- * 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 declare function tryParseBasicAuth(authorization: string | null): BasicAuth | undefined;

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.1",
+  "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",