@atcute/oauth-types 0.1.0

package/lib/schemas/oauth-authorization-details.ts

@@ -0,0 +1,43 @@
+import * as v from '@badrap/valita';
+
+import { urlSchema } from './uri.js';
+
+/**
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc9396#section-2 | RFC 9396, Section 2}
+ */
+export const oauthAuthorizationDetailSchema = v.object({
+	type: v.string(),
+	/**
+	 * an array of strings representing the location of the resource or RS. these
+	 * strings are typically URIs identifying the location of the RS.
+	 */
+	locations: v.array(urlSchema).optional(),
+	/**
+	 * an array of strings representing the kinds of actions to be taken at the
+	 * resource.
+	 */
+	actions: v.array(v.string()).optional(),
+	/**
+	 * an array of strings representing the kinds of data being requested from the
+	 * resource.
+	 */
+	datatypes: v.array(v.string()).optional(),
+	/**
+	 * a string identifier indicating a specific resource available at the API.
+	 */
+	identifier: v.string().optional(),
+	/**
+	 * an array of strings representing the types or levels of privilege being
+	 * requested at the resource.
+	 */
+	privileges: v.array(v.string()).optional(),
+});
+
+export type OAuthAuthorizationDetail = v.Infer<typeof oauthAuthorizationDetailSchema>;
+
+/**
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc9396#section-2 | RFC 9396, Section 2}
+ */
+export const oauthAuthorizationDetailsSchema = v.array(oauthAuthorizationDetailSchema);
+
+export type OAuthAuthorizationDetails = v.Infer<typeof oauthAuthorizationDetailsSchema>;

package/lib/schemas/oauth-authorization-server-metadata.ts

@@ -0,0 +1,101 @@
+import * as v from '@badrap/valita';
+
+import { oauthCodeChallengeMethodSchema } from './oauth-code-challenge-method.js';
+import { oauthIssuerIdentifierSchema } from './oauth-issuer-identifier.js';
+import { oauthPromptSchema } from './oauth-prompt.js';
+import { webUriSchema } from './uri.js';
+
+/**
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc8414}
+ */
+export const oauthAuthorizationServerMetadataSchema = v.object({
+	issuer: oauthIssuerIdentifierSchema,
+
+	claims_supported: v.array(v.string()).optional(),
+	claims_locales_supported: v.array(v.string()).optional(),
+	claims_parameter_supported: v.boolean().optional(),
+	request_parameter_supported: v.boolean().optional(),
+	request_uri_parameter_supported: v.boolean().optional(),
+	require_request_uri_registration: v.boolean().optional(),
+	scopes_supported: v.array(v.string()).optional(),
+	subject_types_supported: v.array(v.string()).optional(),
+	response_types_supported: v.array(v.string()).optional(),
+	response_modes_supported: v.array(v.string()).optional(),
+	grant_types_supported: v.array(v.string()).optional(),
+	code_challenge_methods_supported: v.array(oauthCodeChallengeMethodSchema).optional(),
+	ui_locales_supported: v.array(v.string()).optional(),
+	id_token_signing_alg_values_supported: v.array(v.string()).optional(),
+	display_values_supported: v.array(v.string()).optional(),
+	prompt_values_supported: v.array(oauthPromptSchema).optional(),
+	request_object_signing_alg_values_supported: v.array(v.string()).optional(),
+	authorization_response_iss_parameter_supported: v.boolean().optional(),
+	authorization_details_types_supported: v.array(v.string()).optional(),
+	request_object_encryption_alg_values_supported: v.array(v.string()).optional(),
+	request_object_encryption_enc_values_supported: v.array(v.string()).optional(),
+
+	jwks_uri: webUriSchema.optional(),
+
+	authorization_endpoint: webUriSchema,
+
+	token_endpoint: webUriSchema,
+	// https://www.rfc-editor.org/rfc/rfc8414.html#section-2
+	token_endpoint_auth_methods_supported: v.array(v.string()).optional(),
+	token_endpoint_auth_signing_alg_values_supported: v.array(v.string()).optional(),
+
+	revocation_endpoint: webUriSchema.optional(),
+	revocation_endpoint_auth_methods_supported: v.array(v.string()).optional(),
+	revocation_endpoint_auth_signing_alg_values_supported: v.array(v.string()).optional(),
+
+	introspection_endpoint: webUriSchema.optional(),
+	introspection_endpoint_auth_methods_supported: v.array(v.string()).optional(),
+	introspection_endpoint_auth_signing_alg_values_supported: v.array(v.string()).optional(),
+
+	pushed_authorization_request_endpoint: webUriSchema.optional(),
+	pushed_authorization_request_endpoint_auth_methods_supported: v.array(v.string()).optional(),
+	pushed_authorization_request_endpoint_auth_signing_alg_values_supported: v.array(v.string()).optional(),
+	require_pushed_authorization_requests: v.boolean().optional(),
+
+	userinfo_endpoint: webUriSchema.optional(),
+	end_session_endpoint: webUriSchema.optional(),
+	registration_endpoint: webUriSchema.optional(),
+
+	// https://datatracker.ietf.org/doc/html/rfc9449#section-5.1
+	dpop_signing_alg_values_supported: v.array(v.string()).optional(),
+
+	// https://www.rfc-editor.org/rfc/rfc9728.html#section-4
+	protected_resources: v.array(webUriSchema).optional(),
+
+	// https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-00.html
+	client_id_metadata_document_supported: v.boolean().optional(),
+});
+
+export type OAuthAuthorizationServerMetadata = v.Infer<typeof oauthAuthorizationServerMetadataSchema>;
+
+export const oauthAuthorizationServerMetadataValidator = oauthAuthorizationServerMetadataSchema.chain(
+	(data) => {
+		if (data.require_pushed_authorization_requests && !data.pushed_authorization_request_endpoint) {
+			return v.err({
+				message: `"pushed_authorization_request_endpoint" required when "require_pushed_authorization_requests" is true`,
+				path: ['pushed_authorization_request_endpoint'],
+			});
+		}
+
+		if (data.response_types_supported && !data.response_types_supported.includes('code')) {
+			return v.err({
+				message: `response type "code" is required`,
+				path: ['response_types_supported'],
+			});
+		}
+
+		if (data.token_endpoint_auth_signing_alg_values_supported?.includes('none')) {
+			// https://openid.net/specs/openid-connect-discovery-1_0.html#rfc.section.3
+			// > The value `none` MUST NOT be used.
+			return v.err({
+				message: `client authentication method "none" is not allowed`,
+				path: ['token_endpoint_auth_signing_alg_values_supported'],
+			});
+		}
+
+		return v.ok(data);
+	},
+);

