@shware/security 4.1.0 → 5.0.0

package/dist/oauth2/types.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.cjs","names":[],"sources":["../../src/oauth2/types.ts"],"sourcesContent":["// reference: https://datatracker.ietf.org/doc/html/rfc7636\nexport interface PkceParameters {\n  code_verifier: string;\n  code_challenge: string;\n  code_challenge_method: 'S256' | 'plain';\n}\n\nexport interface OAuth2AuthorizationRequest {\n  state: string;\n  registrationId: string;\n  authorizationRequestUri: string;\n  additionalParameters: PkceParameters;\n  /**\n   * What the host attached when the flow started (`oauth2Authorization` options), kept on the\n   * server and handed back to `onAuthorized` once the callback checks out. Never sent to the\n   * provider, unlike `additionalParameters`. Absent on requests stored before this field existed.\n   */\n  attributes?: Record<string, string>;\n}\n\ninterface CreateAuthorizationUriParams {\n  state: string;\n  clientId: string;\n  redirectUri: string;\n  scope: string[] | undefined;\n  pkce?: Omit<PkceParameters, 'code_verifier'>;\n}\n\nexport interface ExchangeCodeParams {\n  code: string;\n  clientId: string;\n  clientSecret: string;\n  redirectUri: string;\n  pkce?: Omit<PkceParameters, 'code_challenge' | 'code_challenge_method'>;\n}\n\nexport interface RefreshTokenParams {\n  clientId: string;\n  clientSecret: string;\n  refreshToken: string;\n}\n\nexport interface RevokeTokenParams {\n  token: string;\n  clientId: string;\n  clientSecret: string;\n}\n\nexport interface LoginOAuth2NativeParams {\n  clientId: string;\n  clientSecret: string;\n  redirectUri: string;\n  pkce?: PkceParameters;\n  credentials: NativeCredential;\n}\n\n// reference: https://datatracker.ietf.org/doc/html/rfc6749#section-5.1\nexport interface OAuth2Token {\n  /**\n   * REQUIRED.\n   * The access token issued by the authorization server.\n   */\n  access_token: string;\n\n  /**\n   * REQUIRED.\n   * The type of the token issued as described in Section 7.1.  Value is case insensitive.\n   */\n  token_type: 'Bearer' | 'bearer' | 'mac' | (string & {});\n\n  /**\n   * RECOMMENDED.\n   * The lifetime in seconds of the access token. For example, the value \"3600\" denotes that the\n   * access token will expire in one hour from the time the response was generated. If omitted, the\n   * authorization server SHOULD provide the expiration time via other means or document the default\n   * value.\n   */\n  expires_in?: number;\n\n  /**\n   * OPTIONAL.\n   * The refresh token, which can be used to obtain new access tokens using the same authorization\n   * grant as described in Section 6.\n   */\n  refresh_token?: string;\n\n  /**\n   * OPTIONAL.\n   * If identical to the scope requested by the client; otherwise, REQUIRED. The scope of the\n   * access token as described by Section 3.3.\n   */\n  scope?: string;\n\n  id_token?: string;\n\n  [key: string]: unknown;\n}\n\nexport interface OidcToken extends OAuth2Token {\n  id_token: string;\n}\n\nexport type NativeCredential = {\n  state?: string;\n  code?: string;\n  client_id?: string;\n  redirect_uri?: string;\n  id_token?: string;\n  access_token?: string;\n  /**\n   * The user's name as the platform hands it to the app, for providers whose id token carries none\n   * (Apple sends it on the first authorization only): iOS\n   * `ASAuthorizationAppleIDCredential.fullName`, expo-apple-authentication's `credential.fullName`.\n   * The snake_case fields above are OAuth / OIDC protocol parameters; this one is not, it is the\n   * platform's object passed through unchanged, so it keeps the platform's own name and apps send\n   * `fullName: credential.fullName` as is. Unsigned client input: the provider cleans each part and\n   * ignores anything that is not a string. Parts with a standard claim become `given_name`,\n   * `family_name`, `middle_name` and `nickname`; `namePrefix` / `nameSuffix` have none and are kept\n   * in `userInfo.data.fullName` only.\n   */\n  fullName?: PersonNameComponents;\n};\n\n/** iOS `PersonNameComponents` as JSON; every part may be missing or `null`. */\nexport interface PersonNameComponents {\n  givenName?: string | null;\n  familyName?: string | null;\n  middleName?: string | null;\n  namePrefix?: string | null;\n  nameSuffix?: string | null;\n  nickname?: string | null;\n}\n\n/**\n * Fields of the authorization response besides `code` and `state` that a provider uses to fill in\n * the user info: Apple posts the user's name as `user` (JSON) with the first authorization only,\n * since its id token never carries one. Unsigned, so treated as untrusted input.\n */\nexport interface AuthorizationResponse {\n  user?: string;\n}\n\nexport const OIDC_SCOPES = [\n  'openid',\n  'profile',\n  'email',\n  'phone',\n  'address',\n  'offline_access',\n] as const;\n\nexport type OidcScope = (typeof OIDC_SCOPES)[number];\n\n// https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims\nexport interface StandardClaims {\n  sub: string;\n  name?: string;\n  given_name?: string;\n  family_name?: string;\n  middle_name?: string;\n  nickname?: string;\n  preferred_username?: string;\n  profile?: string;\n  picture?: string;\n  website?: string;\n  email?: string;\n  email_verified?: boolean;\n  gender?: 'female' | 'male' | (string & {});\n  birthdate?: string; // ISO 8601-1 [ISO8601‑1] YYYY-MM-DD format.\n  zoneinfo?: string; // IANA Time Zone Database [IANA.time‑zones]\n  locale?: string; // BCP47 [RFC5646] language tag.\n  phone_number?: string; // E.164\n  phone_number_verified?: boolean;\n  address?: {\n    formatted: string;\n    street_address: string;\n    locality: string;\n    region: string;\n    postal_code: string;\n    country: string;\n  }; // [RFC8259] JSON object\n  updated_at?: number;\n}\n\nexport interface UserInfo<T = unknown> {\n  claims: StandardClaims;\n  data: T;\n}\n\nexport interface Provider {\n  /** Authorization URI for the provider. */\n  authorizationUri: string;\n\n  /** Token URI for the provider. */\n  tokenUri: string;\n\n  /** Token revoke URI for the provider. */\n  tokenRevokeUri?: string;\n\n  /** Token refresh URI for the provider. */\n  tokenRefreshUri?: string;\n\n  /** User info URI for the provider. */\n  userInfoUri?: string;\n\n  /** User info authentication method for the provider. */\n  userInfoAuthenticationMethod?: string;\n\n  /**\n   * Name of the attribute that will be used to extract the username from the call to 'userInfoUri'.\n   * */\n  userNameAttribute?: string;\n\n  /** JWK set URI for the provider */\n  jwkSetUri?: string;\n\n  /**\n   * URI that can either be an OpenID Connect discovery endpoint or an OAuth 2.0 Authorization\n   * Server Metadata endpoint defined by RFC 8414.\n   * */\n  issuerUri?: string;\n\n  /** Default scopes for the provider. */\n  defaultScope: string[];\n\n  /** step 1: generate authorization uri and redirect user to it */\n  createAuthorizationUri: (params: CreateAuthorizationUriParams) => URL;\n\n  /** step 2: exchange code for token */\n  exchangeAuthorizationCode: (params: ExchangeCodeParams) => Promise<OAuth2Token>;\n\n  /**\n   * step 3: get user info; `response` holds what the authorization response carried besides the\n   * code, for the providers that send user data there (Apple).\n   */\n  getUserInfo: (token: OAuth2Token, response?: AuthorizationResponse) => Promise<UserInfo>;\n\n  /** others: refresh access token */\n  refreshAccessToken?: (params: RefreshTokenParams) => Promise<OAuth2Token>;\n\n  /** others: revoke token */\n  revokeToken?: (params: RevokeTokenParams) => Promise<void>;\n\n  loginOAuth2Native?: (\n    params: LoginOAuth2NativeParams\n  ) => Promise<{ token: OAuth2Token; userInfo: UserInfo }>;\n}\n\nexport interface OneTapProvider extends Provider {\n  getTokenInfo: (id_token: string) => Promise<{ token: OAuth2Token; userInfo: UserInfo }>;\n}\n\nexport interface Registration {\n  /**\n   * Reference to the OAuth 2.0 provider to use. May reference an element from the 'provider'\n   * property or used one of the commonly used providers (google, github, facebook, okta).\n   * */\n  provider?: string;\n\n  /** Client ID for the registration. */\n  clientId: string;\n\n  /** Client secret of the registration. */\n  clientSecret: string;\n\n  /** Client authentication method. May be left blank when using a pre-defined provider. */\n  clientAuthenticationMethod?: string;\n\n  /** Authorization grant type. May be left blank when using a pre-defined provider. */\n  authorizationGrantType?:\n    | 'authorization_code' // default\n    | 'client_credentials'\n    | 'device_code'\n    | 'jwt_bearer'\n    // Deprecated. The latest OAuth 2.0 Security Best Current Practice disallows the use of the\n    // Resource Owner Password Credentials grant.\n    | 'password'\n    | 'refresh_token'\n    | 'token_exchange';\n\n  /** Redirect URI. May be left blank when using a pre-defined provider. */\n  redirectUri?: string;\n\n  /** Authorization scopes. When left blank the provider's default scopes, if any, will be used. */\n  scope?: string[];\n\n  /** Client name. May be left blank when using a pre-defined provider. */\n  clientName?: string;\n}\n\nexport interface OAuth2ClientConfig {\n  baseUri: string;\n  errorUri: string;\n  successUri: string;\n  provider: { [name: string]: Provider | undefined };\n  registration:\n    | { [name: string]: Registration | undefined }\n    | (() => Promise<{ [name: string]: Registration | undefined }>);\n}\n"],"mappings":";;AA8IA,MAAa,cAAc;CACzB;CACA;CACA;CACA;CACA;CACA;AACF"}
+{"version":3,"file":"types.cjs","names":[],"sources":["../../src/oauth2/types.ts"],"sourcesContent":["// reference: https://datatracker.ietf.org/doc/html/rfc7636\nexport interface PkceParameters {\n  code_verifier: string;\n  code_challenge: string;\n  code_challenge_method: 'S256' | 'plain';\n}\n\nexport interface OAuth2AuthorizationRequest {\n  state: string;\n  /** Key of the provider in `OAuth2ClientConfig.providers` the flow was started for. */\n  provider: string;\n  authorizationRequestUri: string;\n  additionalParameters: PkceParameters;\n  /**\n   * What the host attached when the flow started (`oauth2Authorization` options), kept on the\n   * server and handed back to `onAuthorized` once the callback checks out. Never sent to the\n   * provider, unlike `additionalParameters`. Absent on requests stored before this field existed.\n   */\n  attributes?: Record<string, string>;\n}\n\ninterface CreateAuthorizationUriParams {\n  state: string;\n  clientId: string;\n  redirectUri: string;\n  scope: string[] | undefined;\n  pkce?: Omit<PkceParameters, 'code_verifier'>;\n}\n\nexport interface ExchangeCodeParams {\n  code: string;\n  clientId: string;\n  /** Absent for public clients (Google's installed-app clients, PKCE-only clients). */\n  clientSecret?: string;\n  redirectUri: string;\n  pkce?: Omit<PkceParameters, 'code_challenge' | 'code_challenge_method'>;\n}\n\nexport interface RefreshTokenParams {\n  clientId: string;\n  clientSecret?: string;\n  refreshToken: string;\n}\n\nexport interface RevokeTokenParams {\n  token: string;\n  clientId: string;\n  clientSecret?: string;\n}\n\nexport interface LoginOAuth2NativeParams {\n  /**\n   * The configured client the app signs in as (its `client_id`, or the provider's default native\n   * client). Id tokens must be issued to it: it is the only audience accepted.\n   */\n  clientId: string;\n  clientSecret?: string;\n  redirectUri: string;\n  pkce?: PkceParameters;\n  credentials: NativeCredential;\n}\n\n// reference: https://datatracker.ietf.org/doc/html/rfc6749#section-5.1\nexport interface OAuth2Token {\n  /**\n   * REQUIRED.\n   * The access token issued by the authorization server.\n   */\n  access_token: string;\n\n  /**\n   * REQUIRED.\n   * The type of the token issued as described in Section 7.1.  Value is case insensitive.\n   */\n  token_type: 'Bearer' | 'bearer' | 'mac' | (string & {});\n\n  /**\n   * RECOMMENDED.\n   * The lifetime in seconds of the access token. For example, the value \"3600\" denotes that the\n   * access token will expire in one hour from the time the response was generated. If omitted, the\n   * authorization server SHOULD provide the expiration time via other means or document the default\n   * value.\n   */\n  expires_in?: number;\n\n  /**\n   * OPTIONAL.\n   * The refresh token, which can be used to obtain new access tokens using the same authorization\n   * grant as described in Section 6.\n   */\n  refresh_token?: string;\n\n  /**\n   * OPTIONAL.\n   * If identical to the scope requested by the client; otherwise, REQUIRED. The scope of the\n   * access token as described by Section 3.3.\n   */\n  scope?: string;\n\n  id_token?: string;\n\n  [key: string]: unknown;\n}\n\nexport interface OidcToken extends OAuth2Token {\n  id_token: string;\n}\n\nexport type NativeCredential = {\n  state?: string;\n  code?: string;\n  client_id?: string;\n  redirect_uri?: string;\n  id_token?: string;\n  access_token?: string;\n  /**\n   * The user's name as the platform hands it to the app, for providers whose id token carries none\n   * (Apple sends it on the first authorization only): iOS\n   * `ASAuthorizationAppleIDCredential.fullName`, expo-apple-authentication's `credential.fullName`.\n   * The snake_case fields above are OAuth / OIDC protocol parameters; this one is not, it is the\n   * platform's object passed through unchanged, so it keeps the platform's own name and apps send\n   * `fullName: credential.fullName` as is. Unsigned client input: the provider cleans each part and\n   * ignores anything that is not a string. Parts with a standard claim become `given_name`,\n   * `family_name`, `middle_name` and `nickname`; `namePrefix` / `nameSuffix` have none and are kept\n   * in `userInfo.data.fullName` only.\n   */\n  fullName?: PersonNameComponents;\n};\n\n/** iOS `PersonNameComponents` as JSON; every part may be missing or `null`. */\nexport interface PersonNameComponents {\n  givenName?: string | null;\n  familyName?: string | null;\n  middleName?: string | null;\n  namePrefix?: string | null;\n  nameSuffix?: string | null;\n  nickname?: string | null;\n}\n\n/**\n * Fields of the authorization response besides `code` and `state` that a provider uses to fill in\n * the user info: Apple posts the user's name as `user` (JSON) with the first authorization only,\n * since its id token never carries one. Unsigned, so treated as untrusted input.\n */\nexport interface AuthorizationResponse {\n  user?: string;\n}\n\nexport const OIDC_SCOPES = [\n  'openid',\n  'profile',\n  'email',\n  'phone',\n  'address',\n  'offline_access',\n] as const;\n\nexport type OidcScope = (typeof OIDC_SCOPES)[number];\n\n// https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims\nexport interface StandardClaims {\n  sub: string;\n  name?: string;\n  given_name?: string;\n  family_name?: string;\n  middle_name?: string;\n  nickname?: string;\n  preferred_username?: string;\n  profile?: string;\n  picture?: string;\n  website?: string;\n  email?: string;\n  email_verified?: boolean;\n  gender?: 'female' | 'male' | (string & {});\n  birthdate?: string; // ISO 8601-1 [ISO8601‑1] YYYY-MM-DD format.\n  zoneinfo?: string; // IANA Time Zone Database [IANA.time‑zones]\n  locale?: string; // BCP47 [RFC5646] language tag.\n  phone_number?: string; // E.164\n  phone_number_verified?: boolean;\n  address?: {\n    formatted: string;\n    street_address: string;\n    locality: string;\n    region: string;\n    postal_code: string;\n    country: string;\n  }; // [RFC8259] JSON object\n  updated_at?: number;\n}\n\nexport interface UserInfo<T = unknown> {\n  claims: StandardClaims;\n  data: T;\n}\n\nexport interface Provider {\n  /** Authorization URI for the provider. */\n  authorizationUri: string;\n\n  /** Token URI for the provider. */\n  tokenUri: string;\n\n  /** Token revoke URI for the provider. */\n  tokenRevokeUri?: string;\n\n  /** Token refresh URI for the provider. */\n  tokenRefreshUri?: string;\n\n  /** User info URI for the provider. */\n  userInfoUri?: string;\n\n  /** User info authentication method for the provider. */\n  userInfoAuthenticationMethod?: string;\n\n  /**\n   * Name of the attribute that will be used to extract the username from the call to 'userInfoUri'.\n   * */\n  userNameAttribute?: string;\n\n  /** JWK set URI for the provider */\n  jwkSetUri?: string;\n\n  /**\n   * URI that can either be an OpenID Connect discovery endpoint or an OAuth 2.0 Authorization\n   * Server Metadata endpoint defined by RFC 8414.\n   * */\n  issuerUri?: string;\n\n  /** Default scopes for the provider. */\n  defaultScope: string[];\n\n  /** step 1: generate authorization uri and redirect user to it */\n  createAuthorizationUri: (params: CreateAuthorizationUriParams) => URL;\n\n  /** step 2: exchange code for token */\n  exchangeAuthorizationCode: (params: ExchangeCodeParams) => Promise<OAuth2Token>;\n\n  /**\n   * step 3: get user info. `context.clientId` is the client the token was issued to, the only\n   * audience an id token may carry; `context.response` holds what the authorization response\n   * carried besides the code, for the providers that send user data there (Apple).\n   */\n  getUserInfo: (token: OAuth2Token, context: UserInfoContext) => Promise<UserInfo>;\n\n  /** others: refresh access token */\n  refreshAccessToken?: (params: RefreshTokenParams) => Promise<OAuth2Token>;\n\n  /** others: revoke token */\n  revokeToken?: (params: RevokeTokenParams) => Promise<void>;\n\n  loginOAuth2Native?: (\n    params: LoginOAuth2NativeParams\n  ) => Promise<{ token: OAuth2Token; userInfo: UserInfo }>;\n}\n\nexport interface UserInfoContext {\n  clientId: string;\n  response?: AuthorizationResponse;\n}\n\nexport interface OneTapProvider extends Provider {\n  /** Verifies a One Tap / FedCM credential, which must be issued to `clientId` (the web client). */\n  getTokenInfo: (\n    id_token: string,\n    clientId: string\n  ) => Promise<{ token: OAuth2Token; userInfo: UserInfo }>;\n}\n\n/**\n * A client secret: a fixed string, or a function minting one for the client id it is called with\n * (Sign in with Apple's signed JWT, see `createAppleClientSecret`), called on every use so it can\n * cache and renew on its own.\n */\nexport type ClientSecret = string | ((clientId: string) => string | Promise<string>);\n\n/** The client a provider's server-side flows sign in as: the redirect flow and Google One Tap. */\nexport interface WebClient {\n  clientId: string;\n  /** Absent for a public client. */\n  clientSecret?: ClientSecret;\n  /** Default: `${baseUri}/login/oauth2/code/<provider key>`. */\n  redirectUri?: string;\n  /** Authorization scopes. Default: the provider's `defaultScope`. */\n  scope?: string[];\n}\n\n/**\n * A client an app signs in as on the device (an iOS bundle id, a Google iOS / Android client) and\n * whose code or id token it posts to the native login route.\n */\nexport interface NativeClient {\n  clientId: string;\n  /** Absent for a public client (Google's installed-app clients have none). */\n  clientSecret?: ClientSecret;\n  /**\n   * Redirect URI sent with the code exchange when the app sends no `redirect_uri` of its own.\n   * Default: `${baseUri}/login/oauth2/code/<provider key>`.\n   */\n  redirectUri?: string;\n}\n\n/**\n * One identity source: every user it signs in has a `sub` unique within it, whichever client they\n * came through. The key in `OAuth2ClientConfig.providers` names it in the routes and in\n * `onAuthorized`. Two keys may share an implementation (two Google Cloud projects, one Okta per\n * tenant) when their subjects are separate namespaces.\n */\nexport interface ProviderConfig {\n  /** The implementation: `apple`, `google`, `github`, ... from `@shware/security/oauth2/provider`. */\n  provider: Provider;\n  /** The redirect flow's and One Tap's client. Required by those flows. */\n  web?: WebClient;\n  /**\n   * Clients the native login accepts besides `web`. An app names its client with `client_id`;\n   * without one, the only native client is used, or `web` when there is none.\n   */\n  native?: NativeClient[];\n}\n\nexport type ProvidersConfig = { [key: string]: ProviderConfig | undefined };\n\nexport interface OAuth2ClientConfig {\n  baseUri: string;\n  errorUri: string;\n  successUri: string;\n  /** Providers by key; a function is called per request, for secrets read at request time. */\n  providers: ProvidersConfig | (() => Promise<ProvidersConfig>);\n}\n"],"mappings":";;AAoJA,MAAa,cAAc;CACzB;CACA;CACA;CACA;CACA;CACA;AACF"}

