@ultimat3/auth 27.11.0 → 27.12.0

package/README.md

@@ -253,6 +253,31 @@ to check an id token's signature against, and the token-endpoint TLS exemption b
 caller declares, not one a provider inherits by omission. It refuses a document whose `issuer` is
 not the one asked for, too (OIDC Discovery §4.3).
 
+**Public clients** (`As of 2026-10-18`). `tokenEndpointAuth` on the provider — or on
+`discoverOAuthProvider({ tokenEndpointAuth })`, or per exchange on `credentials` — says how the
+client authenticates at the token endpoint:
+
+| `tokenEndpointAuth` | Secret read from `clientSecretEnv` | Sent |
+|---|---|---|
+| absent / `'client_secret_post'` | required (`X_ENV_MISSING`) | `client_secret` in the form body — the behaviour before the option |
+| `'client_secret_basic'` | required | `Authorization: Basic base64(urlencode(id):urlencode(secret))`; no `client_secret` in the body |
+| `'none'` | not read; a leftover value is ignored | no secret at all — `client_id` and the PKCE `code_verifier` only |
+
+```ts
+import { discoverOAuthProvider, registerOAuthProvider } from '@ultimat3/auth';
+
+registerOAuthProvider(
+  await discoverOAuthProvider({
+    id: 'equipo',
+    issuer: 'https://sso.example.test',
+    tokenEndpointAuth: 'none', // needs EQUIPO_CLIENT_ID only
+  }),
+);
+```
+
+PKCE stays mandatory for all three: for a public client it is the only thing binding the code to
+the browser that started the flow.
+
 **SAML is out of scope and will stay out of scope.** XML-DSig canonicalisation has no Bun native
 and implementing it would mean a real dependency in the primitive vocabulary, which
 [`docs/idea/18-build-vs-wrap.md`](../../docs/idea/18-build-vs-wrap.md) does not permit. The honest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "27.11.0",
+  "version": "27.12.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
   "license": "MIT",
   "type": "module",
@@ -32,8 +32,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "27.11.0",
-    "@ultimat3/db": "27.11.0",
-    "@ultimat3/schema": "27.11.0"
+    "@ultimat3/core": "27.12.0",
+    "@ultimat3/db": "27.12.0",
+    "@ultimat3/schema": "27.12.0"
   }
 }

package/src/index.ts