package/lib/schemas/oauth-client-id-discoverable.ts

@@ -0,0 +1,53 @@
+import * as v from '@badrap/valita';
+
+import { oauthClientIdSchema } from './oauth-client-id.js';
+import { httpsUriSchema } from './uri.js';
+import { extractUrlPath, isHostnameIP } from './utils.js';
+
+/**
+ * @see {@link https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-00.html}
+ */
+export const oauthClientIdDiscoverableSchema = v.string().chain((input, options) => {
+	// first validate as base client ID
+	const clientIdResult = oauthClientIdSchema.try(input, options);
+	if (!clientIdResult.ok) {
+		return clientIdResult;
+	}
+
+	// then validate as https URI
+	const httpsResult = httpsUriSchema.try(input, options);
+	if (!httpsResult.ok) {
+		return httpsResult;
+	}
+
+	const url = new URL(input);
+
+	if (url.username || url.password) {
+		return v.err(`client ID must not contain credentials`);
+	}
+
+	if (url.hash) {
+		return v.err(`client ID must not contain a fragment`);
+	}
+
+	if (url.pathname === '/') {
+		return v.err(`client ID must contain a path component (e.g. "/client-metadata.json")`);
+	}
+
+	if (url.pathname.endsWith('/')) {
+		return v.err(`client ID path must not end with a trailing slash`);
+	}
+
+	if (isHostnameIP(url.hostname)) {
+		return v.err(`client ID hostname must not be an IP address`);
+	}
+
+	// URL constructor normalizes the URL, so we extract the path manually to
+	// avoid normalization, then compare it to the normalized path to ensure
+	// that the URL does not contain path traversal or other unexpected characters
+	if (extractUrlPath(input) !== url.pathname) {
+		return v.err(`client ID must be in canonical form ("${url.href}", got "${input}")`);
+	}
+
+	return v.ok(input);
+});

package/lib/schemas/oauth-client-id.ts

