@atproto/oauth-provider 0.10.1 → 0.11.0

package/src/lexicon/lexicon-manager.ts

@@ -0,0 +1,116 @@
+import { LexPermissionSet } from '@atproto/lexicon'
+import {
+  LexiconResolutionError,
+  LexiconResolver,
+} from '@atproto/lexicon-resolver'
+import { IncludeScope, Nsid } from '@atproto/oauth-scopes'
+import { LexiconGetter } from './lexicon-getter.js'
+import { LexiconStore } from './lexicon-store.js'
+
+export * from './lexicon-store.js'
+
+export class LexiconManager {
+  protected readonly lexiconGetter: LexiconGetter
+
+  constructor(store: LexiconStore, resolveLexicon?: LexiconResolver) {
+    this.lexiconGetter = new LexiconGetter(store, resolveLexicon)
+  }
+
+  public async getPermissionSetsFromScope(scope?: string) {
+    const { includeScopes } = parseScope(scope)
+    return this.extractPermissionSets(includeScopes)
+  }
+
+  /**
+   * Transforms a scope string from an authorization request into a scope
+   * composed solely of granular permission scopes, transforming any NSID
+   * into its corresponding permission scopes.
+   */
+  public async buildTokenScope(scope: string): Promise<string> {
+    const { includeScopes, otherScopes } = parseScope(scope)
+
+    // If the scope does not contain any "include:<nsid>" scopes, return it as-is.
+    if (!includeScopes.length) return scope
+
+    const permissionSets = await this.extractPermissionSets(includeScopes)
+
+    return Array.from(includeScopes)
+      .flatMap(nsidToPermissionScopes, permissionSets)
+      .concat(otherScopes)
+      .join(' ')
+  }
+
+  /**
+   * Given a list of scope values, extract those that are NSIDs and return their
+   * corresponding permission sets.
+   */
+  protected async extractPermissionSets(includeScopes: IncludeScope[]) {
+    const nsids = extractNsids(includeScopes)
+    return this.getPermissionSets(nsids)
+  }
+
+  protected async getPermissionSets(nsids: Set<Nsid>) {
+    return new Map<string, LexPermissionSet>(
+      await Promise.all(Array.from(nsids, this.getPermissionSetEntry, this)),
+    )
+  }
+
+  protected async getPermissionSetEntry(
+    nsid: Nsid,
+  ): Promise<[nsid: Nsid, permissionSet: LexPermissionSet]> {
+    const permissionSet = await this.getPermissionSet(nsid)
+    return [nsid, permissionSet]
+  }
+
+  protected async getPermissionSet(nsid: Nsid): Promise<LexPermissionSet> {
+    const { lexicon } = await this.lexiconGetter.get(nsid)
+
+    if (!lexicon) {
+      throw LexiconResolutionError.from(nsid)
+    }
+
+    if (lexicon.defs.main?.type !== 'permission-set') {
+      const description = 'Lexicon document is not a permission set'
+      throw LexiconResolutionError.from(nsid, description)
+    }
+
+    return lexicon.defs.main
+  }
+}
+
+function parseScope(scope?: string) {
+  const includeScopes: IncludeScope[] = []
+  const otherScopes: string[] = []
+
+  if (scope) {
+    for (const scopeValue of scope.split(' ')) {
+      const parsed = IncludeScope.fromString(scopeValue)
+      if (parsed) {
+        includeScopes.push(parsed)
+      } else {
+        otherScopes.push(scopeValue)
+      }
+    }
+  }
+
+  return {
+    includeScopes,
+    otherScopes,
+  }
+}
+
+function extractNsids(includeScopes: IncludeScope[]): Set<Nsid> {
+  return new Set(Array.from(includeScopes, extractNsid))
+}
+
+function extractNsid(nsidScope: IncludeScope): Nsid {
+  return nsidScope.nsid
+}
+
+export function nsidToPermissionScopes(
+  this: Map<string, LexPermissionSet>,
+  includeScope: IncludeScope,
+): string[] {
+  const permissionSet = this.get(includeScope.nsid)!
+  return includeScope.toPermissions(permissionSet).map(String)
+}

