@atproto/oauth-scopes 0.0.1 → 0.1.0

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

@@ -0,0 +1,130 @@
+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

@@ -0,0 +1,132 @@
+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

@@ -0,0 +1,43 @@
+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

@@ -0,0 +1,47 @@
+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): ParamValue[] | null | undefined
+}

package/src/lib/util.ts

@@ -1,19 +1,14 @@
+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 toRecord(
-  iterable: Iterable<[key: string, value: string]>,
-): Record<string, [string, ...string[]]> {
-  const record: Record<string, [string, ...string[]]> = Object.create(null)
-  for (const [key, value] of iterable) {
-    if (Object.hasOwn(record, key)) {
-      record[key]!.push(value)
-    } else {
-      record[key] = [value]
-    }
-  }
-  return record
+export function knownValuesValidator<T>(values: Iterable<T>) {
+  const set = new Set<unknown>(values)
+  return (value: unknown): value is T => set.has(value)
 }

package/src/{permission-set-transition.test.ts → scope-permissions-transition.test.ts}

@@ -1,11 +1,13 @@
-import { PermissionSetTransition } from './permission-set-transition.js'
+import { ScopePermissionsTransition } from './scope-permissions-transition.js'
 
-describe('PermissionSetTransition', () => {
+describe('ScopePermissionsTransition', () => {
   describe('allowsAccount', () => {
     it('should allow account:email with transition:email', () => {
-      const set = new PermissionSetTransition('transition:email account:repo')
+      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(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)
@@ -19,14 +21,14 @@ describe('PermissionSetTransition', () => {
 
   describe('allowsBlob', () => {
     it('should allow blob with transition:generic', () => {
-      const set = new PermissionSetTransition('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 PermissionSetTransition('transition:generic')
+      const set = new ScopePermissionsTransition('transition:generic')
       expect(
         set.allowsRepo({ collection: 'app.bsky.feed.post', action: 'create' }),
       ).toBe(true)
@@ -44,27 +46,30 @@ describe('PermissionSetTransition', () => {
 
   describe('allowsRpc', () => {
     it('should allow rpc with transition:generic', () => {
-      const set = new PermissionSetTransition('transition:generic')
+      const set = new ScopePermissionsTransition('transition:generic')
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.post' }),
+        set.allowsRpc({
+          aud: 'did:web:example.com',
+          lxm: 'app.bsky.feed.post',
+        }),
       ).toBe(true)
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.foo' }),
+        set.allowsRpc({ aud: 'did:web:example.com', lxm: 'com.example.foo' }),
       ).toBe(true)
-      expect(set.allowsRpc({ aud: 'did:example:123', lxm: '*' })).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 PermissionSetTransition('transition:chat.bsky')
+      const set = new ScopePermissionsTransition('transition:chat.bsky')
       expect(
         set.allowsRpc({
-          aud: 'did:example:123',
+          aud: 'did:web:example.com',
           lxm: 'chat.bsky.message.send',
         }),
       ).toBe(true)
       expect(
         set.allowsRpc({
-          aud: 'did:example:123',
+          aud: 'did:web:example.com',
           lxm: 'chat.bsky.conversation.get',
         }),
       ).toBe(true)
@@ -72,26 +77,31 @@ describe('PermissionSetTransition', () => {
       // Control
 
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.post' }),
+        set.allowsRpc({
+          aud: 'did:web:example.com',
+          lxm: 'app.bsky.feed.post',
+        }),
       ).toBe(false)
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.foo' }),
+        set.allowsRpc({ aud: 'did:web:example.com', lxm: 'com.example.foo' }),
       ).toBe(false)
-      expect(set.allowsRpc({ aud: 'did:example:123', lxm: '*' })).toBe(false)
+      expect(set.allowsRpc({ aud: 'did:web:example.com', lxm: '*' })).toBe(
+        false,
+      )
     })
 
     it('should reject chat methods with "transition:generic"', () => {
-      const set = new PermissionSetTransition('transition:generic')
+      const set = new ScopePermissionsTransition('transition:generic')
 
       expect(
         set.allowsRpc({
-          aud: 'did:example:123',
+          aud: 'did:web:example.com',
           lxm: 'chat.bsky.message.send',
         }),
       ).toBe(false)
       expect(
         set.allowsRpc({
-          aud: 'did:example:123',
+          aud: 'did:web:example.com',
           lxm: 'chat.bsky.conversation.get',
         }),
       ).toBe(false)
@@ -99,10 +109,13 @@ describe('PermissionSetTransition', () => {
       // Control
 
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.post' }),
+        set.allowsRpc({
+          aud: 'did:web:example.com',
+          lxm: 'app.bsky.feed.post',
+        }),
       ).toBe(true)
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.foo' }),
+        set.allowsRpc({ aud: 'did:web:example.com', lxm: 'com.example.foo' }),
       ).toBe(true)
     })
   })

package/src/{permission-set-transition.ts → scope-permissions-transition.ts}

@@ -1,16 +1,16 @@
 import {
-  AccountScopeMatch,
-  BlobScopeMatch,
-  PermissionSet,
-  RepoScopeMatch,
-  RpcScopeMatch,
-} from './permission-set.js'
+  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 PermissionSetTransition extends PermissionSet {
+export class ScopePermissionsTransition extends ScopePermissions {
   get hasTransitionGeneric(): boolean {
     return this.scopes.has('transition:generic')
   }
@@ -23,15 +23,19 @@ export class PermissionSetTransition extends PermissionSet {
     return this.scopes.has('transition:chat.bsky')
   }
 
-  override allowsAccount(options: AccountScopeMatch): boolean {
-    if (options.attr === 'email' && this.hasTransitionEmail) {
+  override allowsAccount(options: AccountPermissionMatch): boolean {
+    if (
+      options.attr === 'email' &&
+      options.action === 'read' &&
+      this.hasTransitionEmail
+    ) {
       return true
     }
 
     return super.allowsAccount(options)
   }
 
-  override allowsBlob(options: BlobScopeMatch): boolean {
+  override allowsBlob(options: BlobPermissionMatch): boolean {
     if (this.hasTransitionGeneric) {
       return true
     }
@@ -39,7 +43,7 @@ export class PermissionSetTransition extends PermissionSet {
     return super.allowsBlob(options)
   }
 
-  override allowsRepo(options: RepoScopeMatch): boolean {
+  override allowsRepo(options: RepoPermissionMatch): boolean {
     if (this.hasTransitionGeneric) {
       return true
     }
@@ -47,7 +51,7 @@ export class PermissionSetTransition extends PermissionSet {
     return super.allowsRepo(options)
   }
 
-  override allowsRpc(options: RpcScopeMatch) {
+  override allowsRpc(options: RpcPermissionMatch) {
     const { lxm } = options
 
     if (this.hasTransitionGeneric && lxm === '*') {