@@ -0,0 +1,6 @@
+import * as v from '@badrap/valita';
+
+/** base OAuth client ID (any non-empty string) */
+export const oauthClientIdSchema = v.string().assert((input) => input.length > 0, `must not be empty`);
+
+export type OAuthClientId = v.Infer<typeof oauthClientIdSchema>;

package/lib/schemas/oauth-client-metadata.ts

@@ -0,0 +1,83 @@
+import * as v from '@badrap/valita';
+
+import { jwksPubSchema } from './jwks.js';
+import { oauthClientIdSchema } from './oauth-client-id.js';
+import { oauthEndpointAuthMethodSchema } from './oauth-endpoint-auth-method.js';
+import { oauthGrantTypeSchema } from './oauth-grant-type.js';
+import { oauthRedirectUriSchema } from './oauth-redirect-uri.js';
+import { oauthResponseTypeSchema } from './oauth-response-type.js';
+import { oauthScopeSchema } from './oauth-scope.js';
+import { webUriSchema } from './uri.js';
+
+const oauthApplicationTypeSchema = v.union(v.literal('web'), v.literal('native'));
+
+const oauthSubjectTypeSchema = v.union(v.literal('public'), v.literal('pairwise'));
+
+// simple email validation
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * base OAuth client metadata schema.
+ *
+ * @see {@link https://openid.net/specs/openid-connect-registration-1_0.html}
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7591}
+ */
+export const oauthClientMetadataSchema = v.object({
+	// https://www.rfc-editor.org/rfc/rfc7591.html#section-2
+	redirect_uris: v
+		.array(oauthRedirectUriSchema)
+		.assert((arr) => arr.length > 0, `must have at least one redirect URI`),
+	response_types: v.array(oauthResponseTypeSchema).optional(),
+	// > If omitted, the default is that the client will use only the "code"
+	// > response type.
+	// .optional((): OAuthResponseType[] => ['code'])
+	grant_types: v.array(oauthGrantTypeSchema).optional(),
+	// > If omitted, the default behavior is that the client will use only the
+	// > "authorization_code" Grant Type.
+	// .optional((): OAuthGrantType[] => ['authorization_code']),
+	scope: oauthScopeSchema.optional(),
+	// https://www.rfc-editor.org/rfc/rfc7591.html#section-2
+	token_endpoint_auth_method: oauthEndpointAuthMethodSchema.optional(),
+	// > If unspecified or omitted, the default is "client_secret_basic" [...].
+	// .optional((): OAuthEndpointAuthMethod => 'client_secret_basic'),
+	token_endpoint_auth_signing_alg: v.string().optional(),
+	userinfo_signed_response_alg: v.string().optional(),
+	userinfo_encrypted_response_alg: v.string().optional(),
+	jwks_uri: webUriSchema.optional(),
+	jwks: jwksPubSchema.optional(),
+	application_type: oauthApplicationTypeSchema.optional(),
+	// .optional((): OAuthApplicationType => 'web'),
+	subject_type: oauthSubjectTypeSchema.optional(),
+	// .optional((): OAuthSubjectType => 'public'),
+	request_object_signing_alg: v.string().optional(),
+	id_token_signed_response_alg: v.string().optional(),
+	authorization_signed_response_alg: v.string().optional(),
+	authorization_encrypted_response_enc: v.literal('A128CBC-HS256').optional(),
+	authorization_encrypted_response_alg: v.string().optional(),
+	client_id: oauthClientIdSchema.optional(),
+	client_name: v.string().optional(),
+	client_uri: webUriSchema.optional(),
+	policy_uri: webUriSchema.optional(),
+	tos_uri: webUriSchema.optional(),
+	logo_uri: webUriSchema.optional(),
+
+	/**
+	 * default Maximum Authentication Age. specifies that the End-User MUST be
+	 * actively authenticated if the End-User was authenticated longer ago than
+	 * the specified number of seconds. the max_age request parameter overrides
+	 * this default value. if omitted, no default Maximum Authentication Age is
+	 * specified.
+	 */
+	default_max_age: v.number().optional(),
+	require_auth_time: v.boolean().optional(),
+	contacts: v.array(v.string().assert((s) => EMAIL_RE.test(s), `must be a valid email`)).optional(),
+	tls_client_certificate_bound_access_tokens: v.boolean().optional(),
+
+	// https://datatracker.ietf.org/doc/html/rfc9449#section-5.2
+	dpop_bound_access_tokens: v.boolean().optional(),
+
+	// https://datatracker.ietf.org/doc/html/rfc9396#section-14.5
+	authorization_details_types: v.array(v.string()).optional(),
+});
+
+export type OAuthClientMetadata = v.Infer<typeof oauthClientMetadataSchema>;

