@eetr/eetr-auth-client 0.2.0 → 0.4.0

package/README.md

@@ -0,0 +1,350 @@
+# @eetr/eetr-auth-client
+
+TypeScript client library for the [eetr-auth](https://github.com/eetr-ai/eetr-auth) OAuth 2.1 / OIDC server.
+
+It wraps the server's token, introspection, UserInfo, admin, and passkey-management
+endpoints, plus helpers for OIDC discovery and JWT verification. Everything is
+`fetch`-based and ships with full type definitions.
+
+## Installation
+
+```bash
+npm install @eetr/eetr-auth-client
+```
+
+```bash
+pnpm add @eetr/eetr-auth-client
+# or
+yarn add @eetr/eetr-auth-client
+```
+
+**Requirements:** Node.js 18+ (the library relies on the global `fetch`; `decodeJwtPayload`
+also uses Node's `Buffer`). `jose` is a runtime dependency used for JWT verification.
+
+The package is ESM-only (`"type": "module"`) and exports both JavaScript and `.d.ts` types.
+
+## Quick start
+
+```ts
+import {
+  fetchOIDCDiscovery,
+  exchangeToken,
+  validateJwt,
+  getUserInfo,
+} from "@eetr/eetr-auth-client";
+
+const ISSUER = "https://auth.example.com";
+
+// 1. Discover endpoints
+const discovery = await fetchOIDCDiscovery(ISSUER);
+
+// 2. Exchange an authorization code for tokens (PKCE)
+const tokens = await exchangeToken(
+  {
+    grantType: "authorization_code",
+    clientId: "my-client",
+    code: authorizationCode,
+    redirectUri: "https://app.example.com/callback",
+    codeVerifier,
+  },
+  { tokenEndpoint: discovery.token_endpoint }
+);
+
+// 3. Verify the access/ID token against the server's JWKS
+const payload = await validateJwt(tokens.access_token, discovery.jwks_uri, {
+  issuer: ISSUER,
+  audience: "my-client",
+});
+
+// 4. Fetch the user's profile
+const user = await getUserInfo(tokens.access_token, discovery.userinfo_endpoint);
+```
+
+## API reference
+
+### Discovery
+
+```ts
+fetchOIDCDiscovery(issuerUrl: string): Promise<OIDCDiscovery>
+fetchOAuthMetadata(issuerUrl: string): Promise<OAuthServerMetadata>
+```
+
+Fetch the server's `/.well-known/openid-configuration` or
+`/.well-known/oauth-authorization-server` metadata. Use the returned
+`token_endpoint`, `jwks_uri`, `userinfo_endpoint`, etc. to configure the rest of
+the client rather than hard-coding paths.
+
+### Authorization URL
+
+```ts
+buildAuthorizationUrl(authorizationEndpoint: string, params: AuthorizationUrlParams): string
+```
+
+Builds the authorization-request URL for the `authorization_code` + PKCE flow.
+`code_challenge` is required (the server only accepts `S256`). Pass `nonce` to
+request an OIDC `nonce` that the server binds into the issued `id_token`, then
+verify it on the returned token with [`validateIdToken`](#jwt-verification).
+
+```ts
+const url = buildAuthorizationUrl(discovery.authorization_endpoint, {
+  clientId: "my-client",
+  redirectUri: "https://app.example.com/callback",
+  codeChallenge,            // base64url SHA-256 of your PKCE verifier
+  scope: "openid profile email",
+  state,
+  nonce,
+});
+```
+
+Prefer the `OIDCScope` constants and the `scopes` array so a typo can't silently
+drop `openid` (which would make `/userinfo` return `403 insufficient_scope`). `scope`
+and `scopes` are merged and de-duplicated, so either or both work:
+
+```ts
+import { OIDCScope, STANDARD_OIDC_SCOPES } from "@eetr/eetr-auth-client";
+
+const url = buildAuthorizationUrl(discovery.authorization_endpoint, {
+  clientId: "my-client",
+  redirectUri: "https://app.example.com/callback",
+  codeChallenge,
+  scopes: [OIDCScope.OpenId, OIDCScope.Profile, OIDCScope.Email], // or STANDARD_OIDC_SCOPES
+  state,
+  nonce,
+});
+```
+
+> The client must be **granted** these scopes by an admin, and `openid`/`profile`/`email`
+> are seeded on the server. Requesting a scope the client wasn't granted fails with
+> `invalid_scope`.
+
+### Token exchange
+
+```ts
+exchangeToken(params: ExchangeTokenParams, config: ExchangeTokenConfig): Promise<TokenResponse>
+```
+
+Performs an OAuth token request. `grantType` is one of `"authorization_code"`,
+`"client_credentials"`, or `"refresh_token"`; supply the fields relevant to the grant.
+When the `openid` scope was granted on an `authorization_code` exchange, the
+`TokenResponse` also includes a signed `id_token`.
+
+```ts
+// Client credentials (machine-to-machine)
+const tokens = await exchangeToken(
+  {
+    grantType: "client_credentials",
+    clientId: "service-a",
+    clientSecret: process.env.CLIENT_SECRET,
+    scope: "admin",
+  },
+  { tokenEndpoint: discovery.token_endpoint }
+);
+```
+
+On a non-2xx response it throws an [`OAuthError`](#error-handling) carrying the
+server's `error` code and `error_description`.
+
+### TokenManager
+
+A small helper that caches an access token and transparently refreshes it (using a
+30-second expiry skew) when a refresh token is available.
+
+```ts
+import { TokenManager } from "@eetr/eetr-auth-client";
+
+const manager = new TokenManager({
+  issuerUrl: ISSUER,
+  clientId: "my-client",
+  clientSecret: process.env.CLIENT_SECRET, // optional for public clients
+  tokenEndpoint: discovery.token_endpoint,
+});
+
+manager.setTokens(tokens);        // seed from an initial exchange
+const accessToken = await manager.getAccessToken(); // refreshes if expired
+```
+
+`getAccessToken()` throws an `OAuthError` with code `no_token` if there is no valid
+token and no refresh token to fall back on.
+
+### JWT verification
+
+```ts
+validateJwt(token: string, jwksUri: string, options?: ValidateJwtOptions): Promise<JWTPayload>
+validateIdToken(token: string, jwksUri: string, options?: ValidateIdTokenOptions): Promise<IDTokenClaims>
+decodeJwtPayload(token: string): JWTPayload
+```
+
+`validateJwt` verifies the signature against the server's JWKS (remote keys are
+cached per `jwksUri`) and validates `issuer`/`audience`/expiry (`clockTolerance`
+defaults to 5 seconds). `decodeJwtPayload` decodes the payload **without** verifying
+the signature — use it only for inspecting claims you have already verified.
+
+```ts
+const payload = await validateJwt(accessToken, discovery.jwks_uri, {
+  issuer: ISSUER,
+  audience: "my-client",
+  clockTolerance: 10,
+});
+```
+
+`validateIdToken` verifies an OIDC `id_token` the same way and, when you pass the
+`nonce` you sent to the authorization endpoint, additionally checks the token's
+`nonce` claim — throwing `id_token nonce mismatch` on a mismatch. It returns the
+typed `IDTokenClaims` (`sub`, `auth_time`, `nonce`, `at_hash`, plus scope-gated
+`name`/`preferred_username`/`picture`/`email`/`email_verified`).
+
+```ts
+const claims = await validateIdToken(tokens.id_token!, discovery.jwks_uri, {
+  issuer: ISSUER,
+  audience: "my-client",
+  nonce, // the value passed to buildAuthorizationUrl
+});
+```
+
+### Token introspection
+
+```ts
+introspectToken(params: IntrospectTokenParams, config: IntrospectTokenConfig): Promise<TokenValidationResponse>
+```
+
+Asks the server whether a token is active within a given environment. The endpoint
+is published as `token_introspection_endpoint` in the OAuth metadata (defaults to
+`${ISSUER}/api/token/validate`).
+
+```ts
+const metadata = await fetchOAuthMetadata(ISSUER);
+
+const result = await introspectToken(
+  { token: accessToken, scopes: ["read"], environmentName: "production" },
+  { introspectionEndpoint: metadata.token_introspection_endpoint! }
+);
+// → { valid, active, client_id, expires_at }
+```
+
+### UserInfo
+
+```ts
+getUserInfo(accessToken: string, userInfoEndpoint: string): Promise<UserInfoResponse>
+```
+
+Returns the OIDC UserInfo claims for the bearer token. The endpoint **requires the
+`openid` scope**; only `sub` is always present, and the remaining claims are gated by
+scope (`profile` → `name`/`preferred_username`/`picture`, `email` →
+`email`/`email_verified`).
+
+On failure it throws an [`OAuthError`](#error-handling). A token that is valid but
+lacks `openid` yields a `403`, surfaced as `code === "insufficient_scope"` (use
+`err.isInsufficientScope`) so you can re-authorize with the right scopes rather than
+discarding the token:
+
+```ts
+try {
+  const info = await getUserInfo(accessToken, discovery.userinfo_endpoint);
+} catch (err) {
+  if (err instanceof OAuthError && err.isInsufficientScope) {
+    // token is fine but missing `openid` — restart the dance requesting it
+  }
+}
+```
+
+#### Normalized profile
+
+```ts
+toUserProfile(userInfo: UserInfoResponse, idTokenClaims?: IDTokenClaims): UserProfile
+```
+
+Merges the UserInfo response (and optionally the decoded `id_token` claims) into a
+single camelCased `UserProfile` (`sub`, `name`, `preferredUsername`, `picture`,
+`email`, `emailVerified`). UserInfo wins; the id_token fills any gap.
+
+```ts
+const info = await getUserInfo(tokens.access_token, discovery.userinfo_endpoint);
+const profile = toUserProfile(info, decodeJwtPayload(tokens.id_token!));
+// → { sub, name?, preferredUsername?, picture?, email?, emailVerified? }
+```
+
+### Admin API
+
+User management against the server's admin API. Requires an access token from a
+client configured as an **admin API client** on the server.
+
+```ts
+import {
+  getAdminUser,
+  createAdminUser,
+  updateAdminUser,
+  deleteAdminUser,
+} from "@eetr/eetr-auth-client";
+
+const config = { baseUrl: ISSUER, accessToken }; // AdminClientConfig
+
+const created = await createAdminUser(
+  { username: "alice", password: "•••", email: "alice@example.com" },
+  config
+);
+
+await updateAdminUser("alice", { name: "Alice B." }, config);
+const user = await getAdminUser("alice", config); // by username or UUID
+await deleteAdminUser(created.id, config);
+```
+
+All admin calls throw `OAuthError` on non-2xx responses.
+
+### Passkey management
+
+List, rename, and remove a user's passkeys. The access token must belong to the
+user whose passkeys are being managed.
+
+```ts
+import { listPasskeys, renamePasskey, removePasskey } from "@eetr/eetr-auth-client";
+
+const config = { baseUrl: ISSUER, accessToken }; // UserClientConfig
+
+const passkeys = await listPasskeys(config);
+await renamePasskey(passkeys[0].id, "Work laptop", config);
+await removePasskey(passkeys[0].id, config);
+```
+
+> Only passkey *management* is available here. Creating or authenticating with a
+> passkey is a WebAuthn ceremony that requires a browser and cannot be driven from a
+> server-side client. `removePasskey` deletes the server-side record only — it does
+> not remove the credential from the device/authenticator.
+
+## Error handling
+
+API helpers throw `OAuthError` (a subclass of `Error`) on non-2xx responses, exposing
+the server's machine-readable `code` alongside the message:
+
+```ts
+import { OAuthError } from "@eetr/eetr-auth-client";
+
+try {
+  await exchangeToken(params, config);
+} catch (err) {
+  if (err instanceof OAuthError) {
+    console.error(err.code, err.message); // e.g. "invalid_grant"
+  }
+}
+```
+
+`OAuthError` also exposes the HTTP `status` and the server's `description`
+(`error_description`) when available, plus an `isInsufficientScope` convenience for
+the `/userinfo` 403 case (token valid but missing `openid`).
+
+The discovery helpers throw a plain `Error` with the HTTP status on failure.
+
+## Types
+
+The package exports TypeScript types for every request and response shape, including
+`TokenResponse`, `UserInfoResponse`, `UserProfile`, `IDTokenClaims`, `OIDCDiscovery`,
+`OAuthServerMetadata`, `AuthClientConfig`, `JWTPayload`, `TokenValidationResponse`,
+`GrantType`, `ExchangeTokenParams`/`Config`, `AuthorizationUrlParams`,
+`IntrospectTokenParams`/`Config`, `OIDCScopeValue`, `ValidateJwtOptions`,
+`ValidateIdTokenOptions`, `AdminUserRecord`, `AdminClientConfig`, `CreateUserParams`,
+`UpdateUserParams`, `PasskeySummary`, and `UserClientConfig`. It also exports the
+`OIDCScope` / `STANDARD_OIDC_SCOPES` constants, the `resolveScopeParam` helper, and
+the `toUserProfile` profile normalizer.
+
+## License
+
+See the [eetr-auth repository](https://github.com/eetr-ai/eetr-auth).

package/dist/api.d.ts

@@ -1,14 +1,54 @@
 import type { TokenResponse, UserInfoResponse, TokenValidationResponse } from "./types.js";
 export declare class OAuthError extends Error {
     readonly code: string;
-    constructor(code: string, message: string);
+    /** HTTP status of the failed response, when the error came from one. */
+    readonly status?: number | undefined;
+    /** The server's `error_description`, when present. */
+    readonly description?: string | undefined;
+    constructor(code: string, message: string, 
+    /** HTTP status of the failed response, when the error came from one. */
+    status?: number | undefined, 
+    /** The server's `error_description`, when present. */
+    description?: string | undefined);
+    /**
+     * True when the access token was valid but lacked a required scope (HTTP 403
+     * `insufficient_scope`) — e.g. calling `/userinfo` with a token that was not
+     * granted `openid`. Re-authorize requesting the missing scope rather than
+     * treating the token as invalid.
+     */
+    get isInsufficientScope(): boolean;
 }
 export type GrantType = "authorization_code" | "client_credentials" | "refresh_token";
+export interface AuthorizationUrlParams {
+    clientId: string;
+    redirectUri: string;
+    /** PKCE S256 challenge (required by this server). */
+    codeChallenge: string;
+    /** Space-delimited scope string. Merged with `scopes` if both are given. */
+    scope?: string;
+    /**
+     * Scopes as an array (e.g. `[OIDCScope.OpenId, OIDCScope.Profile]`). Merged
+     * with `scope`, de-duplicated. Prefer this with the `OIDCScope` constants so
+     * `openid` can't be dropped by a typo.
+     */
+    scopes?: readonly string[];
+    state?: string;
+    /** OIDC nonce, bound into the issued id_token for replay protection. */
+    nonce?: string;
+}
+/**
+ * Build an authorization-request URL for the authorization_code + PKCE flow.
+ * Includes the OIDC `nonce` when provided so it is bound into the id_token.
+ */
+export declare function buildAuthorizationUrl(authorizationEndpoint: string, params: AuthorizationUrlParams): string;
 export interface ExchangeTokenParams {
     grantType: GrantType;
     clientId: string;
     clientSecret?: string;
+    /** Space-delimited scope string. Merged with `scopes` if both are given. */
     scope?: string;
+    /** Scopes as an array (e.g. with the `OIDCScope` constants). Merged with `scope`. */
+    scopes?: readonly string[];
     code?: string;
     redirectUri?: string;
     codeVerifier?: string;
@@ -22,6 +62,13 @@ export interface IntrospectTokenParams {
     token: string;
     scopes?: string[];
     environmentName: string;
+    /**
+     * Optional audience binding. When set to the calling resource server's own
+     * client_id, the token is only reported valid if it was issued to that client —
+     * preventing a token minted for a sibling client in the same environment from
+     * being accepted here. Omit to keep the previous (audience-agnostic) behavior.
+     */
+    clientId?: string;
 }
 export interface IntrospectTokenConfig {
     introspectionEndpoint: string;

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE3F,qBAAa,UAAW,SAAQ,KAAK;aAEjB,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,MAAM,SAAS,GAAG,oBAAoB,GAAG,oBAAoB,GAAG,eAAe,CAAC;AAEtF,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,aAAa,CAAC,CA2BxB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CAWlC;AAED,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAY3B"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAG3F,qBAAa,UAAW,SAAQ,KAAK;aAEjB,IAAI,EAAE,MAAM;IAE5B,wEAAwE;aACxD,MAAM,CAAC,EAAE,MAAM;IAC/B,sDAAsD;aACtC,WAAW,CAAC,EAAE,MAAM;gBALpB,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;IACf,wEAAwE;IACxD,MAAM,CAAC,EAAE,MAAM,YAAA;IAC/B,sDAAsD;IACtC,WAAW,CAAC,EAAE,MAAM,YAAA;IAMtC;;;;;OAKG;IACH,IAAI,mBAAmB,IAAI,OAAO,CAEjC;CACF;AAED,MAAM,MAAM,SAAS,GAAG,oBAAoB,GAAG,oBAAoB,GAAG,eAAe,CAAC;AAEtF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,qBAAqB,EAAE,MAAM,EAC7B,MAAM,EAAE,sBAAsB,GAC7B,MAAM,CAYR;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,aAAa,CAAC,CA4BxB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CAYlC;AAED,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAuB3B"}

package/dist/api.js

@@ -1,10 +1,48 @@
+import { resolveScopeParam } from "./scopes.js";
 export class OAuthError extends Error {
     code;
-    constructor(code, message) {
+    status;
+    description;
+    constructor(code, message, 
+    /** HTTP status of the failed response, when the error came from one. */
+    status, 
+    /** The server's `error_description`, when present. */
+    description) {
         super(message);
         this.code = code;
+        this.status = status;
+        this.description = description;
         this.name = "OAuthError";
     }
+    /**
+     * True when the access token was valid but lacked a required scope (HTTP 403
+     * `insufficient_scope`) — e.g. calling `/userinfo` with a token that was not
+     * granted `openid`. Re-authorize requesting the missing scope rather than
+     * treating the token as invalid.
+     */
+    get isInsufficientScope() {
+        return this.code === "insufficient_scope";
+    }
+}
+/**
+ * Build an authorization-request URL for the authorization_code + PKCE flow.
+ * Includes the OIDC `nonce` when provided so it is bound into the id_token.
+ */
+export function buildAuthorizationUrl(authorizationEndpoint, params) {
+    const url = new URL(authorizationEndpoint);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", params.clientId);
+    url.searchParams.set("redirect_uri", params.redirectUri);
+    url.searchParams.set("code_challenge", params.codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    const scope = resolveScopeParam(params.scope, params.scopes);
+    if (scope)
+        url.searchParams.set("scope", scope);
+    if (params.state)
+        url.searchParams.set("state", params.state);
+    if (params.nonce)
+        url.searchParams.set("nonce", params.nonce);
+    return url.toString();
 }
 export async function exchangeToken(params, config) {
     const body = new URLSearchParams();
@@ -12,8 +50,9 @@ export async function exchangeToken(params, config) {
     body.set("client_id", params.clientId);
     if (params.clientSecret)
         body.set("client_secret", params.clientSecret);
-    if (params.scope)
-        body.set("scope", params.scope);
+    const scope = resolveScopeParam(params.scope, params.scopes);
+    if (scope)
+        body.set("scope", scope);
     if (params.code)
         body.set("code", params.code);
     if (params.redirectUri)
@@ -41,6 +80,7 @@ export async function introspectToken(params, config) {
             token: params.token,
             scopes: params.scopes ?? [],
             environmentName: params.environmentName,
+            ...(params.clientId ? { clientId: params.clientId } : {}),
         }),
     });
     return res.json();
@@ -51,7 +91,16 @@ export async function getUserInfo(accessToken, userInfoEndpoint) {
     });
     if (!res.ok) {
         const data = (await res.json().catch(() => ({})));
-        throw new OAuthError(data.error ?? "invalid_token", `UserInfo request failed: ${res.status}`);
+        // A 403 means the token is valid but missing a required scope (`openid`).
+        // Surface it as `insufficient_scope` so callers can re-authorize with the
+        // right scopes instead of discarding the token as invalid. A 401 (or a
+        // non-JSON body) stays `invalid_token`.
+        const code = data.error ?? (res.status === 403 ? "insufficient_scope" : "invalid_token");
+        const message = data.error_description ??
+            (code === "insufficient_scope"
+                ? "UserInfo requires the openid scope on the access token."
+                : `UserInfo request failed: ${res.status}`);
+        throw new OAuthError(code, message, res.status, data.error_description);
     }
     return res.json();
 }

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,10 +1,15 @@
-export type { TokenResponse, UserInfoResponse, OIDCDiscovery, OAuthServerMetadata, AuthClientConfig, JWTPayload, TokenValidationResponse, } from "./types.js";
+export type { TokenResponse, UserInfoResponse, UserProfile, OIDCDiscovery, OAuthServerMetadata, AuthClientConfig, JWTPayload, IDTokenClaims, TokenValidationResponse, } from "./types.js";
+export { OIDCScope, STANDARD_OIDC_SCOPES, resolveScopeParam, } from "./scopes.js";
+export type { OIDCScopeValue } from "./scopes.js";
+export { toUserProfile } from "./profile.js";
 export { fetchOIDCDiscovery, fetchOAuthMetadata } from "./discovery.js";
-export { OAuthError, exchangeToken, introspectToken, getUserInfo, } from "./api.js";
-export type { GrantType, ExchangeTokenParams, ExchangeTokenConfig, IntrospectTokenParams, IntrospectTokenConfig, } from "./api.js";
+export { OAuthError, exchangeToken, introspectToken, getUserInfo, buildAuthorizationUrl, } from "./api.js";
+export type { GrantType, ExchangeTokenParams, ExchangeTokenConfig, IntrospectTokenParams, IntrospectTokenConfig, AuthorizationUrlParams, } from "./api.js";
 export { TokenManager } from "./tokens.js";
-export { validateJwt, decodeJwtPayload } from "./jwt.js";
-export type { ValidateJwtOptions } from "./jwt.js";
+export { validateJwt, validateIdToken, decodeJwtPayload } from "./jwt.js";
+export type { ValidateJwtOptions, ValidateIdTokenOptions } from "./jwt.js";
 export { getAdminUser, createAdminUser, updateAdminUser, deleteAdminUser, } from "./admin.js";
 export type { AdminUserRecord, AdminClientConfig, CreateUserParams, UpdateUserParams, } from "./admin.js";
+export { listPasskeys, renamePasskey, removePasskey } from "./passkeys.js";
+export type { PasskeySummary, UserClientConfig } from "./passkeys.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACV,uBAAuB,GACxB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAExE,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,WAAW,GACZ,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACzD,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD,OAAO,EACL,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,uBAAuB,GACxB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,EACT,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAExE,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,WAAW,EACX,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC1E,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAE3E,OAAO,EACL,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC3E,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -1,6 +1,9 @@
+export { OIDCScope, STANDARD_OIDC_SCOPES, resolveScopeParam, } from "./scopes.js";
+export { toUserProfile } from "./profile.js";
 export { fetchOIDCDiscovery, fetchOAuthMetadata } from "./discovery.js";
-export { OAuthError, exchangeToken, introspectToken, getUserInfo, } from "./api.js";
+export { OAuthError, exchangeToken, introspectToken, getUserInfo, buildAuthorizationUrl, } from "./api.js";
 export { TokenManager } from "./tokens.js";
-export { validateJwt, decodeJwtPayload } from "./jwt.js";
+export { validateJwt, validateIdToken, decodeJwtPayload } from "./jwt.js";
 export { getAdminUser, createAdminUser, updateAdminUser, deleteAdminUser, } from "./admin.js";
+export { listPasskeys, renamePasskey, removePasskey } from "./passkeys.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAExE,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,WAAW,GACZ,MAAM,UAAU,CAAC;AASlB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAGzD,OAAO,EACL,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,SAAS,EACT,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAExE,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,WAAW,EACX,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAUlB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAG1E,OAAO,EACL,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AAQpB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/jwt.d.ts

@@ -1,9 +1,19 @@
-import type { JWTPayload } from "./types.js";
+import type { IDTokenClaims, JWTPayload } from "./types.js";
 export interface ValidateJwtOptions {
     audience?: string | string[];
     issuer?: string;
     clockTolerance?: number;
 }
+export interface ValidateIdTokenOptions extends ValidateJwtOptions {
+    /** When set, the id_token's `nonce` claim must match this value (OIDC replay defense). */
+    nonce?: string;
+}
 export declare function validateJwt(token: string, jwksUri: string, options?: ValidateJwtOptions): Promise<JWTPayload>;
+/**
+ * Verify an OIDC id_token: checks the RS256 signature against the JWKS plus
+ * `iss`/`aud`/`exp` (via {@link validateJwt}), and — when `options.nonce` is
+ * supplied — that the token's `nonce` claim matches, defending against replay.
+ */
+export declare function validateIdToken(token: string, jwksUri: string, options?: ValidateIdTokenOptions): Promise<IDTokenClaims>;
 export declare function decodeJwtPayload(token: string): JWTPayload;
 //# sourceMappingURL=jwt.d.ts.map

package/dist/jwt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../src/jwt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAWD,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,UAAU,CAAC,CAQrB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAQ1D"}
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../src/jwt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAWD,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,UAAU,CAAC,CAQrB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,aAAa,CAAC,CAOxB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAQ1D"}

package/dist/jwt.js

@@ -15,6 +15,19 @@ export async function validateJwt(token, jwksUri, options = {}) {
     });
     return payload;
 }
+/**
+ * Verify an OIDC id_token: checks the RS256 signature against the JWKS plus
+ * `iss`/`aud`/`exp` (via {@link validateJwt}), and — when `options.nonce` is
+ * supplied — that the token's `nonce` claim matches, defending against replay.
+ */
+export async function validateIdToken(token, jwksUri, options = {}) {
+    const { nonce, ...jwtOptions } = options;
+    const payload = (await validateJwt(token, jwksUri, jwtOptions));
+    if (nonce !== undefined && payload.nonce !== nonce) {
+        throw new Error("id_token nonce mismatch");
+    }
+    return payload;
+}
 export function decodeJwtPayload(token) {
     const parts = token.split(".");
     if (parts.length !== 3) {

package/dist/jwt.js.map

@@ -1 +1 @@
-{"version":3,"file":"jwt.js","sourceRoot":"","sources":["../src/jwt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AASrD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAiD,CAAC;AAE3E,SAAS,OAAO,CAAC,OAAe;IAC9B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,kBAAkB,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,SAAS,CAAC,GAAG,CAAC,OAAO,CAAE,CAAC;AACjC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAa,EACb,OAAe,EACf,UAA8B,EAAE;IAEhC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE;QAC/C,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,CAAC;KAC5C,CAAC,CAAC;IACH,OAAO,OAAqB,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAe,CAAC;AACxC,CAAC"}
+{"version":3,"file":"jwt.js","sourceRoot":"","sources":["../src/jwt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAcrD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAiD,CAAC;AAE3E,SAAS,OAAO,CAAC,OAAe;IAC9B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,kBAAkB,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,SAAS,CAAC,GAAG,CAAC,OAAO,CAAE,CAAC;AACjC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAa,EACb,OAAe,EACf,UAA8B,EAAE;IAEhC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE;QAC/C,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,CAAC;KAC5C,CAAC,CAAC;IACH,OAAO,OAAqB,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAa,EACb,OAAe,EACf,UAAkC,EAAE;IAEpC,MAAM,EAAE,KAAK,EAAE,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC;IACzC,MAAM,OAAO,GAAG,CAAC,MAAM,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,CAAkB,CAAC;IACjF,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAe,CAAC;AACxC,CAAC"}

package/dist/passkeys.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Safe, display-only view of a passkey returned by the auth server. Mirrors the
+ * server-side `PasskeySummary` — never includes the public key, counter, or raw
+ * credential id.
+ */
+export interface PasskeySummary {
+    id: string;
+    name: string | null;
+    /** Backed up / synced across devices (e.g. iCloud Keychain, Google Password Manager). */
+    synced: boolean;
+    /** Single-device credential. */
+    deviceBound: boolean;
+    createdAt: string;
+    lastUsedAt: string | null;
+}
+/**
+ * Config for the passkey management endpoints. These are user-scoped: the access
+ * token must belong to the user whose passkeys are being managed.
+ *
+ * Note: only passkey *management* (list/rename/remove) is available here. Creating
+ * or authenticating with a passkey is a WebAuthn ceremony that requires a browser
+ * and cannot be driven by a server-side client.
+ */
+export interface UserClientConfig {
+    baseUrl: string;
+    accessToken: string;
+}
+/**
+ * List the authenticated user's passkeys.
+ */
+export declare function listPasskeys(config: UserClientConfig): Promise<PasskeySummary[]>;
+/**
+ * Rename one of the authenticated user's passkeys. Throws `OAuthError` with code
+ * `not_found` if the passkey does not exist or is not owned by the user.
+ */
+export declare function renamePasskey(id: string, name: string, config: UserClientConfig): Promise<void>;
+/**
+ * Remove one of the authenticated user's passkeys (server-side record only — this
+ * does not delete the credential from the device/authenticator). Throws `OAuthError`
+ * with code `not_found` if the passkey does not exist or is not owned by the user.
+ */
+export declare function removePasskey(id: string, config: UserClientConfig): Promise<void>;
+//# sourceMappingURL=passkeys.d.ts.map

package/dist/passkeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passkeys.d.ts","sourceRoot":"","sources":["../src/passkeys.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,yFAAyF;IACzF,MAAM,EAAE,OAAO,CAAC;IAChB,gCAAgC;IAChC,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAqBD;;GAEG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAStF;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvF"}

package/dist/passkeys.js

@@ -0,0 +1,57 @@
+import { OAuthError } from "./api.js";
+function passkeysUrl(baseUrl, id) {
+    const trimmed = baseUrl.replace(/\/+$/, "");
+    if (id === undefined) {
+        return `${trimmed}/api/users/passkey`;
+    }
+    return `${trimmed}/api/users/passkey/${encodeURIComponent(id)}`;
+}
+async function parseError(res) {
+    const data = (await res.json().catch(() => ({})));
+    return new OAuthError(data.error ?? "server_error", data.error_description ?? `Passkey API request failed: ${res.status}`);
+}
+/**
+ * List the authenticated user's passkeys.
+ */
+export async function listPasskeys(config) {
+    const res = await fetch(passkeysUrl(config.baseUrl), {
+        headers: { Authorization: `Bearer ${config.accessToken}` },
+    });
+    if (!res.ok) {
+        throw await parseError(res);
+    }
+    const data = (await res.json());
+    return data.passkeys;
+}
+/**
+ * Rename one of the authenticated user's passkeys. Throws `OAuthError` with code
+ * `not_found` if the passkey does not exist or is not owned by the user.
+ */
+export async function renamePasskey(id, name, config) {
+    const res = await fetch(passkeysUrl(config.baseUrl, id), {
+        method: "PATCH",
+        headers: {
+            Authorization: `Bearer ${config.accessToken}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ name }),
+    });
+    if (!res.ok) {
+        throw await parseError(res);
+    }
+}
+/**
+ * Remove one of the authenticated user's passkeys (server-side record only — this
+ * does not delete the credential from the device/authenticator). Throws `OAuthError`
+ * with code `not_found` if the passkey does not exist or is not owned by the user.
+ */
+export async function removePasskey(id, config) {
+    const res = await fetch(passkeysUrl(config.baseUrl, id), {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${config.accessToken}` },
+    });
+    if (!res.ok) {
+        throw await parseError(res);
+    }
+}
+//# sourceMappingURL=passkeys.js.map

package/dist/passkeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"passkeys.js","sourceRoot":"","sources":["../src/passkeys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AA+BtC,SAAS,WAAW,CAAC,OAAe,EAAE,EAAW;IAC/C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC5C,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,OAAO,GAAG,OAAO,oBAAoB,CAAC;IACxC,CAAC;IACD,OAAO,GAAG,OAAO,sBAAsB,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC;AAClE,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,GAAa;IACrC,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAG/C,CAAC;IACF,OAAO,IAAI,UAAU,CACnB,IAAI,CAAC,KAAK,IAAI,cAAc,EAC5B,IAAI,CAAC,iBAAiB,IAAI,+BAA+B,GAAG,CAAC,MAAM,EAAE,CACtE,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAwB;IACzD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE;QACnD,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,MAAM,CAAC,WAAW,EAAE,EAAE;KAC3D,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAmC,CAAC;IAClE,OAAO,IAAI,CAAC,QAAQ,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,EAAU,EACV,IAAY,EACZ,MAAwB;IAExB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE;QACvD,MAAM,EAAE,OAAO;QACf,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,MAAM,CAAC,WAAW,EAAE;YAC7C,cAAc,EAAE,kBAAkB;SACnC;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,CAAC;KAC/B,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAAU,EAAE,MAAwB;IACtE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE;QACvD,MAAM,EAAE,QAAQ;QAChB,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,MAAM,CAAC,WAAW,EAAE,EAAE;KAC3D,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC"}

package/dist/profile.d.ts

@@ -0,0 +1,14 @@
+import type { IDTokenClaims, UserInfoResponse, UserProfile } from "./types.js";
+/**
+ * Merge `/userinfo` claims (and optionally id_token claims) into a normalized,
+ * camelCased {@link UserProfile}. UserInfo values take precedence over id_token
+ * values — UserInfo is the authoritative, freshest source — and the id_token
+ * fills any gap for claims `/userinfo` did not return.
+ *
+ * Fields stay optional because the server only returns claims the access token's
+ * scopes allow (`profile` → name/preferredUsername/picture, `email` →
+ * email/emailVerified), so a profile built from an `openid`-only token carries
+ * just `sub`.
+ */
+export declare function toUserProfile(userInfo: UserInfoResponse, idTokenClaims?: IDTokenClaims): UserProfile;
+//# sourceMappingURL=profile.d.ts.map

package/dist/profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../src/profile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,gBAAgB,EAC1B,aAAa,CAAC,EAAE,aAAa,GAC5B,WAAW,CAcb"}

package/dist/profile.js

@@ -0,0 +1,23 @@
+/**
+ * Merge `/userinfo` claims (and optionally id_token claims) into a normalized,
+ * camelCased {@link UserProfile}. UserInfo values take precedence over id_token
+ * values — UserInfo is the authoritative, freshest source — and the id_token
+ * fills any gap for claims `/userinfo` did not return.
+ *
+ * Fields stay optional because the server only returns claims the access token's
+ * scopes allow (`profile` → name/preferredUsername/picture, `email` →
+ * email/emailVerified), so a profile built from an `openid`-only token carries
+ * just `sub`.
+ */
+export function toUserProfile(userInfo, idTokenClaims) {
+    const prefer = (primary, fallback) => primary !== undefined ? primary : fallback;
+    return {
+        sub: userInfo.sub ?? idTokenClaims?.sub ?? "",
+        name: prefer(userInfo.name, idTokenClaims?.name),
+        preferredUsername: prefer(userInfo.preferred_username, idTokenClaims?.preferred_username),
+        picture: prefer(userInfo.picture, idTokenClaims?.picture),
+        email: prefer(userInfo.email, idTokenClaims?.email),
+        emailVerified: prefer(userInfo.email_verified, idTokenClaims?.email_verified),
+    };
+}
+//# sourceMappingURL=profile.js.map

package/dist/profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.js","sourceRoot":"","sources":["../src/profile.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAC3B,QAA0B,EAC1B,aAA6B;IAE7B,MAAM,MAAM,GAAG,CAAI,OAAsB,EAAE,QAAuB,EAAiB,EAAE,CACnF,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC7C,OAAO;QACL,GAAG,EAAE,QAAQ,CAAC,GAAG,IAAI,aAAa,EAAE,GAAG,IAAI,EAAE;QAC7C,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC;QAChD,iBAAiB,EAAE,MAAM,CACvB,QAAQ,CAAC,kBAAkB,EAC3B,aAAa,EAAE,kBAAkB,CAClC;QACD,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC;QACzD,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,CAAC;QACnD,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,cAAc,EAAE,aAAa,EAAE,cAAc,CAAC;KAC9E,CAAC;AACJ,CAAC"}

package/dist/scopes.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Standard OpenID Connect scopes recognized by the eetr-auth server. These are seeded
+ * on install; an admin still grants them to each client. Use them when building an
+ * authorization request or token exchange so a typo can't silently drop `openid` (which
+ * would make `/userinfo` return 403 insufficient_scope).
+ */
+export declare const OIDCScope: {
+    /** Required to mint an id_token and to call the `/userinfo` endpoint. */
+    readonly OpenId: "openid";
+    /** Gates the `name` / `preferred_username` / `picture` claims. */
+    readonly Profile: "profile";
+    /** Gates the `email` / `email_verified` claims. */
+    readonly Email: "email";
+};
+export type OIDCScopeValue = (typeof OIDCScope)[keyof typeof OIDCScope];
+/** The standard OIDC scopes, in canonical order: `openid profile email`. */
+export declare const STANDARD_OIDC_SCOPES: readonly OIDCScopeValue[];
+/**
+ * Merge a free-form `scope` string and/or a `scopes` array into a single
+ * space-delimited scope string, trimmed, de-duplicated, and order-preserving
+ * (the `scope` string first, then `scopes`). Returns `undefined` when neither
+ * yields any scope, so callers can omit the parameter entirely.
+ */
+export declare function resolveScopeParam(scope?: string, scopes?: readonly string[]): string | undefined;
+//# sourceMappingURL=scopes.d.ts.map

package/dist/scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../src/scopes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,SAAS;IACpB,yEAAyE;;IAEzE,kEAAkE;;IAElE,mDAAmD;;CAE3C,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAExE,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,EAAE,SAAS,cAAc,EAIzD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,GAAG,SAAS,CAapB"}

package/dist/scopes.js

@@ -0,0 +1,43 @@
+/**
+ * Standard OpenID Connect scopes recognized by the eetr-auth server. These are seeded
+ * on install; an admin still grants them to each client. Use them when building an
+ * authorization request or token exchange so a typo can't silently drop `openid` (which
+ * would make `/userinfo` return 403 insufficient_scope).
+ */
+export const OIDCScope = {
+    /** Required to mint an id_token and to call the `/userinfo` endpoint. */
+    OpenId: "openid",
+    /** Gates the `name` / `preferred_username` / `picture` claims. */
+    Profile: "profile",
+    /** Gates the `email` / `email_verified` claims. */
+    Email: "email",
+};
+/** The standard OIDC scopes, in canonical order: `openid profile email`. */
+export const STANDARD_OIDC_SCOPES = [
+    OIDCScope.OpenId,
+    OIDCScope.Profile,
+    OIDCScope.Email,
+];
+/**
+ * Merge a free-form `scope` string and/or a `scopes` array into a single
+ * space-delimited scope string, trimmed, de-duplicated, and order-preserving
+ * (the `scope` string first, then `scopes`). Returns `undefined` when neither
+ * yields any scope, so callers can omit the parameter entirely.
+ */
+export function resolveScopeParam(scope, scopes) {
+    const out = [];
+    const seen = new Set();
+    const add = (value) => {
+        const trimmed = value.trim();
+        if (trimmed && !seen.has(trimmed)) {
+            seen.add(trimmed);
+            out.push(trimmed);
+        }
+    };
+    if (scope)
+        scope.split(/\s+/).forEach(add);
+    if (scopes)
+        scopes.forEach(add);
+    return out.length > 0 ? out.join(" ") : undefined;
+}
+//# sourceMappingURL=scopes.js.map

package/dist/scopes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.js","sourceRoot":"","sources":["../src/scopes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,yEAAyE;IACzE,MAAM,EAAE,QAAQ;IAChB,kEAAkE;IAClE,OAAO,EAAE,SAAS;IAClB,mDAAmD;IACnD,KAAK,EAAE,OAAO;CACN,CAAC;AAIX,4EAA4E;AAC5E,MAAM,CAAC,MAAM,oBAAoB,GAA8B;IAC7D,SAAS,CAAC,MAAM;IAChB,SAAS,CAAC,OAAO;IACjB,SAAS,CAAC,KAAK;CAChB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAc,EACd,MAA0B;IAE1B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAG,CAAC,KAAa,EAAE,EAAE;QAC5B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAClC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAClB,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,CAAC;IACH,CAAC,CAAC;IACF,IAAI,KAAK;QAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,MAAM;QAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAChC,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACpD,CAAC"}

package/dist/types.d.ts

@@ -6,6 +6,12 @@ export interface TokenResponse {
     scope?: string;
     id_token?: string;
 }
+/**
+ * UserInfo claims. Only `sub` is always present; the server gates the remaining
+ * claims on the access token's granted scopes — `name`/`preferred_username`/`picture`
+ * require the `profile` scope and `email`/`email_verified` require the `email` scope.
+ * The endpoint itself requires the `openid` scope.
+ */
 export interface UserInfoResponse {
     sub: string;
     name?: string;
@@ -14,6 +20,21 @@ export interface UserInfoResponse {
     picture?: string;
     preferred_username?: string;
 }
+/**
+ * Normalized user profile, merged from the `/userinfo` response and (optionally) the
+ * id_token claims via {@link toUserProfile}. Claim names are camelCased. Every field
+ * except `sub` is optional because the server only returns claims the access token's
+ * scopes allow (`profile` → name/preferredUsername/picture, `email` →
+ * email/emailVerified).
+ */
+export interface UserProfile {
+    sub: string;
+    name?: string;
+    preferredUsername?: string;
+    picture?: string;
+    email?: string;
+    emailVerified?: boolean;
+}
 export interface OIDCDiscovery {
     issuer: string;
     authorization_endpoint: string;
@@ -61,4 +82,16 @@ export interface TokenValidationResponse {
     client_id: string | null;
     expires_at: string | null;
 }
+/** Claims an issued OIDC id_token may carry (OpenID Connect Core 1.0). */
+export interface IDTokenClaims extends JWTPayload {
+    sub?: string;
+    auth_time?: number;
+    nonce?: string;
+    at_hash?: string;
+    name?: string;
+    preferred_username?: string;
+    picture?: string;
+    email?: string;
+    email_verified?: boolean;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB,EAAE,MAAM,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB,EAAE,MAAM,EAAE,CAAC;IACnC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAClC,qCAAqC,EAAE,MAAM,EAAE,CAAC;IAChD,gCAAgC,EAAE,MAAM,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB,EAAE,MAAM,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,wBAAwB,EAAE,MAAM,EAAE,CAAC;IACnC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,gCAAgC,EAAE,MAAM,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eetr/eetr-auth-client",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "TypeScript client library for eetr-auth OAuth 2.1 / OIDC server",
   "type": "module",
   "main": "./dist/index.js",