@atproto/oauth-scopes 0.5.2 → 0.5.3

package/src/lib/syntax-string.test.ts

@@ -1,130 +0,0 @@
-import { ScopeStringSyntax } from './syntax-string.js'
-import { ScopeStringFor } from './syntax.js'
-
-describe('ScopeStringSyntax', () => {
-  for (const { scope, content } of [
-    {
-      scope: 'my-res',
-      content: { prefix: 'my-res' },
-    },
-    {
-      scope: 'my-res:my-pos',
-      content: { prefix: 'my-res', positional: 'my-pos' },
-    },
-    {
-      scope: 'my-res:',
-      content: { prefix: 'my-res', positional: '' },
-    },
-    {
-      scope: 'my-res:foo?x=value&y=value-y',
-      content: {
-        prefix: 'my-res',
-        positional: 'foo',
-        params: { x: ['value'], y: ['value-y'] },
-      },
-    },
-    {
-      scope: 'my-res?x=value&y=value-y',
-      content: { prefix: 'my-res', params: { x: ['value'], y: ['value-y'] } },
-    },
-    {
-      scope: 'my-res?x=foo&x=bar&x=baz',
-      content: { prefix: 'my-res', params: { x: ['foo', 'bar', 'baz'] } },
-    },
-    {
-      scope: 'rpc:foo.bar?aud=did:foo:bar?lxm=bar.baz',
-      content: {
-        prefix: 'rpc',
-        positional: 'foo.bar',
-        params: { aud: ['did:foo:bar?lxm=bar.baz'] },
-      },
-    },
-  ] satisfies Array<{
-    scope: ScopeStringFor<'my-res' | 'rpc'>
-    content: {
-      prefix: string
-      positional?: string
-      params?: Record<string, string[]>
-    }
-  }>) {
-    const syntax = ScopeStringSyntax.fromString<'my-res' | 'rpc'>(scope)
-
-    describe(scope, () => {
-      it('should match the expected syntax', () => {
-        expect(syntax).toMatchObject({
-          prefix: content.prefix,
-          positional: content.positional,
-        })
-      })
-
-      it(`should match ${scope} prefix`, () => {
-        expect(syntax.prefix).toBe(content.prefix)
-      })
-
-      it(`should return positional parameter`, () => {
-        expect(syntax.positional).toBe(content.positional)
-      })
-
-      it(`should return undefined for nonexistent single-value param`, () => {
-        expect(syntax.getSingle('nonexistent')).toBeUndefined()
-      })
-
-      it(`should return undefined for nonexistent multi-value param`, () => {
-        expect(syntax.getMulti('nonexistent')).toBeUndefined()
-      })
-
-      const { params } = content
-      if (params) {
-        it(`only contain allowed parameters`, () => {
-          const allowedParams = Object.keys(params) as [string, ...string[]]
-          expect(
-            Array.from(syntax.keys()).every((key) =>
-              allowedParams.includes(key),
-            ),
-          ).toBe(true)
-        })
-
-        for (const [key, values] of Object.entries(params)) {
-          it(`should get an array when reading "${key}"`, () => {
-            expect(syntax.getMulti(key)).toEqual(values)
-          })
-
-          if (values.length === 1) {
-            it(`should allow retrieving single-value params`, () => {
-              expect(syntax.getSingle(key)).toEqual(values[0])
-            })
-          } else {
-            it(`should return null for multi-value params`, () => {
-              expect(syntax.getSingle(key)).toBeNull()
-            })
-          }
-        }
-      }
-    })
-  }
-
-  describe('invalid positional parameters', () => {
-    it('should return null for positional parameters used together with named parameters', () => {
-      const syntax = ScopeStringSyntax.fromString('my-res:pos?x=value')
-      expect(syntax.getSingle('x')).toBe('value')
-      expect(syntax.getMulti('x')).toEqual(['value'])
-    })
-  })
-
-  describe('url encoding', () => {
-    it('should handle URL encoding in positional parameters', () => {
-      const syntax = ScopeStringSyntax.fromString('my-res:my%20pos')
-      expect(syntax.positional).toBe('my pos')
-    })
-
-    it('should handle URL encoding in named parameters', () => {
-      const syntax = ScopeStringSyntax.fromString('my-res?x=my%20value')
-      expect(syntax.getSingle('x')).toBe('my value')
-    })
-
-    it(`should allow colon (:) in positional parameters`, () => {
-      const syntax = ScopeStringSyntax.fromString('my-res:my:pos')
-      expect(syntax.positional).toBe('my:pos')
-    })
-  })
-})