@@ -175,6 +175,7 @@ export type {
   OAuthProvider,
   OAuthProviderId,
   PkcePair,
+  TokenEndpointAuth,
 } from './oauth';
 export { assertOAuthCallback, beginOAuth, pkcePair } from './oauth';
 export {

package/src/oauth-discovery.ts

@@ -10,7 +10,7 @@ import {
   renderThrowable,
 } from '@ultimat3/core';
 import { isRecord } from './json';
-import type { OAuthProvider } from './oauth';
+import type { OAuthProvider, TokenEndpointAuth } from './oauth';
 import { oauthExchangeFailed } from './oauth-errors';
 import type { OAuthFetch } from './oauth-exchange';
 import { assertFiniteAuthCount } from './policy-numbers';
@@ -36,6 +36,8 @@ export interface DiscoverOAuthProviderInput {
   readonly scopes?: readonly string[] | undefined;
   readonly clientIdEnv?: string | undefined;
   readonly clientSecretEnv?: string | undefined;
+  /** `'none'` for a public client (no secret read, none sent). Absent: `client_secret_post`. */
+  readonly tokenEndpointAuth?: TokenEndpointAuth | undefined;
   /** Injected in tests; production uses the global. */
   readonly fetch?: OAuthFetch | undefined;
   readonly timeoutMs?: number | undefined;
@@ -173,5 +175,8 @@ export async function discoverOAuthProvider(
     usesNonce: true,
     clientIdEnv: input.clientIdEnv ?? `${prefix}_CLIENT_ID`,
     clientSecretEnv: input.clientSecretEnv ?? `${prefix}_CLIENT_SECRET`,
+    ...(input.tokenEndpointAuth === undefined
+      ? {}
+      : { tokenEndpointAuth: input.tokenEndpointAuth }),
   };
 }

package/src/oauth-exchange.ts

@@ -21,6 +21,7 @@ import {
   type OAuthHandshake,
   type OAuthProvider,
   type OAuthProviderId,
+  type TokenEndpointAuth,
 } from './oauth';
 import { oauthExchangeFailed, restartAt } from './oauth-errors';
 import { providerFor } from './oauth-registry';
@@ -41,7 +42,10 @@ const MAX_DETAIL_LENGTH = 200;
 
 export interface OAuthClientCredentials {
   readonly clientId: string;
+  /** `''` for a public client (`tokenEndpointAuth: 'none'`), which sends none. */
   readonly clientSecret: string;
+  /** Overrides the provider's `tokenEndpointAuth` for this exchange. Absent: the provider's. */
+  readonly tokenEndpointAuth?: TokenEndpointAuth | undefined;
 }
 
 export interface OAuthTokens {
@@ -79,12 +83,14 @@ export function oauthCredentials(
   provider: OAuthProviderId,
   env: Readonly<Record<string, string | undefined>> = Bun.env,
 ): OAuthClientCredentials {
-  const { clientIdEnv, clientSecretEnv } = providerFor(provider);
+  const { clientIdEnv, clientSecretEnv, tokenEndpointAuth } = providerFor(provider);
+  const isPublic = tokenEndpointAuth === 'none';
   const clientId = env[clientIdEnv]?.trim() ?? '';
-  const clientSecret = env[clientSecretEnv]?.trim() ?? '';
+  // A public client has no secret to read, and a leftover one in the env is never sent.
+  const clientSecret = isPublic ? '' : (env[clientSecretEnv]?.trim() ?? '');
   const missing = [
     ...(clientId === '' ? [clientIdEnv] : []),
-    ...(clientSecret === '' ? [clientSecretEnv] : []),
+    ...(clientSecret === '' && !isPublic ? [clientSecretEnv] : []),
   ];
   if (missing.length > 0) {
     throw new EnvMissingError({
@@ -93,7 +99,7 @@ export function oauthCredentials(
       meta: { provider, missing },
     });
   }
-  return { clientId, clientSecret };
+  return isPublic ? { clientId, clientSecret, tokenEndpointAuth } : { clientId, clientSecret };
 }
 
 /**
@@ -160,8 +166,11 @@ export async function providerDetail(
 }
 
 function fixForStatus(provider: OAuthProviderId, status: number): string {
-  const { clientIdEnv, clientSecretEnv } = providerFor(provider);
+  const { clientIdEnv, clientSecretEnv, tokenEndpointAuth } = providerFor(provider);
   if (status === 401 || status === 403) {
+    if (tokenEndpointAuth === 'none') {
+      return `set ${clientIdEnv} to the current value in the ${provider} app settings, and confirm the client is registered as public (token_endpoint_auth_method: none)`;
+    }
     return `set ${clientIdEnv} and ${clientSecretEnv} to the current values in the ${provider} app settings`;
   }
   if (status === 400) {
@@ -174,6 +183,7 @@ async function postForm(
   provider: OAuthProviderId,
   body: URLSearchParams,
   options: OAuthExchangeOptions,
+  authorization?: string,
 ): Promise<Record<string, unknown>> {
   const doFetch: OAuthFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
   // Screened OUTSIDE the try below, deliberately: `AbortSignal.timeout(NaN)` throws, and the
@@ -196,6 +206,7 @@ async function postForm(
         Accept: 'application/json',
         'Content-Type': 'application/x-www-form-urlencoded',
         'User-Agent': OAUTH_USER_AGENT,
+        ...(authorization === undefined ? {} : { Authorization: authorization }),
       },
       body: body.toString(),
       signal: AbortSignal.timeout(timeoutMs),
@@ -311,13 +322,20 @@ export async function exchangeOAuthCode(
     code: callback.code,
     redirect_uri: handshake.redirectUri,
     client_id: options.credentials.clientId,
-    client_secret: options.credentials.clientSecret,
   });
+  const auth = options.credentials.tokenEndpointAuth ?? provider.tokenEndpointAuth;
+  // `client_secret_post` (the default) puts the secret in the body; `'none'` sends no secret at
+  // all, and `client_secret_basic` sends it in the header (RFC 6749 §2.3.1).
+  if (auth === undefined || auth === 'client_secret_post') {
+    body.set('client_secret', options.credentials.clientSecret);
+  }
+  const authorization =
+    auth === 'client_secret_basic' ? basicAuthorization(options.credentials) : undefined;
   // Unconditional: PKCE is not provider-dependent, and `OAuthProvider.usesPkce` is the type-level
   // statement of that — there is no configuration in which this line is skipped.
   body.set('code_verifier', handshake.verifier);
 
-  const payload = await postForm(handshake.provider, body, options);
+  const payload = await postForm(handshake.provider, body, options, authorization);
   const accessToken = payload['access_token'];
   if (typeof accessToken !== 'string' || accessToken === '') {
     throw oauthExchangeFailed({
@@ -365,3 +383,9 @@ export async function exchangeOAuthCode(
           }),
   };
 }
+
+/** RFC 6749 §2.3.1: each half form-encoded BEFORE the base64, so a `:` in either survives. */
+function basicAuthorization(credentials: OAuthClientCredentials): string {
+  const encode = (value: string): string => new URLSearchParams({ v: value }).toString().slice(2);
+  return `Basic ${btoa(`${encode(credentials.clientId)}:${encode(credentials.clientSecret)}`)}`;
+}

package/src/oauth.ts

@@ -43,8 +43,19 @@ export interface OAuthProvider {
   readonly usesNonce: boolean;
   readonly clientIdEnv: string;
   readonly clientSecretEnv: string;
+  /**
+   * How this client authenticates at the token endpoint (OIDC Core 9). Absent:
+   * `'client_secret_post'`, the behaviour before the option existed. `'none'` is a PUBLIC client
+   * — no secret is read from `clientSecretEnv` and none is sent; PKCE, mandatory for every
+   * provider, is what binds the code to the browser. `'client_secret_basic'` sends the pair in
+   * `Authorization: Basic` instead of the body.
+   */
+  readonly tokenEndpointAuth?: TokenEndpointAuth | undefined;
 }
 
+/** The three token-endpoint client authentication methods this package speaks. */
+export type TokenEndpointAuth = 'none' | 'client_secret_post' | 'client_secret_basic';
+
 /**
  * Any registered provider's id — `string`, not a closed union, since 1.3.0. The union of three
  * consumer IdPs made an enterprise OP unrepresentable at the type level, which is a constraint no