package/src/lexicon/lexicon-store.ts

@@ -0,0 +1,36 @@
+import { LexiconDoc } from '@atproto/lexicon'
+import { Awaitable, buildInterfaceChecker } from '../lib/util/type.js'
+import { LexiconData } from './lexicon-data.js'
+
+export type { Awaitable, LexiconData, LexiconDoc }
+
+export interface LexiconStore {
+  findLexicon(nsid: string): Awaitable<LexiconData | null>
+  storeLexicon(nsid: string, data: LexiconData): Awaitable<void>
+  deleteLexicon(nsid: string): Awaitable<void>
+}
+
+export const isLexiconStore = buildInterfaceChecker<LexiconStore>([
+  'findLexicon',
+  'storeLexicon',
+  'deleteLexicon',
+])
+
+export function ifLexiconStore<V extends Partial<LexiconStore>>(
+  implementation?: V,
+): (V & LexiconStore) | undefined {
+  if (implementation && isLexiconStore(implementation)) {
+    return implementation
+  }
+
+  return undefined
+}
+
+export function asLexiconStore<V extends Partial<LexiconStore>>(
+  implementation?: V,
+): V & LexiconStore {
+  const store = ifLexiconStore(implementation)
+  if (store) return store
+
+  throw new Error('Invalid LexiconStore implementation')
+}

package/src/lib/html/hydration-data.ts

@@ -14,7 +14,6 @@ export function* hydrationDataGenerator(
   }
   // The script tag is removed after the data is assigned to the global
   // variables to prevent other scripts from reading the values. The "app"
-  // script will read the global variable and then unset it. See
-  // `readBackendData()` in "src/assets/app/backend-data.ts".
+  // script will read the global variable and then unset it.
   yield js`document.currentScript.remove();`
 }

package/src/lib/nsid.ts

@@ -0,0 +1,10 @@
+import { NSID } from '@atproto/syntax'
+export { NSID }
+
+export function parseNSID(value: string): NSID | null {
+  try {
+    return NSID.parse(value)
+  } catch {
+    return null
+  }
+}

package/src/lib/util/locale.ts

@@ -5,14 +5,8 @@ export const localeSchema = z
   .regex(/^[a-z]{2,3}(-[A-Z]{2})?$/, 'Invalid locale')
 export type Locale = z.infer<typeof localeSchema>
 