package/src/lib/syntax-string.ts

@@ -1,132 +0,0 @@
-import { ScopeStringFor, ScopeSyntax } from './syntax.js'
-import { minIdx } from './util.js'
-
-/**
- * Translates a scope string into a {@link ScopeSyntax}.
- */
-export class ScopeStringSyntax<P extends string> implements ScopeSyntax<P> {
-  constructor(
-    readonly prefix: P,
-    readonly positional?: string,
-    readonly params?: Readonly<URLSearchParams>,
-  ) {}
-
-  *keys() {
-    if (this.params) yield* this.params.keys()
-  }
-
-  getSingle(key: string) {
-    if (!this.params?.has(key)) return undefined
-    const value = this.params.getAll(key)
-    if (value.length > 1) return null
-    return value[0]!
-  }
-
-  getMulti(key: string) {
-    if (!this.params?.has(key)) return undefined
-    return this.params.getAll(key)
-  }
-
-  toString() {
-    let scope: string = this.prefix
-
-    if (this.positional !== undefined) {
-      scope += `:${normalizeURIComponent(encodeURIComponent(this.positional))}`
-    }
-
-    if (this.params?.size) {
-      scope += `?${normalizeURIComponent(this.params.toString())}`
-    }
-
-    return scope as ScopeStringFor<P>
-  }
-
-  static fromString<P extends string>(
-    scopeValue: ScopeStringFor<P>,
-  ): ScopeStringSyntax<P> {
-    const paramIdx = scopeValue.indexOf('?')
-    const colonIdx = scopeValue.indexOf(':')
-    const prefixEnd = minIdx(paramIdx, colonIdx)
-
-    // No param or positional
-    if (prefixEnd === -1) {
-      return new ScopeStringSyntax(scopeValue as P)
-    }
-
-    const prefix = scopeValue.slice(0, prefixEnd) as P
-
-    // Parse the positional parameter if present
-    const positional =
-      colonIdx !== -1
-        ? paramIdx === -1
-          ? decodeURIComponent(scopeValue.slice(colonIdx + 1))
-          : colonIdx < paramIdx
-            ? decodeURIComponent(scopeValue.slice(colonIdx + 1, paramIdx))
-            : undefined
-        : undefined
-
-    // Parse the query string if present and non empty
-    const params =
-      paramIdx !== -1 && paramIdx < scopeValue.length - 1
-        ? new URLSearchParams(scopeValue.slice(paramIdx + 1))
-        : undefined
-
-    return new ScopeStringSyntax(prefix, positional, params)
-  }
-}
-
-/**
- * Set of characters that are allowed in scope components without encoding. This
- * is used to normalize scope components.
- */
-const ALLOWED_SCOPE_CHARS = new Set(
-  // @NOTE This list must not contain "?" or "&" as it would interfere with
-  // query string parsing.
-  [':', '/', '+', ',', '@', '%'],
-)
-
-const NORMALIZABLE_CHARS_MAP = new Map(
-  Array.from(
-    ALLOWED_SCOPE_CHARS,
-    (c) => [encodeURIComponent(c), c] as const,
-  ).filter(
-    ([encoded, c]) =>
-      // Make sure that any char added to ALLOWED_SCOPE_CHARS that is a char
-      // that indeed needs encoding. Also, the normalizeURIComponent only
-      // supports three-character percent-encoded sequences.
-      encoded !== c && encoded.length === 3 && encoded.startsWith('%'),
-  ),
-)
-
-/**
- * Assumes a properly url-encoded string.
- */
-function normalizeURIComponent(value: string): string {
-  // No need to read the last two characters since percent encoded characters
-  // are always three characters long.
-  let end = value.length - 2
-
-  for (let i = 0; i < end; i++) {
-    // Check if the character is a percent-encoded character
-    if (value.charCodeAt(i) === 0x25 /* % */) {
-      // Read the next encoded char. Current version only supports
-      // three-character percent-encoded sequences.
-      const encodedChar = value.slice(i, i + 3)
-
-      // Check if the encoded character is in the normalization map
-      const normalizedChar = NORMALIZABLE_CHARS_MAP.get(encodedChar)
-      if (normalizedChar) {
-        // Replace the encoded character with its normalized version
-        value = `${value.slice(0, i)}${normalizedChar}${value.slice(i + encodedChar.length)}`
-
-        // Adjust index to account for the length change
-        i += normalizedChar.length - 1
-
-        // Adjust end index since we replaced encoded char with normalized char
-        end -= encodedChar.length - normalizedChar.length
-      }
-    }
-  }
-
-  return value
-}

