@udibo/oauth2 0.4.1 → 0.5.1

package/esm/testing/tenant.d.ts

@@ -102,7 +102,7 @@ export interface FakeTenantOptions {
     issuer: string;
 }
 /**
- * A stand-in for a Udibo tenant, for testing an app that signs in against one
+ * A stand-in for a Udibo Identity tenant, for testing an app that signs in against one
  * without running the identity service. It answers the tenant's protocol
  * surface — discovery, authorize, token, introspection, UserInfo, JWKS — the
  * caller's own `GET /api/memberships`, and the two authorization questions,
@@ -124,9 +124,17 @@ export interface FakeTenant {
     addUser(user: FakeTenantUser): Promise<void>;
     /** Adds an organization. Throws on a duplicate id. */
     addOrganization(organization: FakeTenantOrganization): void;
-    /** Makes a person a member of an organization, replacing any earlier membership. */
+    /**
+     * Makes a person a member of an organization, replacing any earlier
+     * membership. Throws when the organization does not exist.
+     */
     addMember(organizationId: string, userId: string, membership?: FakeTenantMembership): void;
-    /** Ends a membership. Credentials issued in that organization stop answering for it. */
+    /**
+     * Ends a membership. From then on introspection and `/api/check` stop
+     * answering for that organization on credentials issued in it, and UserInfo
+     * drops its `org_*` claims; a JWT access token or id_token already minted
+     * keeps its claims until it expires.
+     */
     removeMember(organizationId: string, userId: string): void;
     /** Registers a resource type, so `/api/check` accepts it. */
     registerResourceType(type: string): void;
@@ -134,12 +142,13 @@ export interface FakeTenant {
     grant(grant: FakeTenantGrant): void;
     /**
      * Chooses who the next authorization requests authenticate as, until
-     * called again. With nobody chosen, authorize answers `login_required`.
+     * called again. With nobody chosen, authorize answers `access_denied`.
      */
     signInAs(userId: string | null, signIn?: FakeTenantSignIn): void;
     /**
      * Mints an access token without the browser flow, for testing an API
-     * directly. JWT or opaque as the client is registered.
+     * directly. JWT or opaque as the client is registered. Throws when the
+     * client or user does not exist.
      */
     issueAccessToken(request: FakeTenantTokenRequest): Promise<string>;
 }

package/esm/utils/_buffer.d.ts

@@ -4,7 +4,8 @@
  * @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 declare function toArrayBuffer(bytes: Uint8Array): ArrayBuffer;

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