-export const multiLangStringSchema = z.intersection(
-  z.object({ en: z.string() }), // en is required
-  z.record(localeSchema, z.string().optional()),
+export const multiLangStringSchema = z.record(
+  localeSchema,
+  z.string().optional(),
 )
 export type MultiLangString = z.infer<typeof multiLangStringSchema>
-
-export const localizedStringSchema = z.union([
-  z.string(),
-  multiLangStringSchema,
-])
-export type LocalizedString = z.infer<typeof localizedStringSchema>

package/src/oauth-provider.ts

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto'
 import type { Redis, RedisOptions } from 'ioredis'
 import { Jwks, Keyset } from '@atproto/jwk'
+import { LexiconResolver } from '@atproto/lexicon-resolver'
 import type { Account } from '@atproto/oauth-provider-api'
 import {
   CLIENT_ASSERTION_TYPE_JWT_BEARER,
@@ -71,11 +72,13 @@ import { InvalidDpopProofError } from './errors/invalid-dpop-proof-error.js'
 import { InvalidGrantError } from './errors/invalid-grant-error.js'
 import { InvalidRequestError } from './errors/invalid-request-error.js'
 import { LoginRequiredError } from './errors/login-required-error.js'
+import { LexiconManager } from './lexicon/lexicon-manager.js'
+import { LexiconStore, asLexiconStore } from './lexicon/lexicon-store.js'
 import { HcaptchaConfig } from './lib/hcaptcha.js'
 import { RequestMetadata } from './lib/http/request.js'
 import { dateToRelativeSeconds } from './lib/util/date.js'
 import { formatError } from './lib/util/error.js'
-import { LocalizedString, MultiLangString } from './lib/util/locale.js'
+import { MultiLangString } from './lib/util/locale.js'
 import { CustomMetadata, buildMetadata } from './metadata/build-metadata.js'
 import { OAuthHooks } from './oauth-hooks.js'
 import {
@@ -117,7 +120,7 @@ export type {
   CustomizationInput,
   ErrorHandler,
   HcaptchaConfig,
-  LocalizedString,
+  LexiconResolver,
   MultiLangString,
   OAuthAuthorizationServerMetadata,
 }
@@ -129,11 +132,6 @@ type OAuthProviderConfig = {
    */
   authenticationMaxAge?: number
 
-  /**
-   * Maximum age an ephemeral session (one where "remember me" was not
-   * checked) can be before requiring re-authentication.
-   */
-
   /**
    * Maximum age access & id tokens can be before requiring a refresh.
    */
@@ -169,6 +167,11 @@ type OAuthProviderConfig = {
    */
   safeFetch?: typeof globalThis.fetch
 
+  /**
+   * A custom ATProto lexicon resolver
+   */
+  lexiconResolver?: LexiconResolver
+
   /**
    * A redis instance to use for replay protection. If not provided, replay
    * protection will use memory storage.
@@ -186,6 +189,7 @@ type OAuthProviderConfig = {
     AccountStore &
       ClientStore &
       DeviceStore &
+      LexiconStore &
       ReplayStore &
       RequestStore &
       TokenStore
@@ -194,6 +198,7 @@ type OAuthProviderConfig = {
   accountStore?: AccountStore
   clientStore?: ClientStore
   deviceStore?: DeviceStore
+  lexiconStore?: LexiconStore
   replayStore?: ReplayStore
   requestStore?: RequestStore
   tokenStore?: TokenStore
@@ -243,6 +248,7 @@ export class OAuthProvider extends OAuthVerifier {
   public readonly accountManager: AccountManager
   public readonly deviceManager: DeviceManager
   public readonly clientManager: ClientManager
+  public readonly lexiconManager: LexiconManager
   public readonly requestManager: RequestManager
   public readonly tokenManager: TokenManager
 
@@ -254,16 +260,18 @@ export class OAuthProvider extends OAuthVerifier {
 
     metadata,
 
+    lexiconResolver,
     safeFetch = safeFetchWrap(),
     store, // compound store implementation
 
-    // Requires stores
+    // Required stores
     accountStore = asAccountStore(store),
     deviceStore = asDeviceStore(store),
+    lexiconStore = asLexiconStore(store),
     tokenStore = asTokenStore(store),
     requestStore = asRequestStore(store),
 
-    // These are optional
+    // Optional stores
     clientStore = ifClientStore(store),
     replayStore = ifReplayStore(store),
 
@@ -322,14 +330,17 @@ export class OAuthProvider extends OAuthVerifier {
       clientJwksCache,
       clientMetadataCache,
     )
+    this.lexiconManager = new LexiconManager(lexiconStore, lexiconResolver)
     this.requestManager = new RequestManager(
       requestStore,
+      this.lexiconManager,
       this.signer,
       this.metadata,
       this.hooks,
     )
     this.tokenManager = new TokenManager(
       tokenStore,
+      this.lexiconManager,
       this.signer,
       this.hooks,
       this.accessTokenMode,
@@ -667,6 +678,16 @@ export class OAuthProvider extends OAuthVerifier {
           loginRequired: session.loginRequired,
           consentRequired: session.consentRequired,
         })),
+        permissionSets: await this.lexiconManager
+          .getPermissionSetsFromScope(parameters.scope)
+          .catch((cause) => {
+            throw new AuthorizationError(
+              parameters,
+              'Unable to retrieve permission sets',
+              'invalid_scope',
+              cause,
+            )
+          }),
       }
     } catch (err) {
       try {

package/src/oauth-store.ts

@@ -6,6 +6,7 @@
 export * from './account/account-store.js'
 export * from './client/client-store.js'
 export * from './device/device-store.js'
+export * from './lexicon/lexicon-store.js'
 export * from './replay/replay-store.js'
 export * from './request/request-store.js'
 export * from './token/token-store.js'

package/src/request/request-manager.ts

@@ -1,6 +1,7 @@
 import { isAtprotoDid } from '@atproto/did'
+import { LexiconResolutionError } from '@atproto/lexicon-resolver'
 import type { Account } from '@atproto/oauth-provider-api'
-import { isValidAtprotoOauthScope } from '@atproto/oauth-scopes'
+import { isAtprotoOauthScope } from '@atproto/oauth-scopes'
 import {
   OAuthAuthorizationRequestParameters,
   OAuthAuthorizationServerMetadata,
@@ -23,6 +24,7 @@ import { InvalidAuthorizationDetailsError } from '../errors/invalid-authorizatio
 import { InvalidGrantError } from '../errors/invalid-grant-error.js'
 import { InvalidRequestError } from '../errors/invalid-request-error.js'
 import { InvalidScopeError } from '../errors/invalid-scope-error.js'
+import { LexiconManager } from '../lexicon/lexicon-manager.js'
 import { RequestMetadata } from '../lib/http/request.js'
 import { callAsync } from '../lib/util/function.js'
 import { OAuthHooks } from '../oauth-hooks.js'
@@ -43,6 +45,7 @@ import {
 export class RequestManager {
   constructor(
     protected readonly store: RequestStore,
+    protected readonly lexiconManager: LexiconManager,
     protected readonly signer: Signer,
     protected readonly metadata: OAuthAuthorizationServerMetadata,
     protected readonly hooks: OAuthHooks,
@@ -171,17 +174,16 @@ export class RequestManager {
     // > (Section 3.2.3) to inform the client of the actual scope granted.
 
     // Let's make sure the scopes are unique (to reduce the token & storage
-    // size) & are indeed supported.
+    // size).
+    const scopes = new Set(parameters.scope?.split(' '))
 
     // @NOTE An app requesting a not yet supported list of scopes will need to
     // re-authenticate the user once the scopes are supported. This is due to
     // the fact that the AS does not know how to properly display those scopes
     // to the user, so it cannot properly ask for consent.
-    const scopes = new Set(
-      parameters.scope?.split(' ')?.filter(isValidAtprotoOauthScope),
-    )
-
-    parameters = { ...parameters, scope: [...scopes].join(' ') || undefined }
+    const scope =
+      Array.from(scopes).filter(isAtprotoOauthScope).join(' ') || undefined
+    parameters = { ...parameters, scope }
 
     if (parameters.code_challenge) {
       switch (parameters.code_challenge_method) {
@@ -288,6 +290,23 @@ export class RequestManager {
       parameters = { ...parameters, login_hint: hint }
     }
 
+    // Make sure that every nsid in the scope resolves to a valid permission set
+    // lexicon
+    if (parameters.scope) {
+      await this.lexiconManager
+        .getPermissionSetsFromScope(parameters.scope)
+        .catch((cause) => {
+          throw new AuthorizationError(
+            parameters,
+            cause instanceof LexiconResolutionError
+              ? cause.message
+              : 'Unable to retrieve included permission sets',
+            'invalid_scope',
+            cause,
+          )
+        })
+    }
+
     return parameters
   }
 

package/src/result/authorization-result-authorize-page.ts

@@ -1,12 +1,14 @@
+import type { LexPermissionSet } from '@atproto/lexicon'
 import type { Session } from '@atproto/oauth-provider-api'
-import { OAuthAuthorizationRequestParameters } from '@atproto/oauth-types'
-import { Client } from '../client/client.js'
-import { RequestUri } from '../request/request-uri.js'
+import type { OAuthAuthorizationRequestParameters } from '@atproto/oauth-types'
+import type { Client } from '../client/client.js'
+import type { RequestUri } from '../request/request-uri.js'
 
 export type AuthorizationResultAuthorizePage = {
   issuer: string
   client: Client
   parameters: OAuthAuthorizationRequestParameters
+  permissionSets: Map<string, LexPermissionSet>
 
   requestUri: RequestUri
   sessions: readonly Session[]

package/src/router/assets/send-authorization-page.ts

@@ -46,6 +46,7 @@ export function sendAuthorizePageFactory(customization: Customization) {
         scope: data.parameters.scope,
         uiLocales: data.parameters.ui_locales,
         loginHint: data.parameters.login_hint,
+        permissionSets: Object.fromEntries(data.permissionSets),
       },
       __sessions: data.sessions,
     })

package/src/token/token-data.ts

@@ -29,4 +29,12 @@ export type TokenData = {
   parameters: OAuthAuthorizationRequestParameters
   details?: null // Legacy field, not used
   code: Code | null
+
+  /**
+   * This will contain the parameter scope, translated into permissions
+   *
+   * @note null because this didn't use to exist. New tokens should always
+   * include a scope.
+   */
+  scope: string | null
 }

package/src/token/token-manager.ts

@@ -1,4 +1,5 @@
 import { SignedJwt, isSignedJwt } from '@atproto/jwk'
+import { LexiconResolutionError } from '@atproto/lexicon-resolver'
 import type { Account } from '@atproto/oauth-provider-api'
 import {
   OAuthAccessToken,
@@ -14,6 +15,7 @@ import { DeviceId } from '../device/device-id.js'
 import { InvalidGrantError } from '../errors/invalid-grant-error.js'
 import { InvalidRequestError } from '../errors/invalid-request-error.js'
 import { InvalidTokenError } from '../errors/invalid-token-error.js'
+import { LexiconManager } from '../lexicon/lexicon-manager.js'
 import { RequestMetadata } from '../lib/http/request.js'
 import { dateToEpoch, dateToRelativeSeconds } from '../lib/util/date.js'
 import { callAsync } from '../lib/util/function.js'
@@ -28,9 +30,8 @@ import {
   generateRefreshToken,
   isRefreshToken,
 } from './refresh-token.js'
-import { TokenData } from './token-data.js'
 import { TokenId, generateTokenId, isTokenId } from './token-id.js'
-import { TokenInfo, TokenStore } from './token-store.js'
+import { CreateTokenData, TokenInfo, TokenStore } from './token-store.js'
 import {
   VerifyTokenClaimsOptions,
   VerifyTokenClaimsResult,
@@ -43,6 +44,7 @@ export type { OAuthHooks, TokenStore, VerifyTokenClaimsResult }
 export class TokenManager {
   constructor(
     protected readonly store: TokenStore,
+    protected readonly lexiconManager: LexiconManager,
     protected readonly signer: Signer,
     protected readonly hooks: OAuthHooks,
     protected readonly accessTokenMode: AccessTokenMode,
@@ -58,21 +60,20 @@ export class TokenManager {
     account: Account,
     client: Client,
     parameters: OAuthAuthorizationRequestParameters,
-    options: {
-      now: Date
-      expiresAt: Date
-    },
+    createdAt: Date,
+    expiresAt: Date,
+    scope: string,
   ): Promise<OAuthAccessToken> {
     return this.signer.createAccessToken({
       jti: tokenId,
       sub: account.sub,
-      exp: dateToEpoch(options.expiresAt),
-      iat: dateToEpoch(options.now),
+      exp: dateToEpoch(expiresAt),
+      iat: dateToEpoch(createdAt),
       cnf: parameters.dpop_jkt ? { jkt: parameters.dpop_jkt } : undefined,
 
       ...(this.accessTokenMode === AccessTokenMode.stateless && {
         aud: account.aud,
-        scope: parameters.scope,
+        scope,
         // https://datatracker.ietf.org/doc/html/rfc8693#section-4.3
         client_id: client.id,
       }),
@@ -98,36 +99,50 @@ export class TokenManager {
     const now = new Date()
     const expiresAt = this.createTokenExpiry(now)
 
-    const tokenData: TokenData = {
-      createdAt: now,
-      updatedAt: now,
-      expiresAt,
-      clientId: client.id,
-      clientAuth,
-      deviceId,
-      sub: account.sub,
-      parameters,
-      details: null,
-      code,
-    }
+    const scope = await this.lexiconManager
+      .buildTokenScope(parameters.scope!)
+      .catch((cause) => {
+        throw new InvalidRequestError(
+          cause instanceof LexiconResolutionError
+            ? cause.message
+            : 'Unable to retrieve included permission sets',
+          cause,
+        )
+      })
 
     const accessToken = await this.buildAccessToken(
       tokenId,
       account,
       client,
       parameters,
-      { now, expiresAt },
+      now,
+      expiresAt,
+      scope,
     )
 
-    const response = await this.buildTokenResponse(
-      client,
+    const response = this.buildTokenResponse(
+      inferTokenType(parameters),
       accessToken,
       refreshToken,
       expiresAt,
-      parameters,
       account.sub,
+      scope,
     )
 
+    const tokenData: CreateTokenData = {
+      createdAt: now,
+      updatedAt: now,
+      expiresAt,
+      clientId: client.id,
+      clientAuth,
+      deviceId,
+      sub: account.sub,
+      parameters,
+      details: null,
+      scope,
+      code,
+    }
+
     await this.store.createToken(tokenId, tokenData, refreshToken)
 
     try {
@@ -161,18 +176,18 @@ export class TokenManager {
   }
 
   protected buildTokenResponse(
-    client: Client,
+    tokenType: OAuthTokenType,
     accessToken: OAuthAccessToken,
     refreshToken: string | undefined,
     expiresAt: Date,
-    parameters: OAuthAuthorizationRequestParameters,
     sub: Sub,
+    scope: string,
   ): OAuthTokenResponse {
     return {
       access_token: accessToken,
-      token_type: parameters.dpop_jkt ? 'DPoP' : 'Bearer',
+      token_type: tokenType,
       refresh_token: refreshToken,
-      scope: parameters.scope,
+      scope,
 
       // @NOTE using a getter so that the value gets computed when the JSON
       // response is generated, allowing to value to be as accurate as possible.
@@ -204,6 +219,11 @@ export class TokenManager {
     const now = new Date()
     const expiresAt = this.createTokenExpiry(now)
 
+    // @NOTE since the permission sets are stored in a persistent store,
+    // it's fine to propagate a 500 (server_error) here as the values should
+    // be retrievable from the store.
+    const scope = await this.lexiconManager.buildTokenScope(parameters.scope!)
+
     await this.store.rotateToken(tokenInfo.id, nextTokenId, nextRefreshToken, {
       updatedAt: now,
       expiresAt,
@@ -214,6 +234,7 @@ export class TokenManager {
       // - Allow clients to become "confidential" if they were previously
       //   "public"
       clientAuth,
+      scope,
     })
 
     const accessToken = await this.buildAccessToken(
@@ -221,16 +242,18 @@ export class TokenManager {
       account,
       client,
       parameters,
-      { now, expiresAt },
+      now,
+      expiresAt,
+      scope,
     )
 
-    const response = await this.buildTokenResponse(
-      client,
+    const response = this.buildTokenResponse(
+      inferTokenType(parameters),
       accessToken,
       nextRefreshToken,
       expiresAt,
-      parameters,
       account.sub,
+      scope,
     )
 
     await callAsync(this.hooks.onTokenRefreshed, {
@@ -361,7 +384,9 @@ export class TokenManager {
       // These are not stored in the JWT access token in "light" access token
       // mode. See `buildAccessToken`.
       aud: account.aud,
-      scope: parameters.scope,
+      // Note we fallback to parameters.scope for sessions created before
+      // TokenData.scope was introduced.
+      scope: data.scope ?? parameters.scope,
       client_id: data.clientId,
     }
 
@@ -386,3 +411,12 @@ export class TokenManager {
 function isCurrentTokenExpired(tokenInfo: TokenInfo): boolean {
   return tokenInfo.data.expiresAt.getTime() < Date.now()
 }
+
+function inferTokenType(
+  parameters: OAuthAuthorizationRequestParameters,
+): OAuthTokenType {
+  if (parameters.dpop_jkt) {
+    return 'DPoP'
+  }
+  return 'Bearer'
+}