package/src/lib/syntax.test.ts

@@ -1,43 +0,0 @@
-import { isScopeStringFor } from './syntax.js'
-
-describe('isScopeStringFor', () => {
-  describe('exact match', () => {
-    it('should return true for exact match', () => {
-      expect(isScopeStringFor('prefix', 'prefix')).toBe(true)
-    })
-
-    it('should return false for different prefix', () => {
-      expect(isScopeStringFor('prefix', 'differentResource')).toBe(false)
-    })
-  })
-
-  describe('with positional parameter', () => {
-    it('should return true for exact match with positional parameter', () => {
-      expect(isScopeStringFor('prefix:positional', 'prefix')).toBe(true)
-    })
-
-    it('should return false for different prefix with positional parameter', () => {
-      expect(isScopeStringFor('differentResource:positional', 'prefix')).toBe(
-        false,
-      )
-    })
-  })
-
-  describe('with named parameters', () => {
-    it('should return true for exact match with named parameters', () => {
-      expect(isScopeStringFor('prefix?param=value', 'prefix')).toBe(true)
-    })
-
-    it('should return false for different prefix with named parameters', () => {
-      expect(isScopeStringFor('prefix', 'prefi')).toBe(false)
-      expect(isScopeStringFor('prefix:pos', 'prefi')).toBe(false)
-      expect(isScopeStringFor('prefix?param=value', 'prefi')).toBe(false)
-      expect(isScopeStringFor('prefix', 'fix')).toBe(false)
-      expect(isScopeStringFor('prefix:pos', 'fix')).toBe(false)
-      expect(isScopeStringFor('prefix?param=value', 'fix')).toBe(false)
-      expect(isScopeStringFor('differentResource?param=value', 'prefix')).toBe(
-        false,
-      )
-    })
-  })
-})

package/src/lib/syntax.ts

@@ -1,54 +0,0 @@
-export type ParamValue = string | number | boolean
-
-export type NeArray<T> = [T, ...T[]]
-
-/**
- * Non-empty readonly array
- */
-export type NeRoArray<T> = readonly [T, ...T[]]
-
-export type ScopeStringFor<P extends string> =
-  | P
-  | `${P}:${string}`
-  | `${P}?${string}`
-
-/**
- * Allows to quickly check if a scope is for a specific resource.
- */
-export function isScopeStringFor<P extends string>(
-  value: string,
-  prefix: P,
-): value is ScopeStringFor<P> {
-  if (value.length > prefix.length) {
-    // First, check the next char is either : or ?
-    const nextChar = value.charCodeAt(prefix.length)
-    if (nextChar !== 0x3a /* : */ && nextChar !== 0x3f /* ? */) {
-      return false
-    }
-
-    // Then check the full prefix
-    return value.startsWith(prefix)
-  } else {
-    // value and prefix must be equal
-    return value === prefix
-  }
-}
-
-/**
- * Abstract interface that allows parsing various syntaxes into permission
- * representations.
- */
-export interface ScopeSyntax<P extends string> {
-  readonly prefix: P
-  readonly positional?: ParamValue
-  keys(): Iterable<string, void, unknown>
-  getSingle(key: string): ParamValue | null | undefined
-  getMulti(key: string): readonly ParamValue[] | null | undefined
-}
-
-export function isScopeSyntaxFor<P extends string>(
-  syntax: ScopeSyntax<string>,
-  prefix: P,
-): syntax is ScopeSyntax<P> {
-  return syntax.prefix === prefix
-}