package/lib/schemas/oauth-code-challenge-method.ts

@@ -0,0 +1,5 @@
+import * as v from '@badrap/valita';
+
+export const oauthCodeChallengeMethodSchema = v.union(v.literal('S256'), v.literal('plain'));
+
+export type OAuthCodeChallengeMethod = v.Infer<typeof oauthCodeChallengeMethodSchema>;

package/lib/schemas/oauth-endpoint-auth-method.ts

@@ -0,0 +1,13 @@
+import * as v from '@badrap/valita';
+
+export const oauthEndpointAuthMethodSchema = v.union(
+	v.literal('client_secret_basic'),
+	v.literal('client_secret_jwt'),
+	v.literal('client_secret_post'),
+	v.literal('none'),
+	v.literal('private_key_jwt'),
+	v.literal('self_signed_tls_client_auth'),
+	v.literal('tls_client_auth'),
+);
+
+export type OAuthEndpointAuthMethod = v.Infer<typeof oauthEndpointAuthMethodSchema>;

package/lib/schemas/oauth-grant-type.ts

@@ -0,0 +1,13 @@
+import * as v from '@badrap/valita';
+
+export const oauthGrantTypeSchema = v.union(
+	v.literal('authorization_code'),
+	v.literal('implicit'),
+	v.literal('refresh_token'),
+	v.literal('password'), // not part of OAuth 2.1
+	v.literal('client_credentials'),
+	v.literal('urn:ietf:params:oauth:grant-type:jwt-bearer'),
+	v.literal('urn:ietf:params:oauth:grant-type:saml2-bearer'),
+);
+
+export type OAuthGrantType = v.Infer<typeof oauthGrantTypeSchema>;

package/lib/schemas/oauth-issuer-identifier.ts

@@ -0,0 +1,30 @@
+import * as v from '@badrap/valita';
+
+import { webUriSchema } from './uri.js';
+
+export const oauthIssuerIdentifierSchema = webUriSchema.chain((input) => {
+	// validate the issuer (MIX-UP attacks)
+
+	if (input.endsWith('/')) {
+		return v.err(`issuer URL must not end with a slash`);
+	}
+
+	const url = new URL(input);
+
+	if (url.username || url.password) {
+		return v.err(`issuer URL must not contain a username or password`);
+	}
+
+	if (url.hash || url.search) {
+		return v.err(`issuer URL must not contain a query or fragment`);
+	}
+
+	const canonicalValue = url.pathname === '/' ? url.origin : url.href;
+	if (input !== canonicalValue) {
+		return v.err(`issuer URL must be in the canonical form`);
+	}
+
+	return v.ok(input);
+});
+
+export type OAuthIssuerIdentifier = v.Infer<typeof oauthIssuerIdentifierSchema>;

package/lib/schemas/oauth-par-response.ts

@@ -0,0 +1,10 @@
+import * as v from '@badrap/valita';
+
+const isPositiveInteger = (n: number): boolean => Number.isInteger(n) && n > 0;
+
+export const oauthParResponseSchema = v.object({
+	request_uri: v.string(),
+	expires_in: v.number().assert(isPositiveInteger, `must be a positive integer`),
+});
+
+export type OAuthParResponse = v.Infer<typeof oauthParResponseSchema>;

package/lib/schemas/oauth-prompt.ts

@@ -0,0 +1,20 @@
+import * as v from '@badrap/valita';
+
+/**
+ * OAuth prompt mode values.
+ *
+ * - `none`: only succeed if user already authorized this client on this device
+ * - `login`: force re-authentication
+ * - `consent`: force re-consent
+ * - `select_account`: force account selection
+ * - `create`: force user registration screen
+ */
+export const oauthPromptSchema = v.union(
+	v.literal('none'),
+	v.literal('login'),
+	v.literal('consent'),
+	v.literal('select_account'),
+	v.literal('create'),
+);
+
+export type OAuthPrompt = v.Infer<typeof oauthPromptSchema>;

package/lib/schemas/oauth-protected-resource-metadata.ts

