@atproto/oauth-types 0.1.0

package/src/oauth-client-id-loopback.ts

@@ -0,0 +1,58 @@
+import { parseOAuthClientIdUrl } from './oauth-client-id-url.js'
+import { OAuthClientId } from './oauth-client-id.js'
+
+export type OAuthClientIdLoopback = OAuthClientId &
+  `http://localhost${'' | `${'/' | '?' | '#'}${string}`}`
+
+export function isOAuthClientIdLoopback<C extends OAuthClientId>(
+  clientId: C,
+): clientId is C & OAuthClientIdLoopback {
+  try {
+    parseOAuthLoopbackClientId(clientId)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function parseOAuthLoopbackClientId(clientId: OAuthClientId): URL {
+  const url = parseOAuthClientIdUrl(clientId)
+
+  // Optimization: cheap checks first
+
+  if (url.protocol !== 'http:') {
+    throw new TypeError('Loopback ClientID must use the "http:" protocol')
+  }
+
+  if (url.hostname !== 'localhost') {
+    throw new TypeError('Loopback ClientID must use the "localhost" hostname')
+  }
+
+  if (url.hash) {
+    throw new TypeError('Loopback ClientID must not contain a fragment')
+  }
+
+  if (url.username || url.password) {
+    throw new TypeError('Loopback ClientID must not contain credentials')
+  }
+
+  if (url.port) {
+    throw new TypeError('Loopback ClientID must not contain a port')
+  }
+
+  // Note: url.pathname === '/' is allowed for loopback URIs
+
+  if (url.pathname !== '/' && url.pathname.endsWith('/')) {
+    throw new TypeError('Loopback ClientID must not end with a trailing slash')
+  }
+
+  if (url.pathname.includes('//')) {
+    throw new TypeError(
+      `Loopback ClientID must not contain any double slashes in its path`,
+    )
+  }
+
+  // Note: Query string is allowed
+
+  return url
+}

package/src/oauth-client-id-url.ts

@@ -0,0 +1,25 @@
+import { OAuthClientId } from './oauth-client-id.js'
+
+export function parseOAuthClientIdUrl(clientId: OAuthClientId): URL {
+  if (clientId.endsWith('/')) {
+    throw new TypeError('ClientID must not end with a trailing slash')
+  }
+
+  const url = new URL(clientId)
+
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new TypeError('ClientID must use the "https:" or "http:" protocol')
+  }
+
+  url.searchParams.sort()
+
+  // URL constructor normalizes the URL, so we need to compare the canonical form
+  const canonicalUri = url.pathname === '/' ? url.origin + url.search : url.href
+  if (canonicalUri !== clientId) {
+    throw new TypeError(
+      `ClientID must be in canonical form ("${canonicalUri}", got "${clientId}")`,
+    )
+  }
+
+  return url
+}

package/src/oauth-client-id.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod'
+
+export const oauthClientIdSchema = z.string().min(1)
+export type OAuthClientId = z.infer<typeof oauthClientIdSchema>

package/src/oauth-client-identification.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod'
+
+import { oauthClientIdSchema } from './oauth-client-id.js'
+import { oauthClientCredentialsSchema } from './oauth-client-credentials.js'
+
+export const oauthClientIdentificationSchema = z.union([
+  oauthClientCredentialsSchema,
+  // Must be last since it is less specific
+  z.object({ client_id: oauthClientIdSchema }),
+])
+
+export type OAuthClientIdentification = z.infer<
+  typeof oauthClientIdentificationSchema
+>

package/src/oauth-client-metadata.ts

@@ -0,0 +1,75 @@
+import { jwksPubSchema } from '@atproto/jwk'
+import { z } from 'zod'
+
+import { oauthClientIdSchema } from './oauth-client-id.js'
+import { oauthEndpointAuthMethod } from './oauth-endpoint-auth-method.js'
+import { oauthGrantTypeSchema } from './oauth-grant-type.js'
+import { oauthResponseTypeSchema } from './oauth-response-type.js'
+
+// https://openid.net/specs/openid-connect-registration-1_0.html
+// https://datatracker.ietf.org/doc/html/rfc7591
+export const oauthClientMetadataSchema = z.object({
+  redirect_uris: z.array(z.string().url()).nonempty(),
+  response_types: z
+    .array(oauthResponseTypeSchema)
+    .nonempty()
+    // > If omitted, the default is that the client will use only the "code"
+    // > response type.
+    .default(['code']),
+  grant_types: z
+    .array(oauthGrantTypeSchema)
+    .nonempty()
+    // > If omitted, the default behavior is that the client will use only the
+    // > "authorization_code" Grant Type.
+    .default(['authorization_code']),
+  scope: z.string().optional(),
+  token_endpoint_auth_method: oauthEndpointAuthMethod
+    .default('none')
+    .optional(),
+  token_endpoint_auth_signing_alg: z.string().optional(),
+  introspection_endpoint_auth_method: oauthEndpointAuthMethod.optional(),
+  introspection_endpoint_auth_signing_alg: z.string().optional(),
+  revocation_endpoint_auth_method: oauthEndpointAuthMethod.optional(),
+  revocation_endpoint_auth_signing_alg: z.string().optional(),
+  pushed_authorization_request_endpoint_auth_method:
+    oauthEndpointAuthMethod.optional(),
+  pushed_authorization_request_endpoint_auth_signing_alg: z.string().optional(),
+  userinfo_signed_response_alg: z.string().optional(),
+  userinfo_encrypted_response_alg: z.string().optional(),
+  jwks_uri: z.string().url().optional(),
+  jwks: jwksPubSchema.optional(),
+  application_type: z.enum(['web', 'native']).default('web').optional(), // default, per spec, is "web"
+  subject_type: z.enum(['public', 'pairwise']).default('public').optional(),
+  request_object_signing_alg: z.string().optional(),
+  id_token_signed_response_alg: z.string().optional(),
+  authorization_signed_response_alg: z.string().default('RS256').optional(),
+  authorization_encrypted_response_enc: z.enum(['A128CBC-HS256']).optional(),
+  authorization_encrypted_response_alg: z.string().optional(),
+  client_id: oauthClientIdSchema.optional(),
+  client_name: z.string().optional(),
+  client_uri: z.string().url().optional(),
+  policy_uri: z.string().url().optional(),
+  tos_uri: z.string().url().optional(),
+  logo_uri: z.string().url().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: z.number().optional(),
+  require_auth_time: z.boolean().optional(),
+  contacts: z.array(z.string().email()).optional(),
+  tls_client_certificate_bound_access_tokens: z.boolean().optional(),
+
+  // https://datatracker.ietf.org/doc/html/rfc9449#section-5.2
+  dpop_bound_access_tokens: z.boolean().optional(),
+
+  // https://datatracker.ietf.org/doc/html/rfc9396#section-14.5
+  authorization_details_types: z.array(z.string()).optional(),
+})
+
+export type OAuthClientMetadata = z.infer<typeof oauthClientMetadataSchema>
+export type OAuthClientMetadataInput = z.input<typeof oauthClientMetadataSchema>

package/src/oauth-endpoint-auth-method.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod'
+
+export const oauthEndpointAuthMethod = z.enum([
+  'client_secret_basic',
+  'client_secret_jwt',
+  'client_secret_post',
+  'none',
+  'private_key_jwt',
+  'self_signed_tls_client_auth',
+  'tls_client_auth',
+])
+
+export type OauthEndpointAuthMethod = z.infer<typeof oauthEndpointAuthMethod>

package/src/oauth-endpoint-name.ts

@@ -0,0 +1,5 @@
+export type OAuthEndpointName =
+  | 'token'
+  | 'revocation'
+  | 'introspection'
+  | 'pushed_authorization_request'

package/src/oauth-grant-type.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod'
+
+export const oauthGrantTypeSchema = z.enum([
+  'authorization_code',
+  'implicit',
+  'refresh_token',
+  'password', // Not part of OAuth 2.1
+  'client_credentials',
+  'urn:ietf:params:oauth:grant-type:jwt-bearer',
+  'urn:ietf:params:oauth:grant-type:saml2-bearer',
+])
+
+export type OAuthGrantType = z.infer<typeof oauthGrantTypeSchema>

package/src/oauth-issuer-identifier.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod'
+
+// try/catch to support running in a browser, including when process.env is
+// shimmed (e.g. by webpack)
+const ALLOW_INSECURE = (() => {
+  try {
+    const env = process.env.NODE_ENV
+    return env === 'development' || env === 'test'
+  } catch {
+    return false
+  }
+})()
+
+export const oauthIssuerIdentifierSchema = z
+  .string()
+  .url()
+  .superRefine((value, ctx) => {
+    // Validate the issuer (MIX-UP attacks)
+
+    if (value.endsWith('/')) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Issuer URL must not end with a slash',
+      })
+    }
+
+    const url = new URL(value)
+
+    if (url.protocol !== 'https:') {
+      if (ALLOW_INSECURE && url.protocol === 'http:') {
+        // We'll allow HTTP in development mode
+      } else {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: 'Issuer must be an HTTPS URL',
+        })
+      }
+    }
+
+    if (url.username || url.password) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Issuer URL must not contain a username or password',
+      })
+    }
+
+    if (url.hash || url.search) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Issuer URL must not contain a query or fragment',
+      })
+    }
+
+    const canonicalValue = url.pathname === '/' ? url.origin : url.href
+    if (value !== canonicalValue) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Issuer URL must be in the canonical form',
+      })
+    }
+  })