package/src/lib/util.ts

@@ -1,18 +0,0 @@
-export interface Matchable<T> {
-  matches(options: T): boolean
-}
-
-export function minIdx(a: number, b: number): number {
-  if (a === -1) return b
-  if (b === -1) return a
-  return Math.min(a, b)
-}
-
-export function knownValuesValidator<T>(values: Iterable<T>) {
-  const set = new Set<unknown>(values)
-  return (value: unknown): value is T => set.has(value)
-}
-
-export function isNonNullable<T>(value: T): value is NonNullable<T> {
-  return value != null
-}

package/src/scope-missing-error.ts

@@ -1,15 +0,0 @@
-export class ScopeMissingError extends Error {
-  name = 'ScopeMissingError'
-
-  // compatibility layer with http-errors package. The goal if to make
-  // isHttpError(new ScopeMissingError) return true.
-  status = 403
-  expose = true
-  get statusCode() {
-    return this.status
-  }
-
-  constructor(public readonly scope: string) {
-    super(`Missing required scope "${scope}"`)
-  }
-}

package/src/scope-permissions-transition.test.ts

@@ -1,122 +0,0 @@
-import { ScopePermissionsTransition } from './scope-permissions-transition.js'
-
-describe('ScopePermissionsTransition', () => {
-  describe('allowsAccount', () => {
-    it('should allow account:email with transition:email', () => {
-      const set = new ScopePermissionsTransition(
-        'transition:email account:repo',
-      )
-      expect(set.allowsAccount({ attr: 'email', action: 'read' })).toBe(true)
-      expect(set.allowsAccount({ attr: 'email', action: 'manage' })).toBe(false)
-
-      expect(set.allowsAccount({ attr: 'repo', action: 'read' })).toBe(true)
-      expect(set.allowsAccount({ attr: 'repo', action: 'manage' })).toBe(false)
-
-      expect(set.allowsAccount({ attr: 'status', action: 'read' })).toBe(false)
-      expect(set.allowsAccount({ attr: 'status', action: 'manage' })).toBe(
-        false,
-      )
-    })
-  })
-
-  describe('allowsBlob', () => {
-    it('should allow blob with transition:generic', () => {
-      const set = new ScopePermissionsTransition('transition:generic')
-      expect(set.allowsBlob({ mime: 'foo/bar' })).toBe(true)
-    })
-  })
-
-  describe('allowsRepo', () => {
-    it('should allow repo with transition:generic', () => {
-      const set = new ScopePermissionsTransition('transition:generic')
-      expect(
-        set.allowsRepo({ collection: 'app.bsky.feed.post', action: 'create' }),
-      ).toBe(true)
-      expect(
-        set.allowsRepo({ collection: 'app.bsky.feed.post', action: 'delete' }),
-      ).toBe(true)
-      expect(
-        set.allowsRepo({ collection: 'com.example.foo', action: 'create' }),
-      ).toBe(true)
-      expect(
-        set.allowsRepo({ collection: 'com.example.foo', action: 'update' }),
-      ).toBe(true)
-    })
-  })
-
-  describe('allowsRpc', () => {
-    it('should allow rpc with transition:generic', () => {
-      const set = new ScopePermissionsTransition('transition:generic')
-      expect(
-        set.allowsRpc({
-          aud: 'did:web:example.com',
-          lxm: 'app.bsky.feed.post',
-        }),
-      ).toBe(true)
-      expect(
-        set.allowsRpc({ aud: 'did:web:example.com', lxm: 'com.example.foo' }),
-      ).toBe(true)
-      expect(set.allowsRpc({ aud: 'did:web:example.com', lxm: '*' })).toBe(true)
-    })
-
-    it('should allow chat.bsky.* methods with "transition:chat.bsky"', () => {
-      const set = new ScopePermissionsTransition('transition:chat.bsky')
-      expect(
-        set.allowsRpc({
-          aud: 'did:web:example.com',
-          lxm: 'chat.bsky.message.send',
-        }),
-      ).toBe(true)
-      expect(
-        set.allowsRpc({
-          aud: 'did:web:example.com',
-          lxm: 'chat.bsky.conversation.get',
-        }),
-      ).toBe(true)
-
-      // Control
-
-      expect(
-        set.allowsRpc({
-          aud: 'did:web:example.com',
-          lxm: 'app.bsky.feed.post',
-        }),
-      ).toBe(false)
-      expect(
-        set.allowsRpc({ aud: 'did:web:example.com', lxm: 'com.example.foo' }),
-      ).toBe(false)
-      expect(set.allowsRpc({ aud: 'did:web:example.com', lxm: '*' })).toBe(
-        false,
-      )
-    })
-
-    it('should reject chat methods with "transition:generic"', () => {
-      const set = new ScopePermissionsTransition('transition:generic')
-
-      expect(
-        set.allowsRpc({
-          aud: 'did:web:example.com',
-          lxm: 'chat.bsky.message.send',
-        }),
-      ).toBe(false)
-      expect(
-        set.allowsRpc({
-          aud: 'did:web:example.com',
-          lxm: 'chat.bsky.conversation.get',
-        }),
-      ).toBe(false)
-
-      // Control
-
-      expect(
-        set.allowsRpc({
-          aud: 'did:web:example.com',
-          lxm: 'app.bsky.feed.post',
-        }),
-      ).toBe(true)
-      expect(
-        set.allowsRpc({ aud: 'did:web:example.com', lxm: 'com.example.foo' }),
-      ).toBe(true)
-    })
-  })
-})