@@ -0,0 +1,89 @@
+import * as v from '@badrap/valita';
+
+import { oauthIssuerIdentifierSchema } from './oauth-issuer-identifier.js';
+import { webUriSchema } from './uri.js';
+
+export const oauthBearerMethodSchema = v.union(v.literal('header'), v.literal('body'), v.literal('query'));
+
+export type OAuthBearerMethod = v.Infer<typeof oauthBearerMethodSchema>;
+
+/**
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-3.2}
+ */
+export const oauthProtectedResourceMetadataSchema = v.object({
+	/**
+	 * REQUIRED. the protected resource's resource identifier, which is a URL that
+	 * uses the https scheme and has no query or fragment components.
+	 */
+	resource: webUriSchema,
+
+	/**
+	 * OPTIONAL. JSON array containing a list of OAuth authorization server issuer
+	 * identifiers, as defined in RFC8414, for authorization servers that can be
+	 * used with this protected resource.
+	 */
+	authorization_servers: v.array(oauthIssuerIdentifierSchema).optional(),
+
+	/**
+	 * OPTIONAL. URL of the protected resource's JWK Set document.
+	 */
+	jwks_uri: webUriSchema.optional(),
+
+	/**
+	 * RECOMMENDED. JSON array containing a list of the OAuth 2.0 scope values that
+	 * are used in authorization requests to request access to this protected resource.
+	 */
+	scopes_supported: v.array(v.string()).optional(),
+
+	/**
+	 * OPTIONAL. JSON array containing a list of the supported methods of sending
+	 * an OAuth 2.0 Bearer Token to the protected resource.
+	 */
+	bearer_methods_supported: v.array(oauthBearerMethodSchema).optional(),
+
+	/**
+	 * OPTIONAL. JSON array containing a list of the JWS signing algorithms
+	 * supported by the protected resource for signing resource responses.
+	 */
+	resource_signing_alg_values_supported: v.array(v.string()).optional(),
+
+	/**
+	 * OPTIONAL. URL of a page containing human-readable information that
+	 * developers might want or need to know when using the protected resource.
+	 */
+	resource_documentation: webUriSchema.optional(),
+
+	/**
+	 * OPTIONAL. URL that the protected resource provides to read about the
+	 * protected resource's requirements on how the client can use the data.
+	 */
+	resource_policy_uri: webUriSchema.optional(),
+
+	/**
+	 * OPTIONAL. URL that the protected resource provides to read about the
+	 * protected resource's terms of service.
+	 */
+	resource_tos_uri: webUriSchema.optional(),
+});
+
+export const oauthProtectedResourceMetadataValidator = oauthProtectedResourceMetadataSchema.chain((data) => {
+	const url = new URL(data.resource);
+
+	if (url.search) {
+		return v.err({
+			message: `resource URL must not contain query parameters`,
+			path: ['resource'],
+		});
+	}
+
+	if (url.hash) {
+		return v.err({
+			message: `resource URL must not contain a fragment`,
+			path: ['resource'],
+		});
+	}
+
+	return v.ok(data);
+});
+
+export type OAuthProtectedResourceMetadata = v.Infer<typeof oauthProtectedResourceMetadataSchema>;

package/lib/schemas/oauth-redirect-uri.ts

@@ -0,0 +1,42 @@
+import * as v from '@badrap/valita';
+
+import { httpsUriSchema, loopbackUriSchema, privateUseUriSchema } from './uri.js';
+
+/**
+ * this is a loopback URI with the additional restriction that the hostname
+ * `localhost` is not allowed.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc8252#section-8.3 Loopback Redirect Considerations} RFC8252
+ *
+ * > While redirect URIs using localhost (i.e.,
+ * > "http://localhost:{port}/{path}") function similarly to loopback IP
+ * > redirects described in Section 7.3, the use of localhost is NOT
+ * > RECOMMENDED. Specifying a redirect URI with the loopback IP literal rather
+ * > than localhost avoids inadvertently listening on network interfaces other
+ * > than the loopback interface. It is also less susceptible to client-side
+ * > firewalls and misconfigured host name resolution on the user's device.
+ */
+export const loopbackRedirectUriSchema = loopbackUriSchema.chain((input) => {
+	if (input.startsWith('http://localhost')) {
+		return v.err(
+			`use of "localhost" hostname is not allowed (RFC 8252), use a loopback IP such as "127.0.0.1" instead`,
+		);
+	}
+	return v.ok(input);
+});
+
+export type LoopbackRedirectUri = v.Infer<typeof loopbackRedirectUriSchema>;
+
+export const oauthRedirectUriSchema = v.string().chain((input, options) => {
+	if (input.startsWith('http://')) {
+		return loopbackRedirectUriSchema.try(input, options);
+	}
+
+	if (input.startsWith('https://')) {
+		return httpsUriSchema.try(input, options);
+	}
+
+	return privateUseUriSchema.try(input, options);
+});
+
+export type OAuthRedirectUri = v.Infer<typeof oauthRedirectUriSchema>;