package/src/oauth-par-response.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod'
+
+export const oauthParResponseSchema = z.object({
+  request_uri: z.string(),
+})
+
+export type OAuthParResponse = z.infer<typeof oauthParResponseSchema>

package/src/oauth-protected-resource-metadata.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod'
+
+import { oauthIssuerIdentifierSchema } from './oauth-issuer-identifier.js'
+
+/**
+ * @see {@link https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-05#name-protected-resource-metadata-r}
+ */
+export const oauthProtectedResourceMetadataSchema = z.object({
+  /**
+   * REQUIRED. The protected resource's resource identifier, which is a URL that
+   * uses the https scheme and has no query or fragment components. Using these
+   * well-known resources is described in Section 3.
+   */
+  resource: z.string().url(),
+
+  /**
+   * 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. Protected resources MAY choose not to
+   * advertise some supported authorization servers even when this parameter is
+   * used. In some use cases, the set of authorization servers will not be
+   * enumerable, in which case this metadata parameter would not be used.
+   */
+  authorization_servers: z.array(oauthIssuerIdentifierSchema).optional(),
+
+  /**
+   * OPTIONAL. URL of the protected resource's JWK Set [JWK] document. This
+   * contains public keys belonging to the protected resource, such as signing
+   * key(s) that the resource server uses to sign resource responses. This URL
+   * MUST use the https scheme. When both signing and encryption keys are made
+   * available, a use (public key use) parameter value is REQUIRED for all keys
+   * in the referenced JWK Set to indicate each key's intended usage.
+   */
+  jwks_uri: z.string().url().optional(),
+
+  /**
+   * RECOMMENDED. JSON array containing a list of the OAuth 2.0 [RFC6749] scope
+   * values that are used in authorization requests to request access to this
+   * protected resource. Protected resources MAY choose not to advertise some
+   * scope values supported even when this parameter is used.
+   */
+  scopes_supported: z.array(z.string()).optional(),
+
+  /**
+   * OPTIONAL. JSON array containing a list of the supported methods of sending
+   * an OAuth 2.0 Bearer Token [RFC6750] to the protected resource. Defined
+   * values are ["header", "body", "query"], corresponding to Sections 2.1, 2.2,
+   * and 2.3 of RFC 6750.
+   */
+  bearer_methods_supported: z
+    .array(z.enum(['header', 'body', 'query']))
+    .optional(),
+
+  /**
+   * OPTIONAL. JSON array containing a list of the JWS [JWS] signing algorithms
+   * (alg values) [JWA] supported by the protected resource for signing resource
+   * responses, for instance, as described in [FAPI.MessageSigning]. No default
+   * algorithms are implied if this entry is omitted. The value none MUST NOT be
+   * used.
+   */
+  resource_signing_alg_values_supported: z.array(z.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: z.string().url().optional(),
+
+  /**
+   * OPTIONAL. URL that the protected resource provides to read about the
+   * protected resource's requirements on how the client can use the data
+   * provided by the protected resource
+   */
+  resource_policy_uri: z.string().url().optional(),
+
+  /**
+   * OPTIONAL. URL that the protected resource provides to read about the
+   * protected resource's terms of service
+   */
+  resource_tos_uri: z.string().url().optional(),
+})
+
+export type OAuthProtectedResourceMetadata = z.infer<
+  typeof oauthProtectedResourceMetadataSchema
+>

package/src/oauth-response-mode.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod'
+
+export const oauthResponseModeSchema = z.enum([
+  'query',
+  'fragment',
+  'form_post',
+])
+
+export type OAuthResponseMode = z.infer<typeof oauthResponseModeSchema>

package/src/oauth-response-type.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod'
+
+export const oauthResponseTypeSchema = z.enum([
+  // OAuth
+  'code', // Authorization Code Grant
+  'token', // Implicit Grant
+
+  // OpenID
+  'none',
+  'code id_token token',
+  'code id_token',
+  'code token',
+  'id_token token',
+  'id_token',
+])
+
+export type OAuthResponseType = z.infer<typeof oauthResponseTypeSchema>

package/src/oauth-token-response.ts

@@ -0,0 +1,29 @@
+import { signedJwtSchema } from '@atproto/jwk'
+import { z } from 'zod'
+
+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 = z
+  .object({
+    access_token: z.string(),
+    token_type: oauthTokenTypeSchema,
+    issuer: z.string().url().optional(),
+    sub: z.string().optional(),
+    scope: z.string().optional(),
+    id_token: signedJwtSchema.optional(),
+    refresh_token: z.string().optional(),
+    expires_in: z.number().optional(),
+    authorization_details: oauthAuthorizationDetailsSchema.optional(),
+  })
+  // https://www.rfc-editor.org/rfc/rfc6749.html#section-5.1
+  // > The client MUST ignore unrecognized value names in the response.
+  .passthrough()
+
+/**
+ * @see {@link oauthTokenResponseSchema}
+ */
+export type OAuthTokenResponse = z.infer<typeof oauthTokenResponseSchema>

package/src/oauth-token-type.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod'
+
+// Case insensitive input, normalized output
+export const oauthTokenTypeSchema = z.union([
+  z
+    .string()
+    .regex(/^DPoP$/i)
+    .transform(() => 'DPoP' as const),
+  z
+    .string()
+    .regex(/^Bearer$/i)
+    .transform(() => 'Bearer' as const),
+])
+
+export type OAuthTokenType = z.infer<typeof oauthTokenTypeSchema>

package/src/oidc-claims-parameter.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod'
+
+export const oidcClaimsParameterSchema = z.enum([
+  // https://openid.net/specs/openid-provider-authentication-policy-extension-1_0.html#rfc.section.5.2
+  // if client metadata "require_auth_time" is true, this *must* be provided
+  'auth_time',
+
+  // OIDC
+  'nonce',
+  'acr',
+
+  // OpenID: "profile" scope
+  'name',
+  'family_name',
+  'given_name',
+  'middle_name',
+  'nickname',
+  'preferred_username',
+  'gender',
+  'picture',
+  'profile',
+  'website',
+  'birthdate',
+  'zoneinfo',
+  'locale',
+  'updated_at',
+
+  // OpenID: "email" scope
+  'email',
+  'email_verified',
+
+  // OpenID: "phone" scope
+  'phone_number',
+  'phone_number_verified',
+
+  // OpenID: "address" scope
+  'address',
+])
+
+export type OidcClaimsParameter = z.infer<typeof oidcClaimsParameterSchema>

package/src/oidc-claims-properties.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod'
+
+const oidcClaimsValueSchema = z.union([z.string(), z.number(), z.boolean()])
+
+export const oidcClaimsPropertiesSchema = z.object({
+  essential: z.boolean().optional(),
+  value: oidcClaimsValueSchema.optional(),
+  values: z.array(oidcClaimsValueSchema).optional(),
+})
+
+export type OidcClaimsProperties = z.infer<typeof oidcClaimsPropertiesSchema>

package/src/oidc-entity-type.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod'
+
+export const oidcEntityTypeSchema = z.enum(['userinfo', 'id_token'])
+
+export type OidcEntityType = z.infer<typeof oidcEntityTypeSchema>

package/src/util.ts

@@ -0,0 +1,20 @@
+export function isIP(hostname: string) {
+  // IPv4
+  if (hostname.match(/^\d+\.\d+\.\d+\.\d+$/)) return true
+
+  // IPv6
+  if (hostname.startsWith('[') && hostname.endsWith(']')) return true
+
+  return false
+}
+
+export type LoopbackHost = 'localhost' | '127.0.0.1' | '[::1]'
+
+export function isLoopbackHost(host: unknown): host is LoopbackHost {
+  return host === 'localhost' || host === '127.0.0.1' || host === '[::1]'
+}
+
+export function isLoopbackUrl(input: URL | string): boolean {
+  const url = typeof input === 'string' ? new URL(input) : input
+  return isLoopbackHost(url.hostname)
+}

package/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../tsconfig/isomorphic.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["./src"]
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "include": [],
+  "references": [{ "path": "./tsconfig.build.json" }]
+}