package/src/scope-permissions-transition.ts

@@ -1,71 +0,0 @@
-import {
-  AccountPermissionMatch,
-  BlobPermissionMatch,
-  RepoPermissionMatch,
-  RpcPermissionMatch,
-  ScopePermissions,
-} from './scope-permissions.js'
-
-/**
- * Overrides the default permission set to allow transitional scopes to be used
- * in place of the generic scopes.
- */
-export class ScopePermissionsTransition extends ScopePermissions {
-  get hasTransitionGeneric(): boolean {
-    return this.scopes.has('transition:generic')
-  }
-
-  get hasTransitionEmail(): boolean {
-    return this.scopes.has('transition:email')
-  }
-
-  get hasTransitionChatBsky(): boolean {
-    return this.scopes.has('transition:chat.bsky')
-  }
-
-  override allowsAccount(options: AccountPermissionMatch): boolean {
-    if (
-      options.attr === 'email' &&
-      options.action === 'read' &&
-      this.hasTransitionEmail
-    ) {
-      return true
-    }
-
-    return super.allowsAccount(options)
-  }
-
-  override allowsBlob(options: BlobPermissionMatch): boolean {
-    if (this.hasTransitionGeneric) {
-      return true
-    }
-
-    return super.allowsBlob(options)
-  }
-
-  override allowsRepo(options: RepoPermissionMatch): boolean {
-    if (this.hasTransitionGeneric) {
-      return true
-    }
-
-    return super.allowsRepo(options)
-  }
-
-  override allowsRpc(options: RpcPermissionMatch) {
-    const { lxm } = options
-
-    if (this.hasTransitionGeneric && lxm === '*') {
-      return true
-    }
-
-    if (this.hasTransitionGeneric && !lxm.startsWith('chat.bsky.')) {
-      return true
-    }
-
-    if (this.hasTransitionChatBsky && lxm.startsWith('chat.bsky.')) {
-      return true
-    }
-
-    return super.allowsRpc(options)
-  }
-}