package/lib/schemas/oauth-response-mode.ts

@@ -0,0 +1,9 @@
+import * as v from '@badrap/valita';
+
+export const oauthResponseModeSchema = v.union(
+	v.literal('query'),
+	v.literal('fragment'),
+	v.literal('form_post'),
+);
+
+export type OAuthResponseMode = v.Infer<typeof oauthResponseModeSchema>;

package/lib/schemas/oauth-response-type.ts

@@ -0,0 +1,17 @@
+import * as v from '@badrap/valita';
+
+export const oauthResponseTypeSchema = v.union(
+	// OAuth2 (https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-10#section-4.1.1)
+	v.literal('code'), // Authorization Code Grant
+	v.literal('token'), // Implicit Grant
+
+	// OIDC (https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html)
+	v.literal('none'),
+	v.literal('code id_token token'),
+	v.literal('code id_token'),
+	v.literal('code token'),
+	v.literal('id_token token'),
+	v.literal('id_token'),
+);
+
+export type OAuthResponseType = v.Infer<typeof oauthResponseTypeSchema>;

package/lib/schemas/oauth-scope.ts

@@ -0,0 +1,18 @@
+import * as v from '@badrap/valita';
+
+// scope       = scope-token *( SP scope-token )
+// scope-token = 1*( %x21 / %x23-5B / %x5D-7E )
+// https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-11#section-1.4.1
+export const OAUTH_SCOPE_REGEXP = /^[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*$/;
+
+export const isOAuthScope = (input: string): boolean => OAUTH_SCOPE_REGEXP.test(input);
+
+/**
+ * a (single) space separated list of non empty printable ASCII char string
+ * (except backslash and double quote).
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-11#section-1.4.1}
+ */
+export const oauthScopeSchema = v.string().assert(isOAuthScope, `invalid OAuth scope`);
+
+export type OAuthScope = v.Infer<typeof oauthScopeSchema>;

package/lib/schemas/oauth-token-response.ts

@@ -0,0 +1,22 @@
+import * as v from '@badrap/valita';
+
+import { oauthAuthorizationDetailsSchema } from './oauth-authorization-details.js';
+import { oauthTokenTypeSchema } from './oauth-token-type.js';
+
+/**
+ * @see {@link https://www.rfc-editor.org/rfc/rfc6749.html#section-5.1 | RFC 6749 (OAuth2), Section 5.1}
+ */
+export const oauthTokenResponseSchema = v.object({
+	// https://www.rfc-editor.org/rfc/rfc6749.html#section-5.1
+	access_token: v.string(),
+	token_type: oauthTokenTypeSchema,
+	scope: v.string().optional(),
+	refresh_token: v.string().optional(),
+	expires_in: v.number().optional(),
+	// https://openid.net/specs/openid-connect-core-1_0.html#TokenResponse
+	id_token: v.string().optional(),
+	// https://datatracker.ietf.org/doc/html/rfc9396#name-enriched-authorization-deta
+	authorization_details: oauthAuthorizationDetailsSchema.optional(),
+});
+
+export type OAuthTokenResponse = v.Infer<typeof oauthTokenResponseSchema>;

package/lib/schemas/oauth-token-type.ts

@@ -0,0 +1,15 @@
+import * as v from '@badrap/valita';
+
+/** token type (case-insensitive input, normalized output) */
+export const oauthTokenTypeSchema = v.string().chain((input) => {
+	const lower = input.toLowerCase();
+	if (lower === 'dpop') {
+		return v.ok('DPoP');
+	}
+	if (lower === 'bearer') {
+		return v.ok('Bearer');
+	}
+	return v.err(`must be "DPoP" or "Bearer"`);
+});
+
+export type OAuthTokenType = v.Infer<typeof oauthTokenTypeSchema>;