package/dist/oauth2/types.d.cts

@@ -6,7 +6,8 @@ export interface PkceParameters {
 }
 export interface OAuth2AuthorizationRequest {
   state: string;
-  registrationId: string;
+  /** Key of the provider in `OAuth2ClientConfig.providers` the flow was started for. */
+  provider: string;
   authorizationRequestUri: string;
   additionalParameters: PkceParameters;
   /**
@@ -26,23 +27,28 @@ interface CreateAuthorizationUriParams {
 export interface ExchangeCodeParams {
   code: string;
   clientId: string;
-  clientSecret: string;
+  /** Absent for public clients (Google's installed-app clients, PKCE-only clients). */
+  clientSecret?: string;
   redirectUri: string;
   pkce?: Omit<PkceParameters, 'code_challenge' | 'code_challenge_method'>;
 }
 export interface RefreshTokenParams {
   clientId: string;
-  clientSecret: string;
+  clientSecret?: string;
   refreshToken: string;
 }
 export interface RevokeTokenParams {
   token: string;
   clientId: string;
-  clientSecret: string;
+  clientSecret?: string;
 }
 export interface LoginOAuth2NativeParams {
+  /**
+   * The configured client the app signs in as (its `client_id`, or the provider's default native
+   * client). Id tokens must be issued to it: it is the only audience accepted.
+   */
   clientId: string;
-  clientSecret: string;
+  clientSecret?: string;
   redirectUri: string;
   pkce?: PkceParameters;
   credentials: NativeCredential;
@@ -187,10 +193,11 @@ export interface Provider {
   /** step 2: exchange code for token */
   exchangeAuthorizationCode: (params: ExchangeCodeParams) => Promise<OAuth2Token>;
   /**
-   * step 3: get user info; `response` holds what the authorization response carried besides the
-   * code, for the providers that send user data there (Apple).
+   * step 3: get user info. `context.clientId` is the client the token was issued to, the only
+   * audience an id token may carry; `context.response` holds what the authorization response
+   * carried besides the code, for the providers that send user data there (Apple).
    */
-  getUserInfo: (token: OAuth2Token, response?: AuthorizationResponse) => Promise<UserInfo>;
+  getUserInfo: (token: OAuth2Token, context: UserInfoContext) => Promise<UserInfo>;
   /** others: refresh access token */
   refreshAccessToken?: (params: RefreshTokenParams) => Promise<OAuth2Token>;
   /** others: revoke token */
@@ -200,45 +207,73 @@ export interface Provider {
     userInfo: UserInfo;
   }>;
 }
+export interface UserInfoContext {
+  clientId: string;
+  response?: AuthorizationResponse;
+}
 export interface OneTapProvider extends Provider {
-  getTokenInfo: (id_token: string) => Promise<{
+  /** Verifies a One Tap / FedCM credential, which must be issued to `clientId` (the web client). */
+  getTokenInfo: (id_token: string, clientId: string) => Promise<{
     token: OAuth2Token;
     userInfo: UserInfo;
   }>;
 }
-export interface Registration {
-  /**
-   * Reference to the OAuth 2.0 provider to use. May reference an element from the 'provider'
-   * property or used one of the commonly used providers (google, github, facebook, okta).
-   * */
-  provider?: string;
-  /** Client ID for the registration. */
+/**
+ * A client secret: a fixed string, or a function minting one for the client id it is called with
+ * (Sign in with Apple's signed JWT, see `createAppleClientSecret`), called on every use so it can
+ * cache and renew on its own.
+ */
+export type ClientSecret = string | ((clientId: string) => string | Promise<string>);
+/** The client a provider's server-side flows sign in as: the redirect flow and Google One Tap. */
+export interface WebClient {
   clientId: string;
-  /** Client secret of the registration. */
-  clientSecret: string;
-  /** Client authentication method. May be left blank when using a pre-defined provider. */
-  clientAuthenticationMethod?: string;
-  /** Authorization grant type. May be left blank when using a pre-defined provider. */
-  authorizationGrantType?: 'authorization_code' | 'client_credentials' | 'device_code' | 'jwt_bearer' | 'password' | 'refresh_token' | 'token_exchange';
-  /** Redirect URI. May be left blank when using a pre-defined provider. */
+  /** Absent for a public client. */
+  clientSecret?: ClientSecret;
+  /** Default: `${baseUri}/login/oauth2/code/<provider key>`. */
   redirectUri?: string;
-  /** Authorization scopes. When left blank the provider's default scopes, if any, will be used. */
+  /** Authorization scopes. Default: the provider's `defaultScope`. */
   scope?: string[];
-  /** Client name. May be left blank when using a pre-defined provider. */
-  clientName?: string;
 }
+/**
+ * A client an app signs in as on the device (an iOS bundle id, a Google iOS / Android client) and
+ * whose code or id token it posts to the native login route.
+ */
+export interface NativeClient {
+  clientId: string;
+  /** Absent for a public client (Google's installed-app clients have none). */
+  clientSecret?: ClientSecret;
+  /**
+   * Redirect URI sent with the code exchange when the app sends no `redirect_uri` of its own.
+   * Default: `${baseUri}/login/oauth2/code/<provider key>`.
+   */
+  redirectUri?: string;
+}
+/**
+ * One identity source: every user it signs in has a `sub` unique within it, whichever client they
+ * came through. The key in `OAuth2ClientConfig.providers` names it in the routes and in
+ * `onAuthorized`. Two keys may share an implementation (two Google Cloud projects, one Okta per
+ * tenant) when their subjects are separate namespaces.
+ */
+export interface ProviderConfig {
+  /** The implementation: `apple`, `google`, `github`, ... from `@shware/security/oauth2/provider`. */
+  provider: Provider;
+  /** The redirect flow's and One Tap's client. Required by those flows. */
+  web?: WebClient;
+  /**
+   * Clients the native login accepts besides `web`. An app names its client with `client_id`;
+   * without one, the only native client is used, or `web` when there is none.
+   */
+  native?: NativeClient[];
+}
+export type ProvidersConfig = {
+  [key: string]: ProviderConfig | undefined;
+};
 export interface OAuth2ClientConfig {
   baseUri: string;
   errorUri: string;
   successUri: string;
-  provider: {
-    [name: string]: Provider | undefined;
-  };
-  registration: {
-    [name: string]: Registration | undefined;
-  } | (() => Promise<{
-    [name: string]: Registration | undefined;
-  }>);
+  /** Providers by key; a function is called per request, for secrets read at request time. */
+  providers: ProvidersConfig | (() => Promise<ProvidersConfig>);
 }
 //#endregion
 export {};

package/dist/oauth2/types.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.cts","names":[],"sources":["../../src/oauth2/types.ts"],"mappings":";iBACiB;EACf;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA,sBAAsB;;;;;;EAMtB,aAAa;;UAGL;EACR;EACA;EACA;EACA;EACA,OAAO,KAAK;;iBAGG;EACf;EACA;EACA;EACA;EACA,OAAO,KAAK;;iBAGG;EACf;EACA;EACA;;iBAGe;EACf;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA,OAAO;EACP,aAAa;;iBAIE;;;;;EAKf;;;;;EAMA;;;;;;;;EASA;;;;;;EAOA;;;;;;EAOA;EAEA;GAEC;;iBAGc,kBAAkB;EACjC;;YAGU;EACV;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;;EAYA,WAAW;;;iBAII;EACf;EACA;EACA;EACA;EACA;EACA;;;;;;;iBAQe;EACf;;qBAGW;YASD,oBAAoB;iBAGf;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;IACE;IACA;IACA;IACA;IACA;IACA;;EAEF;;iBAGe,SAAS;EACxB,QAAQ;EACR,MAAM;;iBAGS;;EAEf;;EAGA;;EAGA;;EAGA;;EAGA;;EAGA;;;;EAKA;;EAGA;;;;;EAMA;;EAGA;;EAGA,yBAAyB,QAAQ,iCAAiC;;EAGlE,4BAA4B,QAAQ,uBAAuB,QAAQ;;;;;EAMnE,cAAc,OAAO,aAAa,WAAW,0BAA0B,QAAQ;;EAG/E,sBAAsB,QAAQ,uBAAuB,QAAQ;;EAG7D,eAAe,QAAQ,sBAAsB;EAE7C,qBACE,QAAQ,4BACL;IAAU,OAAO;IAAa,UAAU;;;iBAG9B,uBAAuB;EACtC,eAAe,qBAAqB;IAAU,OAAO;IAAa,UAAU;;;iBAG7D;;;;;EAKf;;EAGA;;EAGA;;EAGA;;EAGA;;EAYA;;EAGA;;EAGA;;iBAGe;EACf;EACA;EACA;EACA;KAAa,eAAe;;EAC5B;KACO,eAAe;aACX;KAAW,eAAe"}
+{"version":3,"file":"types.d.cts","names":[],"sources":["../../src/oauth2/types.ts"],"mappings":";iBACiB;EACf;EACA;EACA;;iBAGe;EACf;;EAEA;EACA;EACA,sBAAsB;;;;;;EAMtB,aAAa;;UAGL;EACR;EACA;EACA;EACA;EACA,OAAO,KAAK;;iBAGG;EACf;EACA;;EAEA;EACA;EACA,OAAO,KAAK;;iBAGG;EACf;EACA;EACA;;iBAGe;EACf;EACA;EACA;;iBAGe;;;;;EAKf;EACA;EACA;EACA,OAAO;EACP,aAAa;;iBAIE;;;;;EAKf;;;;;EAMA;;;;;;;;EASA;;;;;;EAOA;;;;;;EAOA;EAEA;GAEC;;iBAGc,kBAAkB;EACjC;;YAGU;EACV;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;;EAYA,WAAW;;;iBAII;EACf;EACA;EACA;EACA;EACA;EACA;;;;;;;iBAQe;EACf;;qBAGW;YASD,oBAAoB;iBAGf;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;IACE;IACA;IACA;IACA;IACA;IACA;;EAEF;;iBAGe,SAAS;EACxB,QAAQ;EACR,MAAM;;iBAGS;;EAEf;;EAGA;;EAGA;;EAGA;;EAGA;;EAGA;;;;EAKA;;EAGA;;;;;EAMA;;EAGA;;EAGA,yBAAyB,QAAQ,iCAAiC;;EAGlE,4BAA4B,QAAQ,uBAAuB,QAAQ;;;;;;EAOnE,cAAc,OAAO,aAAa,SAAS,oBAAoB,QAAQ;;EAGvE,sBAAsB,QAAQ,uBAAuB,QAAQ;;EAG7D,eAAe,QAAQ,sBAAsB;EAE7C,qBACE,QAAQ,4BACL;IAAU,OAAO;IAAa,UAAU;;;iBAG9B;EACf;EACA,WAAW;;iBAGI,uBAAuB;;EAEtC,eACE,kBACA,qBACG;IAAU,OAAO;IAAa,UAAU;;;;;;;;YAQnC,0BAA0B,8BAA8B;;iBAGnD;EACf;;EAEA,eAAe;;EAEf;;EAEA;;;;;;iBAOe;EACf;;EAEA,eAAe;;;;;EAKf;;;;;;;;iBASe;;EAEf,UAAU;;EAEV,MAAM;;;;;EAKN,SAAS;;YAGC;GAAqB,cAAc;;iBAE9B;EACf;EACA;EACA;;EAEA,WAAW,yBAAyB,QAAQ"}

package/dist/oauth2/types.d.mts

@@ -6,7 +6,8 @@ export interface PkceParameters {
 }
 export interface OAuth2AuthorizationRequest {
   state: string;
-  registrationId: string;
+  /** Key of the provider in `OAuth2ClientConfig.providers` the flow was started for. */
+  provider: string;
   authorizationRequestUri: string;
   additionalParameters: PkceParameters;
   /**
@@ -26,23 +27,28 @@ interface CreateAuthorizationUriParams {
 export interface ExchangeCodeParams {
   code: string;
   clientId: string;
-  clientSecret: string;
+  /** Absent for public clients (Google's installed-app clients, PKCE-only clients). */
+  clientSecret?: string;
   redirectUri: string;
   pkce?: Omit<PkceParameters, 'code_challenge' | 'code_challenge_method'>;
 }
 export interface RefreshTokenParams {
   clientId: string;
-  clientSecret: string;
+  clientSecret?: string;
   refreshToken: string;
 }
 export interface RevokeTokenParams {
   token: string;
   clientId: string;
-  clientSecret: string;
+  clientSecret?: string;
 }
 export interface LoginOAuth2NativeParams {
+  /**
+   * The configured client the app signs in as (its `client_id`, or the provider's default native
+   * client). Id tokens must be issued to it: it is the only audience accepted.
+   */
   clientId: string;
-  clientSecret: string;
+  clientSecret?: string;
   redirectUri: string;
   pkce?: PkceParameters;
   credentials: NativeCredential;
@@ -187,10 +193,11 @@ export interface Provider {
   /** step 2: exchange code for token */
   exchangeAuthorizationCode: (params: ExchangeCodeParams) => Promise<OAuth2Token>;
   /**
-   * step 3: get user info; `response` holds what the authorization response carried besides the
-   * code, for the providers that send user data there (Apple).
+   * step 3: get user info. `context.clientId` is the client the token was issued to, the only
+   * audience an id token may carry; `context.response` holds what the authorization response
+   * carried besides the code, for the providers that send user data there (Apple).
    */
-  getUserInfo: (token: OAuth2Token, response?: AuthorizationResponse) => Promise<UserInfo>;
+  getUserInfo: (token: OAuth2Token, context: UserInfoContext) => Promise<UserInfo>;
   /** others: refresh access token */
   refreshAccessToken?: (params: RefreshTokenParams) => Promise<OAuth2Token>;
   /** others: revoke token */
@@ -200,45 +207,73 @@ export interface Provider {
     userInfo: UserInfo;
   }>;
 }
+export interface UserInfoContext {
+  clientId: string;
+  response?: AuthorizationResponse;
+}
 export interface OneTapProvider extends Provider {
-  getTokenInfo: (id_token: string) => Promise<{
+  /** Verifies a One Tap / FedCM credential, which must be issued to `clientId` (the web client). */
+  getTokenInfo: (id_token: string, clientId: string) => Promise<{
     token: OAuth2Token;
     userInfo: UserInfo;
   }>;
 }
-export interface Registration {
-  /**
-   * Reference to the OAuth 2.0 provider to use. May reference an element from the 'provider'
-   * property or used one of the commonly used providers (google, github, facebook, okta).
-   * */
-  provider?: string;
-  /** Client ID for the registration. */
+/**
+ * A client secret: a fixed string, or a function minting one for the client id it is called with
+ * (Sign in with Apple's signed JWT, see `createAppleClientSecret`), called on every use so it can
+ * cache and renew on its own.
+ */
+export type ClientSecret = string | ((clientId: string) => string | Promise<string>);
+/** The client a provider's server-side flows sign in as: the redirect flow and Google One Tap. */
+export interface WebClient {
   clientId: string;
-  /** Client secret of the registration. */
-  clientSecret: string;
-  /** Client authentication method. May be left blank when using a pre-defined provider. */
-  clientAuthenticationMethod?: string;
-  /** Authorization grant type. May be left blank when using a pre-defined provider. */
-  authorizationGrantType?: 'authorization_code' | 'client_credentials' | 'device_code' | 'jwt_bearer' | 'password' | 'refresh_token' | 'token_exchange';
-  /** Redirect URI. May be left blank when using a pre-defined provider. */
+  /** Absent for a public client. */
+  clientSecret?: ClientSecret;
+  /** Default: `${baseUri}/login/oauth2/code/<provider key>`. */
   redirectUri?: string;
-  /** Authorization scopes. When left blank the provider's default scopes, if any, will be used. */
+  /** Authorization scopes. Default: the provider's `defaultScope`. */
   scope?: string[];
-  /** Client name. May be left blank when using a pre-defined provider. */
-  clientName?: string;
 }
+/**
+ * A client an app signs in as on the device (an iOS bundle id, a Google iOS / Android client) and
+ * whose code or id token it posts to the native login route.
+ */
+export interface NativeClient {
+  clientId: string;
+  /** Absent for a public client (Google's installed-app clients have none). */
+  clientSecret?: ClientSecret;
+  /**
+   * Redirect URI sent with the code exchange when the app sends no `redirect_uri` of its own.
+   * Default: `${baseUri}/login/oauth2/code/<provider key>`.
+   */
+  redirectUri?: string;
+}
+/**
+ * One identity source: every user it signs in has a `sub` unique within it, whichever client they
+ * came through. The key in `OAuth2ClientConfig.providers` names it in the routes and in
+ * `onAuthorized`. Two keys may share an implementation (two Google Cloud projects, one Okta per
+ * tenant) when their subjects are separate namespaces.
+ */
+export interface ProviderConfig {
+  /** The implementation: `apple`, `google`, `github`, ... from `@shware/security/oauth2/provider`. */
+  provider: Provider;
+  /** The redirect flow's and One Tap's client. Required by those flows. */
+  web?: WebClient;
+  /**
+   * Clients the native login accepts besides `web`. An app names its client with `client_id`;
+   * without one, the only native client is used, or `web` when there is none.
+   */
+  native?: NativeClient[];
+}
+export type ProvidersConfig = {
+  [key: string]: ProviderConfig | undefined;
+};
 export interface OAuth2ClientConfig {
   baseUri: string;
   errorUri: string;
   successUri: string;
-  provider: {
-    [name: string]: Provider | undefined;
-  };
-  registration: {
-    [name: string]: Registration | undefined;
-  } | (() => Promise<{
-    [name: string]: Registration | undefined;
-  }>);
+  /** Providers by key; a function is called per request, for secrets read at request time. */
+  providers: ProvidersConfig | (() => Promise<ProvidersConfig>);
 }
 //#endregion
 export {};

package/dist/oauth2/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/oauth2/types.ts"],"mappings":";iBACiB;EACf;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA,sBAAsB;;;;;;EAMtB,aAAa;;UAGL;EACR;EACA;EACA;EACA;EACA,OAAO,KAAK;;iBAGG;EACf;EACA;EACA;EACA;EACA,OAAO,KAAK;;iBAGG;EACf;EACA;EACA;;iBAGe;EACf;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA,OAAO;EACP,aAAa;;iBAIE;;;;;EAKf;;;;;EAMA;;;;;;;;EASA;;;;;;EAOA;;;;;;EAOA;EAEA;GAEC;;iBAGc,kBAAkB;EACjC;;YAGU;EACV;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;;EAYA,WAAW;;;iBAII;EACf;EACA;EACA;EACA;EACA;EACA;;;;;;;iBAQe;EACf;;qBAGW;YASD,oBAAoB;iBAGf;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;IACE;IACA;IACA;IACA;IACA;IACA;;EAEF;;iBAGe,SAAS;EACxB,QAAQ;EACR,MAAM;;iBAGS;;EAEf;;EAGA;;EAGA;;EAGA;;EAGA;;EAGA;;;;EAKA;;EAGA;;;;;EAMA;;EAGA;;EAGA,yBAAyB,QAAQ,iCAAiC;;EAGlE,4BAA4B,QAAQ,uBAAuB,QAAQ;;;;;EAMnE,cAAc,OAAO,aAAa,WAAW,0BAA0B,QAAQ;;EAG/E,sBAAsB,QAAQ,uBAAuB,QAAQ;;EAG7D,eAAe,QAAQ,sBAAsB;EAE7C,qBACE,QAAQ,4BACL;IAAU,OAAO;IAAa,UAAU;;;iBAG9B,uBAAuB;EACtC,eAAe,qBAAqB;IAAU,OAAO;IAAa,UAAU;;;iBAG7D;;;;;EAKf;;EAGA;;EAGA;;EAGA;;EAGA;;EAYA;;EAGA;;EAGA;;iBAGe;EACf;EACA;EACA;EACA;KAAa,eAAe;;EAC5B;KACO,eAAe;aACX;KAAW,eAAe"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/oauth2/types.ts"],"mappings":";iBACiB;EACf;EACA;EACA;;iBAGe;EACf;;EAEA;EACA;EACA,sBAAsB;;;;;;EAMtB,aAAa;;UAGL;EACR;EACA;EACA;EACA;EACA,OAAO,KAAK;;iBAGG;EACf;EACA;;EAEA;EACA;EACA,OAAO,KAAK;;iBAGG;EACf;EACA;EACA;;iBAGe;EACf;EACA;EACA;;iBAGe;;;;;EAKf;EACA;EACA;EACA,OAAO;EACP,aAAa;;iBAIE;;;;;EAKf;;;;;EAMA;;;;;;;;EASA;;;;;;EAOA;;;;;;EAOA;EAEA;GAEC;;iBAGc,kBAAkB;EACjC;;YAGU;EACV;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;;EAYA,WAAW;;;iBAII;EACf;EACA;EACA;EACA;EACA;EACA;;;;;;;iBAQe;EACf;;qBAGW;YASD,oBAAoB;iBAGf;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;IACE;IACA;IACA;IACA;IACA;IACA;;EAEF;;iBAGe,SAAS;EACxB,QAAQ;EACR,MAAM;;iBAGS;;EAEf;;EAGA;;EAGA;;EAGA;;EAGA;;EAGA;;;;EAKA;;EAGA;;;;;EAMA;;EAGA;;EAGA,yBAAyB,QAAQ,iCAAiC;;EAGlE,4BAA4B,QAAQ,uBAAuB,QAAQ;;;;;;EAOnE,cAAc,OAAO,aAAa,SAAS,oBAAoB,QAAQ;;EAGvE,sBAAsB,QAAQ,uBAAuB,QAAQ;;EAG7D,eAAe,QAAQ,sBAAsB;EAE7C,qBACE,QAAQ,4BACL;IAAU,OAAO;IAAa,UAAU;;;iBAG9B;EACf;EACA,WAAW;;iBAGI,uBAAuB;;EAEtC,eACE,kBACA,qBACG;IAAU,OAAO;IAAa,UAAU;;;;;;;;YAQnC,0BAA0B,8BAA8B;;iBAGnD;EACf;;EAEA,eAAe;;EAEf;;EAEA;;;;;;iBAOe;EACf;;EAEA,eAAe;;;;;EAKf;;;;;;;;iBASe;;EAEf,UAAU;;EAEV,MAAM;;;;;EAKN,SAAS;;YAGC;GAAqB,cAAc;;iBAE9B;EACf;EACA;EACA;;EAEA,WAAW,yBAAyB,QAAQ"}

package/dist/oauth2/types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.mjs","names":[],"sources":["../../src/oauth2/types.ts"],"sourcesContent":["// reference: https://datatracker.ietf.org/doc/html/rfc7636\nexport interface PkceParameters {\n  code_verifier: string;\n  code_challenge: string;\n  code_challenge_method: 'S256' | 'plain';\n}\n\nexport interface OAuth2AuthorizationRequest {\n  state: string;\n  registrationId: string;\n  authorizationRequestUri: string;\n  additionalParameters: PkceParameters;\n  /**\n   * What the host attached when the flow started (`oauth2Authorization` options), kept on the\n   * server and handed back to `onAuthorized` once the callback checks out. Never sent to the\n   * provider, unlike `additionalParameters`. Absent on requests stored before this field existed.\n   */\n  attributes?: Record<string, string>;\n}\n\ninterface CreateAuthorizationUriParams {\n  state: string;\n  clientId: string;\n  redirectUri: string;\n  scope: string[] | undefined;\n  pkce?: Omit<PkceParameters, 'code_verifier'>;\n}\n\nexport interface ExchangeCodeParams {\n  code: string;\n  clientId: string;\n  clientSecret: string;\n  redirectUri: string;\n  pkce?: Omit<PkceParameters, 'code_challenge' | 'code_challenge_method'>;\n}\n\nexport interface RefreshTokenParams {\n  clientId: string;\n  clientSecret: string;\n  refreshToken: string;\n}\n\nexport interface RevokeTokenParams {\n  token: string;\n  clientId: string;\n  clientSecret: string;\n}\n\nexport interface LoginOAuth2NativeParams {\n  clientId: string;\n  clientSecret: string;\n  redirectUri: string;\n  pkce?: PkceParameters;\n  credentials: NativeCredential;\n}\n\n// reference: https://datatracker.ietf.org/doc/html/rfc6749#section-5.1\nexport interface OAuth2Token {\n  /**\n   * REQUIRED.\n   * The access token issued by the authorization server.\n   */\n  access_token: string;\n\n  /**\n   * REQUIRED.\n   * The type of the token issued as described in Section 7.1.  Value is case insensitive.\n   */\n  token_type: 'Bearer' | 'bearer' | 'mac' | (string & {});\n\n  /**\n   * RECOMMENDED.\n   * The lifetime in seconds of the access token. For example, the value \"3600\" denotes that the\n   * access token will expire in one hour from the time the response was generated. If omitted, the\n   * authorization server SHOULD provide the expiration time via other means or document the default\n   * value.\n   */\n  expires_in?: number;\n\n  /**\n   * OPTIONAL.\n   * The refresh token, which can be used to obtain new access tokens using the same authorization\n   * grant as described in Section 6.\n   */\n  refresh_token?: string;\n\n  /**\n   * OPTIONAL.\n   * If identical to the scope requested by the client; otherwise, REQUIRED. The scope of the\n   * access token as described by Section 3.3.\n   */\n  scope?: string;\n\n  id_token?: string;\n\n  [key: string]: unknown;\n}\n\nexport interface OidcToken extends OAuth2Token {\n  id_token: string;\n}\n\nexport type NativeCredential = {\n  state?: string;\n  code?: string;\n  client_id?: string;\n  redirect_uri?: string;\n  id_token?: string;\n  access_token?: string;\n  /**\n   * The user's name as the platform hands it to the app, for providers whose id token carries none\n   * (Apple sends it on the first authorization only): iOS\n   * `ASAuthorizationAppleIDCredential.fullName`, expo-apple-authentication's `credential.fullName`.\n   * The snake_case fields above are OAuth / OIDC protocol parameters; this one is not, it is the\n   * platform's object passed through unchanged, so it keeps the platform's own name and apps send\n   * `fullName: credential.fullName` as is. Unsigned client input: the provider cleans each part and\n   * ignores anything that is not a string. Parts with a standard claim become `given_name`,\n   * `family_name`, `middle_name` and `nickname`; `namePrefix` / `nameSuffix` have none and are kept\n   * in `userInfo.data.fullName` only.\n   */\n  fullName?: PersonNameComponents;\n};\n\n/** iOS `PersonNameComponents` as JSON; every part may be missing or `null`. */\nexport interface PersonNameComponents {\n  givenName?: string | null;\n  familyName?: string | null;\n  middleName?: string | null;\n  namePrefix?: string | null;\n  nameSuffix?: string | null;\n  nickname?: string | null;\n}\n\n/**\n * Fields of the authorization response besides `code` and `state` that a provider uses to fill in\n * the user info: Apple posts the user's name as `user` (JSON) with the first authorization only,\n * since its id token never carries one. Unsigned, so treated as untrusted input.\n */\nexport interface AuthorizationResponse {\n  user?: string;\n}\n\nexport const OIDC_SCOPES = [\n  'openid',\n  'profile',\n  'email',\n  'phone',\n  'address',\n  'offline_access',\n] as const;\n\nexport type OidcScope = (typeof OIDC_SCOPES)[number];\n\n// https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims\nexport interface StandardClaims {\n  sub: string;\n  name?: string;\n  given_name?: string;\n  family_name?: string;\n  middle_name?: string;\n  nickname?: string;\n  preferred_username?: string;\n  profile?: string;\n  picture?: string;\n  website?: string;\n  email?: string;\n  email_verified?: boolean;\n  gender?: 'female' | 'male' | (string & {});\n  birthdate?: string; // ISO 8601-1 [ISO8601‑1] YYYY-MM-DD format.\n  zoneinfo?: string; // IANA Time Zone Database [IANA.time‑zones]\n  locale?: string; // BCP47 [RFC5646] language tag.\n  phone_number?: string; // E.164\n  phone_number_verified?: boolean;\n  address?: {\n    formatted: string;\n    street_address: string;\n    locality: string;\n    region: string;\n    postal_code: string;\n    country: string;\n  }; // [RFC8259] JSON object\n  updated_at?: number;\n}\n\nexport interface UserInfo<T = unknown> {\n  claims: StandardClaims;\n  data: T;\n}\n\nexport interface Provider {\n  /** Authorization URI for the provider. */\n  authorizationUri: string;\n\n  /** Token URI for the provider. */\n  tokenUri: string;\n\n  /** Token revoke URI for the provider. */\n  tokenRevokeUri?: string;\n\n  /** Token refresh URI for the provider. */\n  tokenRefreshUri?: string;\n\n  /** User info URI for the provider. */\n  userInfoUri?: string;\n\n  /** User info authentication method for the provider. */\n  userInfoAuthenticationMethod?: string;\n\n  /**\n   * Name of the attribute that will be used to extract the username from the call to 'userInfoUri'.\n   * */\n  userNameAttribute?: string;\n\n  /** JWK set URI for the provider */\n  jwkSetUri?: string;\n\n  /**\n   * URI that can either be an OpenID Connect discovery endpoint or an OAuth 2.0 Authorization\n   * Server Metadata endpoint defined by RFC 8414.\n   * */\n  issuerUri?: string;\n\n  /** Default scopes for the provider. */\n  defaultScope: string[];\n\n  /** step 1: generate authorization uri and redirect user to it */\n  createAuthorizationUri: (params: CreateAuthorizationUriParams) => URL;\n\n  /** step 2: exchange code for token */\n  exchangeAuthorizationCode: (params: ExchangeCodeParams) => Promise<OAuth2Token>;\n\n  /**\n   * step 3: get user info; `response` holds what the authorization response carried besides the\n   * code, for the providers that send user data there (Apple).\n   */\n  getUserInfo: (token: OAuth2Token, response?: AuthorizationResponse) => Promise<UserInfo>;\n\n  /** others: refresh access token */\n  refreshAccessToken?: (params: RefreshTokenParams) => Promise<OAuth2Token>;\n\n  /** others: revoke token */\n  revokeToken?: (params: RevokeTokenParams) => Promise<void>;\n\n  loginOAuth2Native?: (\n    params: LoginOAuth2NativeParams\n  ) => Promise<{ token: OAuth2Token; userInfo: UserInfo }>;\n}\n\nexport interface OneTapProvider extends Provider {\n  getTokenInfo: (id_token: string) => Promise<{ token: OAuth2Token; userInfo: UserInfo }>;\n}\n\nexport interface Registration {\n  /**\n   * Reference to the OAuth 2.0 provider to use. May reference an element from the 'provider'\n   * property or used one of the commonly used providers (google, github, facebook, okta).\n   * */\n  provider?: string;\n\n  /** Client ID for the registration. */\n  clientId: string;\n\n  /** Client secret of the registration. */\n  clientSecret: string;\n\n  /** Client authentication method. May be left blank when using a pre-defined provider. */\n  clientAuthenticationMethod?: string;\n\n  /** Authorization grant type. May be left blank when using a pre-defined provider. */\n  authorizationGrantType?:\n    | 'authorization_code' // default\n    | 'client_credentials'\n    | 'device_code'\n    | 'jwt_bearer'\n    // Deprecated. The latest OAuth 2.0 Security Best Current Practice disallows the use of the\n    // Resource Owner Password Credentials grant.\n    | 'password'\n    | 'refresh_token'\n    | 'token_exchange';\n\n  /** Redirect URI. May be left blank when using a pre-defined provider. */\n  redirectUri?: string;\n\n  /** Authorization scopes. When left blank the provider's default scopes, if any, will be used. */\n  scope?: string[];\n\n  /** Client name. May be left blank when using a pre-defined provider. */\n  clientName?: string;\n}\n\nexport interface OAuth2ClientConfig {\n  baseUri: string;\n  errorUri: string;\n  successUri: string;\n  provider: { [name: string]: Provider | undefined };\n  registration:\n    | { [name: string]: Registration | undefined }\n    | (() => Promise<{ [name: string]: Registration | undefined }>);\n}\n"],"mappings":";AA8IA,MAAa,cAAc;CACzB;CACA;CACA;CACA;CACA;CACA;AACF"}
+{"version":3,"file":"types.mjs","names":[],"sources":["../../src/oauth2/types.ts"],"sourcesContent":["// reference: https://datatracker.ietf.org/doc/html/rfc7636\nexport interface PkceParameters {\n  code_verifier: string;\n  code_challenge: string;\n  code_challenge_method: 'S256' | 'plain';\n}\n\nexport interface OAuth2AuthorizationRequest {\n  state: string;\n  /** Key of the provider in `OAuth2ClientConfig.providers` the flow was started for. */\n  provider: string;\n  authorizationRequestUri: string;\n  additionalParameters: PkceParameters;\n  /**\n   * What the host attached when the flow started (`oauth2Authorization` options), kept on the\n   * server and handed back to `onAuthorized` once the callback checks out. Never sent to the\n   * provider, unlike `additionalParameters`. Absent on requests stored before this field existed.\n   */\n  attributes?: Record<string, string>;\n}\n\ninterface CreateAuthorizationUriParams {\n  state: string;\n  clientId: string;\n  redirectUri: string;\n  scope: string[] | undefined;\n  pkce?: Omit<PkceParameters, 'code_verifier'>;\n}\n\nexport interface ExchangeCodeParams {\n  code: string;\n  clientId: string;\n  /** Absent for public clients (Google's installed-app clients, PKCE-only clients). */\n  clientSecret?: string;\n  redirectUri: string;\n  pkce?: Omit<PkceParameters, 'code_challenge' | 'code_challenge_method'>;\n}\n\nexport interface RefreshTokenParams {\n  clientId: string;\n  clientSecret?: string;\n  refreshToken: string;\n}\n\nexport interface RevokeTokenParams {\n  token: string;\n  clientId: string;\n  clientSecret?: string;\n}\n\nexport interface LoginOAuth2NativeParams {\n  /**\n   * The configured client the app signs in as (its `client_id`, or the provider's default native\n   * client). Id tokens must be issued to it: it is the only audience accepted.\n   */\n  clientId: string;\n  clientSecret?: string;\n  redirectUri: string;\n  pkce?: PkceParameters;\n  credentials: NativeCredential;\n}\n\n// reference: https://datatracker.ietf.org/doc/html/rfc6749#section-5.1\nexport interface OAuth2Token {\n  /**\n   * REQUIRED.\n   * The access token issued by the authorization server.\n   */\n  access_token: string;\n\n  /**\n   * REQUIRED.\n   * The type of the token issued as described in Section 7.1.  Value is case insensitive.\n   */\n  token_type: 'Bearer' | 'bearer' | 'mac' | (string & {});\n\n  /**\n   * RECOMMENDED.\n   * The lifetime in seconds of the access token. For example, the value \"3600\" denotes that the\n   * access token will expire in one hour from the time the response was generated. If omitted, the\n   * authorization server SHOULD provide the expiration time via other means or document the default\n   * value.\n   */\n  expires_in?: number;\n\n  /**\n   * OPTIONAL.\n   * The refresh token, which can be used to obtain new access tokens using the same authorization\n   * grant as described in Section 6.\n   */\n  refresh_token?: string;\n\n  /**\n   * OPTIONAL.\n   * If identical to the scope requested by the client; otherwise, REQUIRED. The scope of the\n   * access token as described by Section 3.3.\n   */\n  scope?: string;\n\n  id_token?: string;\n\n  [key: string]: unknown;\n}\n\nexport interface OidcToken extends OAuth2Token {\n  id_token: string;\n}\n\nexport type NativeCredential = {\n  state?: string;\n  code?: string;\n  client_id?: string;\n  redirect_uri?: string;\n  id_token?: string;\n  access_token?: string;\n  /**\n   * The user's name as the platform hands it to the app, for providers whose id token carries none\n   * (Apple sends it on the first authorization only): iOS\n   * `ASAuthorizationAppleIDCredential.fullName`, expo-apple-authentication's `credential.fullName`.\n   * The snake_case fields above are OAuth / OIDC protocol parameters; this one is not, it is the\n   * platform's object passed through unchanged, so it keeps the platform's own name and apps send\n   * `fullName: credential.fullName` as is. Unsigned client input: the provider cleans each part and\n   * ignores anything that is not a string. Parts with a standard claim become `given_name`,\n   * `family_name`, `middle_name` and `nickname`; `namePrefix` / `nameSuffix` have none and are kept\n   * in `userInfo.data.fullName` only.\n   */\n  fullName?: PersonNameComponents;\n};\n\n/** iOS `PersonNameComponents` as JSON; every part may be missing or `null`. */\nexport interface PersonNameComponents {\n  givenName?: string | null;\n  familyName?: string | null;\n  middleName?: string | null;\n  namePrefix?: string | null;\n  nameSuffix?: string | null;\n  nickname?: string | null;\n}\n\n/**\n * Fields of the authorization response besides `code` and `state` that a provider uses to fill in\n * the user info: Apple posts the user's name as `user` (JSON) with the first authorization only,\n * since its id token never carries one. Unsigned, so treated as untrusted input.\n */\nexport interface AuthorizationResponse {\n  user?: string;\n}\n\nexport const OIDC_SCOPES = [\n  'openid',\n  'profile',\n  'email',\n  'phone',\n  'address',\n  'offline_access',\n] as const;\n\nexport type OidcScope = (typeof OIDC_SCOPES)[number];\n\n// https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims\nexport interface StandardClaims {\n  sub: string;\n  name?: string;\n  given_name?: string;\n  family_name?: string;\n  middle_name?: string;\n  nickname?: string;\n  preferred_username?: string;\n  profile?: string;\n  picture?: string;\n  website?: string;\n  email?: string;\n  email_verified?: boolean;\n  gender?: 'female' | 'male' | (string & {});\n  birthdate?: string; // ISO 8601-1 [ISO8601‑1] YYYY-MM-DD format.\n  zoneinfo?: string; // IANA Time Zone Database [IANA.time‑zones]\n  locale?: string; // BCP47 [RFC5646] language tag.\n  phone_number?: string; // E.164\n  phone_number_verified?: boolean;\n  address?: {\n    formatted: string;\n    street_address: string;\n    locality: string;\n    region: string;\n    postal_code: string;\n    country: string;\n  }; // [RFC8259] JSON object\n  updated_at?: number;\n}\n\nexport interface UserInfo<T = unknown> {\n  claims: StandardClaims;\n  data: T;\n}\n\nexport interface Provider {\n  /** Authorization URI for the provider. */\n  authorizationUri: string;\n\n  /** Token URI for the provider. */\n  tokenUri: string;\n\n  /** Token revoke URI for the provider. */\n  tokenRevokeUri?: string;\n\n  /** Token refresh URI for the provider. */\n  tokenRefreshUri?: string;\n\n  /** User info URI for the provider. */\n  userInfoUri?: string;\n\n  /** User info authentication method for the provider. */\n  userInfoAuthenticationMethod?: string;\n\n  /**\n   * Name of the attribute that will be used to extract the username from the call to 'userInfoUri'.\n   * */\n  userNameAttribute?: string;\n\n  /** JWK set URI for the provider */\n  jwkSetUri?: string;\n\n  /**\n   * URI that can either be an OpenID Connect discovery endpoint or an OAuth 2.0 Authorization\n   * Server Metadata endpoint defined by RFC 8414.\n   * */\n  issuerUri?: string;\n\n  /** Default scopes for the provider. */\n  defaultScope: string[];\n\n  /** step 1: generate authorization uri and redirect user to it */\n  createAuthorizationUri: (params: CreateAuthorizationUriParams) => URL;\n\n  /** step 2: exchange code for token */\n  exchangeAuthorizationCode: (params: ExchangeCodeParams) => Promise<OAuth2Token>;\n\n  /**\n   * step 3: get user info. `context.clientId` is the client the token was issued to, the only\n   * audience an id token may carry; `context.response` holds what the authorization response\n   * carried besides the code, for the providers that send user data there (Apple).\n   */\n  getUserInfo: (token: OAuth2Token, context: UserInfoContext) => Promise<UserInfo>;\n\n  /** others: refresh access token */\n  refreshAccessToken?: (params: RefreshTokenParams) => Promise<OAuth2Token>;\n\n  /** others: revoke token */\n  revokeToken?: (params: RevokeTokenParams) => Promise<void>;\n\n  loginOAuth2Native?: (\n    params: LoginOAuth2NativeParams\n  ) => Promise<{ token: OAuth2Token; userInfo: UserInfo }>;\n}\n\nexport interface UserInfoContext {\n  clientId: string;\n  response?: AuthorizationResponse;\n}\n\nexport interface OneTapProvider extends Provider {\n  /** Verifies a One Tap / FedCM credential, which must be issued to `clientId` (the web client). */\n  getTokenInfo: (\n    id_token: string,\n    clientId: string\n  ) => Promise<{ token: OAuth2Token; userInfo: UserInfo }>;\n}\n\n/**\n * A client secret: a fixed string, or a function minting one for the client id it is called with\n * (Sign in with Apple's signed JWT, see `createAppleClientSecret`), called on every use so it can\n * cache and renew on its own.\n */\nexport type ClientSecret = string | ((clientId: string) => string | Promise<string>);\n\n/** The client a provider's server-side flows sign in as: the redirect flow and Google One Tap. */\nexport interface WebClient {\n  clientId: string;\n  /** Absent for a public client. */\n  clientSecret?: ClientSecret;\n  /** Default: `${baseUri}/login/oauth2/code/<provider key>`. */\n  redirectUri?: string;\n  /** Authorization scopes. Default: the provider's `defaultScope`. */\n  scope?: string[];\n}\n\n/**\n * A client an app signs in as on the device (an iOS bundle id, a Google iOS / Android client) and\n * whose code or id token it posts to the native login route.\n */\nexport interface NativeClient {\n  clientId: string;\n  /** Absent for a public client (Google's installed-app clients have none). */\n  clientSecret?: ClientSecret;\n  /**\n   * Redirect URI sent with the code exchange when the app sends no `redirect_uri` of its own.\n   * Default: `${baseUri}/login/oauth2/code/<provider key>`.\n   */\n  redirectUri?: string;\n}\n\n/**\n * One identity source: every user it signs in has a `sub` unique within it, whichever client they\n * came through. The key in `OAuth2ClientConfig.providers` names it in the routes and in\n * `onAuthorized`. Two keys may share an implementation (two Google Cloud projects, one Okta per\n * tenant) when their subjects are separate namespaces.\n */\nexport interface ProviderConfig {\n  /** The implementation: `apple`, `google`, `github`, ... from `@shware/security/oauth2/provider`. */\n  provider: Provider;\n  /** The redirect flow's and One Tap's client. Required by those flows. */\n  web?: WebClient;\n  /**\n   * Clients the native login accepts besides `web`. An app names its client with `client_id`;\n   * without one, the only native client is used, or `web` when there is none.\n   */\n  native?: NativeClient[];\n}\n\nexport type ProvidersConfig = { [key: string]: ProviderConfig | undefined };\n\nexport interface OAuth2ClientConfig {\n  baseUri: string;\n  errorUri: string;\n  successUri: string;\n  /** Providers by key; a function is called per request, for secrets read at request time. */\n  providers: ProvidersConfig | (() => Promise<ProvidersConfig>);\n}\n"],"mappings":";AAoJA,MAAa,cAAc;CACzB;CACA;CACA;CACA;CACA;CACA;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shware/security",
-  "version": "4.1.0",
+  "version": "5.0.0",
   "private": false,
   "repository": {
     "type": "git",