@atproto/oauth-scopes 0.0.1

package/src/permission-set.ts

@@ -0,0 +1,78 @@
+import { AccountScope, AccountScopeMatch } from './resources/account-scope.js'
+import { BlobScope, BlobScopeMatch } from './resources/blob-scope.js'
+import {
+  IdentityScope,
+  IdentityScopeMatch,
+} from './resources/identity-scope.js'
+import { RepoScope, RepoScopeMatch } from './resources/repo-scope.js'
+import { RpcScope, RpcScopeMatch } from './resources/rpc-scope.js'
+import { ScopeMissingError } from './scope-missing-error.js'
+import { ScopesSet } from './scopes-set.js'
+
+export type {
+  AccountScopeMatch,
+  BlobScopeMatch,
+  IdentityScopeMatch,
+  RepoScopeMatch,
+  RpcScopeMatch,
+}
+
+export class PermissionSet {
+  public readonly scopes: ScopesSet
+
+  constructor(scopes?: null | string | Iterable<string>) {
+    this.scopes = new ScopesSet(
+      typeof scopes === 'string' ? scopes.split(' ') : scopes,
+    )
+  }
+
+  public allowsAccount(options: AccountScopeMatch): boolean {
+    return this.scopes.matches('account', options)
+  }
+  public assertAccount(options: AccountScopeMatch): void {
+    if (!this.allowsAccount(options)) {
+      const scope = AccountScope.scopeNeededFor(options)
+      throw new ScopeMissingError(scope)
+    }
+  }
+
+  public allowsIdentity(options: IdentityScopeMatch): boolean {
+    return this.scopes.matches('identity', options)
+  }
+  public assertIdentity(options: IdentityScopeMatch): void {
+    if (!this.allowsIdentity(options)) {
+      const scope = IdentityScope.scopeNeededFor(options)
+      throw new ScopeMissingError(scope)
+    }
+  }
+
+  public allowsBlob(options: BlobScopeMatch): boolean {
+    return this.scopes.matches('blob', options)
+  }
+  public assertBlob(options: BlobScopeMatch): void {
+    if (!this.allowsBlob(options)) {
+      const scope = BlobScope.scopeNeededFor(options)
+      throw new ScopeMissingError(scope)
+    }
+  }
+
+  public allowsRepo(options: RepoScopeMatch): boolean {
+    return this.scopes.matches('repo', options)
+  }
+  public assertRepo(options: RepoScopeMatch): void {
+    if (!this.allowsRepo(options)) {
+      const scope = RepoScope.scopeNeededFor(options)
+      throw new ScopeMissingError(scope)
+    }
+  }
+
+  public allowsRpc(options: RpcScopeMatch): boolean {
+    return this.scopes.matches('rpc', options)
+  }
+  public assertRpc(options: RpcScopeMatch): void {
+    if (!this.allowsRpc(options)) {
+      const scope = RpcScope.scopeNeededFor(options)
+      throw new ScopeMissingError(scope)
+    }
+  }
+}

package/src/resources/account-scope.test.ts

@@ -0,0 +1,175 @@
+import { AccountScope } from './account-scope.js'
+
+describe('AccountScope', () => {
+  describe('static', () => {
+    describe('fromString', () => {
+      it('should parse valid scope strings', () => {
+        const scope1 = AccountScope.fromString('account:email?action=read')
+        expect(scope1).not.toBeNull()
+        expect(scope1!.attr).toBe('email')
+        expect(scope1!.action).toBe('read')
+
+        const scope2 = AccountScope.fromString('account:repo?action=manage')
+        expect(scope2).not.toBeNull()
+        expect(scope2!.attr).toBe('repo')
+        expect(scope2!.action).toBe('manage')
+      })
+
+      it('should parse scope without action (defaults to read)', () => {
+        const scope = AccountScope.fromString('account:status')
+        expect(scope).not.toBeNull()
+        expect(scope!.attr).toBe('status')
+        expect(scope!.action).toBe('read')
+      })
+
+      it('should reject invalid attribute names', () => {
+        const scope = AccountScope.fromString('account:invalid')
+        expect(scope).toBeNull()
+      })
+
+      it('should reject invalid action names', () => {
+        const scope = AccountScope.fromString('account:email?action=invalid')
+        expect(scope).toBeNull()
+      })
+
+      it('should reject malformed scope strings', () => {
+        expect(AccountScope.fromString('invalid:email')).toBeNull()
+        expect(AccountScope.fromString('account')).toBeNull()
+        expect(AccountScope.fromString('')).toBeNull()
+        expect(AccountScope.fromString('account:')).toBeNull()
+      })
+    })
+
+    describe('scopeNeededFor', () => {
+      it('should return correct scope string for read actions', () => {
+        expect(
+          AccountScope.scopeNeededFor({ attr: 'email', action: 'read' }),
+        ).toBe('account:email')
+        expect(
+          AccountScope.scopeNeededFor({ attr: 'repo', action: 'read' }),
+        ).toBe('account:repo')
+        expect(
+          AccountScope.scopeNeededFor({ attr: 'status', action: 'read' }),
+        ).toBe('account:status')
+      })
+
+      it('should return correct scope string for manage actions', () => {
+        expect(
+          AccountScope.scopeNeededFor({ attr: 'email', action: 'manage' }),
+        ).toBe('account:email?action=manage')
+        expect(
+          AccountScope.scopeNeededFor({ attr: 'repo', action: 'manage' }),
+        ).toBe('account:repo?action=manage')
+        expect(
+          AccountScope.scopeNeededFor({
+            attr: 'status',
+            action: 'manage',
+          }),
+        ).toBe('account:status?action=manage')
+      })
+    })
+  })
+
+  describe('instance', () => {
+    describe('matches', () => {
+      it('should match read action', () => {
+        const scope = AccountScope.fromString('account:email?action=read')
+        expect(scope).not.toBeNull()
+        expect(scope!.matches({ attr: 'email', action: 'read' })).toBe(true)
+      })
+
+      it('should match manage action', () => {
+        const scope = AccountScope.fromString('account:repo?action=manage')
+        expect(scope).not.toBeNull()
+        expect(scope!.matches({ attr: 'repo', action: 'manage' })).toBe(true)
+      })
+
+      it('should not match unspecified action', () => {
+        const scope = AccountScope.fromString('account:email?action=read')
+        expect(scope).not.toBeNull()
+        expect(scope!.matches({ attr: 'email', action: 'manage' })).toBe(false)
+      })
+
+      it('should not match different attribute', () => {
+        const scope = AccountScope.fromString('account:email?action=read')
+        expect(scope).not.toBeNull()
+        expect(scope!.matches({ attr: 'repo', action: 'read' })).toBe(false)
+      })
+
+      it('should default to "read" action', () => {
+        const scope = AccountScope.fromString('account:email')
+        expect(scope).not.toBeNull()
+        expect(scope!.matches({ attr: 'email', action: 'read' })).toBe(true)
+        expect(scope!.matches({ attr: 'email', action: 'manage' })).toBe(false)
+      })
+
+      it('should work with all valid attributes', () => {
+        const emailScope = AccountScope.fromString('account:email?action=read')
+        const repoScope = AccountScope.fromString('account:repo?action=manage')
+        const statusScope = AccountScope.fromString(
+          'account:status?action=read',
+        )
+
+        expect(emailScope).not.toBeNull()
+        expect(repoScope).not.toBeNull()
+        expect(statusScope).not.toBeNull()
+
+        expect(emailScope!.matches({ attr: 'email', action: 'read' })).toBe(
+          true,
+        )
+        expect(repoScope!.matches({ attr: 'repo', action: 'manage' })).toBe(
+          true,
+        )
+        expect(statusScope!.matches({ attr: 'status', action: 'read' })).toBe(
+          true,
+        )
+      })
+
+      it('should allow read when "manage" action is specified', () => {
+        const scope = AccountScope.fromString('account:email?action=manage')
+        expect(scope).not.toBeNull()
+        expect(scope!.matches({ attr: 'email', action: 'read' })).toBe(true)
+      })
+    })
+
+    describe('toString', () => {
+      it('should format scope with explicit action', () => {
+        const scope = new AccountScope('email', 'manage')
+        expect(scope.toString()).toBe('account:email?action=manage')
+      })
+
+      it('should format scope with default action', () => {
+        const scope = new AccountScope('repo', 'read')
+        expect(scope.toString()).toBe('account:repo')
+      })
+
+      it('should format all attributes correctly', () => {
+        expect(new AccountScope('email', 'read').toString()).toBe(
+          'account:email',
+        )
+        expect(new AccountScope('repo', 'read').toString()).toBe('account:repo')
+        expect(new AccountScope('status', 'read').toString()).toBe(
+          'account:status',
+        )
+        expect(new AccountScope('email', 'manage').toString()).toBe(
+          'account:email?action=manage',
+        )
+      })
+    })
+  })
+
+  it('should maintain consistency between toString and fromString', () => {
+    const testCases = [
+      'account:email',
+      'account:email?action=manage',
+      'account:repo',
+      'account:repo?action=manage',
+      'account:status',
+      'account:status?action=manage',
+    ]
+
+    for (const scope of testCases) {
+      expect(AccountScope.fromString(scope)?.toString()).toBe(scope)
+    }
+  })
+})

package/src/resources/account-scope.ts

@@ -0,0 +1,66 @@
+import { Parser, knownValuesValidator } from '../parser.js'
+import { ResourceSyntax, isScopeForResource } from '../syntax.js'
+
+const ACCOUNT_ATTRIBUTES = Object.freeze(['email', 'repo', 'status'] as const)
+export type AccountAttribute = (typeof ACCOUNT_ATTRIBUTES)[number]
+
+const ACCOUNT_ACTIONS = Object.freeze(['read', 'manage'] as const)
+export type AccountAction = (typeof ACCOUNT_ACTIONS)[number]
+
+export const accountParser = new Parser(
+  'account',
+  {
+    attr: {
+      multiple: false,
+      required: true,
+      validate: knownValuesValidator(ACCOUNT_ATTRIBUTES),
+    },
+    action: {
+      multiple: false,
+      required: false,
+      validate: knownValuesValidator(ACCOUNT_ACTIONS),
+      default: 'read' as const,
+    },
+  },
+  'attr',
+)
+
+export type AccountScopeMatch = {
+  attr: AccountAttribute
+  action: AccountAction
+}
+
+export class AccountScope {
+  constructor(
+    public readonly attr: AccountAttribute,
+    public readonly action: AccountAction,
+  ) {}
+
+  matches(options: AccountScopeMatch): boolean {
+    return (
+      this.attr === options.attr &&
+      (this.action === 'manage' || this.action === options.action)
+    )
+  }
+
+  toString() {
+    return accountParser.format(this)
+  }
+
+  static fromString(scope: string) {
+    if (!isScopeForResource(scope, 'account')) return null
+    const syntax = ResourceSyntax.fromString(scope)
+    return this.fromSyntax(syntax)
+  }
+
+  static fromSyntax(syntax: ResourceSyntax) {
+    const result = accountParser.parse(syntax)
+    if (!result) return null
+
+    return new AccountScope(result.attr, result.action)
+  }
+
+  static scopeNeededFor(options: AccountScopeMatch): string {
+    return accountParser.format(options)
+  }
+}

package/src/resources/blob-scope.test.ts

@@ -0,0 +1,118 @@
+import { BlobScope } from './blob-scope.js'
+
+describe('BlobScope', () => {
+  describe('static', () => {
+    describe('fromString', () => {
+      it('should parse positional scope', () => {
+        const scope = BlobScope.fromString('blob:image/png')
+        expect(scope).not.toBeNull()
+        expect(scope!.accept).toEqual(['image/png'])
+      })
+
+      it('should parse valid blob scope with multiple accept parameters', () => {
+        const scope = BlobScope.fromString(
+          'blob?accept=image/png&accept=image/jpeg',
+        )
+        expect(scope).not.toBeNull()
+        expect(scope!.accept).toEqual(['image/png', 'image/jpeg'])
+      })
+
+      it('should reject blob scope without accept', () => {
+        const scope = BlobScope.fromString('blob')
+        expect(scope).toBeNull()
+      })
+
+      for (const invalid of [
+        'invalid',
+        'scope',
+        'blob:invalid',
+        'blob?accept=invalid-mime',
+        'blob?accept=invalid',
+        'blob:*/**',
+        'blob:*/png',
+      ]) {
+        it(`should return null for invalid rpc scope: ${invalid}`, () => {
+          expect(BlobScope.fromString(invalid)).toBeNull()
+        })
+      }
+    })
+
+    describe('scopeNeededFor', () => {
+      it('should return correct scope string for specific MIME type', () => {
+        const scope = BlobScope.scopeNeededFor({ mime: 'image/png' })
+        expect(scope).toBe('blob:image/png')
+      })
+
+      it('should return scope that accepts all MIME types', () => {
+        const scope = BlobScope.scopeNeededFor({ mime: 'application/json' })
+        expect(scope).toBe('blob:application/json')
+      })
+    })
+  })
+
+  describe('instance', () => {
+    describe('matches', () => {
+      it('should match exact MIME type', () => {
+        const scope = BlobScope.fromString('blob:image/png')
+        expect(scope).not.toBeNull()
+        expect(scope!.matches({ mime: 'image/png' })).toBe(true)
+      })
+
+      it('should match wildcard MIME type', () => {
+        const scope = BlobScope.fromString('blob:*/*')
+        expect(scope).not.toBeNull()
+        expect(scope!.matches({ mime: 'image/jpeg' })).toBe(true)
+        expect(scope!.matches({ mime: 'application/json' })).toBe(true)
+      })
+
+      it('should match subtype wildcard MIME type', () => {
+        const scope = BlobScope.fromString('blob:image/*')
+        expect(scope).not.toBeNull()
+        expect(scope!.matches({ mime: 'image/gif' })).toBe(true)
+      })
+
+      it('should not match different MIME type', () => {
+        const scope = BlobScope.fromString('blob:image/png')
+        expect(scope).not.toBeNull()
+        expect(scope!.matches({ mime: 'image/jpeg' })).toBe(false)
+      })
+
+      it('should match multiple accept values', () => {
+        const scope = BlobScope.fromString(
+          'blob?accept=image/png&accept=image/jpeg',
+        )
+        expect(scope).not.toBeNull()
+        expect(scope!.matches({ mime: 'image/png' })).toBe(true)
+        expect(scope!.matches({ mime: 'image/jpeg' })).toBe(true)
+        expect(scope!.matches({ mime: 'image/gif' })).toBe(false)
+      })
+    })
+
+    describe('toString', () => {
+      it('should format scope with accept parameter', () => {
+        const scope = new BlobScope(['image/png', 'image/jpeg'])
+        expect(scope.toString()).toBe('blob?accept=image/png&accept=image/jpeg')
+      })
+
+      it('should strip redundant accept parameters', () => {
+        expect(new BlobScope(['*/*', 'image/*']).toString()).toBe('blob:*/*')
+        expect(new BlobScope(['*/*', 'image/png']).toString()).toBe('blob:*/*')
+        expect(new BlobScope(['image/*', 'image/png']).toString()).toBe(
+          'blob:image/*',
+        )
+      })
+
+      it('should use positional format for single accept', () => {
+        expect(new BlobScope(['image/png']).toString()).toBe('blob:image/png')
+        expect(new BlobScope(['image/*']).toString()).toBe('blob:image/*')
+        expect(new BlobScope(['*/*']).toString()).toBe('blob:*/*')
+      })
+
+      it('should use query format for multiple accepts', () => {
+        expect(new BlobScope(['image/png', 'image/jpeg']).toString()).toBe(
+          'blob?accept=image/png&accept=image/jpeg',
+        )
+      })
+    })
+  })
+})

package/src/resources/blob-scope.ts

@@ -0,0 +1,86 @@
+import { Accept, isAccept, matchesAnyAccept } from '../lib/mime.js'
+import { Parser } from '../parser.js'
+import { NeRoArray, ResourceSyntax, isScopeForResource } from '../syntax.js'
+
+export const DEFAULT_ACCEPT = Object.freeze(['*/*'] as const)
+
+export const blobParser = new Parser(
+  'blob',
+  {
+    accept: {
+      multiple: true,
+      required: true,
+      validate: isAccept,
+      normalize: (value) => {
+        // Returns a more concise representation of the accept values.
+        if (value.includes('*/*')) return DEFAULT_ACCEPT
+
+        return value.map(toLowerCase).filter(isNonRedundant) as [
+          Accept,
+          ...Accept[],
+        ]
+      },
+    },
+  },
+  'accept',
+)
+
+export type BlobScopeMatch = {
+  mime: string
+}
+
+export class BlobScope {
+  constructor(public readonly accept: NeRoArray<Accept>) {}
+
+  matches(options: BlobScopeMatch) {
+    return matchesAnyAccept(this.accept, options.mime)
+  }
+
+  toString() {
+    return blobParser.format(this)
+  }
+
+  static fromString(scope: string) {
+    if (!isScopeForResource(scope, 'blob')) return null
+    const syntax = ResourceSyntax.fromString(scope)
+    return this.fromSyntax(syntax)
+  }
+
+  static fromSyntax(syntax: ResourceSyntax) {
+    const result = blobParser.parse(syntax)
+    if (!result) return null
+
+    return new BlobScope(result.accept)
+  }
+
+  static scopeNeededFor(options: BlobScopeMatch) {
+    return blobParser.format({
+      accept: [options.mime as Accept],
+    })
+  }
+}
+
+function toLowerCase(value: string): string {
+  return value.toLowerCase()
+}
+
+function isNonRedundant(
+  value: string,
+  index: number,
+  arr: readonly string[],
+): boolean {
+  if (value.endsWith('/*')) {
+    // assuming the array contains unique element, wildcards cannot be redundant
+    // with one another ('image/*' is not redundant with 'text/*')
+    return true
+  }
+  const base = value.split('/', 1)[0]
+  if (arr.includes(`${base}/*`)) {
+    // If another value in the array is a wildcard for the same base, we can
+    // skip this one as it is redundant. e.g. if the array contains 'image/png'
+    // and 'image/*', we can skip 'image/png' because 'image/*' already covers
+    // it.
+    return false
+  }
+  return true
+}

package/src/resources/identity-scope.test.ts

@@ -0,0 +1,80 @@
+import { IdentityScope } from './identity-scope.js'
+
+describe('IdentityScope', () => {
+  describe('static', () => {
+    describe('fromString', () => {
+      it('should parse positional scope', () => {
+        const scope = IdentityScope.fromString('identity:handle')
+        expect(scope).not.toBeNull()
+        expect(scope!.attr).toBe('handle')
+      })
+
+      it('should parse valid identity scope with wildcard attribute', () => {
+        const scope = IdentityScope.fromString('identity:*')
+        expect(scope).not.toBeNull()
+        expect(scope!.attr).toBe('*')
+      })
+
+      it('should return null for invalid identity scope', () => {
+        expect(IdentityScope.fromString('invalid')).toBeNull()
+        expect(IdentityScope.fromString('identity:invalid')).toBeNull()
+      })
+
+      for (const invalid of [
+        'identity:*?action=*',
+        'identity:*?action=manage',
+        'identity:*?action=submit',
+        'invalid',
+        'identity:invalid',
+        'identity:handle?action=invalid',
+        'identity?attribute=invalid&action=invalid',
+      ]) {
+        it(`should return null for invalid rpc scope: ${invalid}`, () => {
+          expect(IdentityScope.fromString(invalid)).toBeNull()
+        })
+      }
+    })
+
+    describe('scopeNeededFor', () => {
+      it('should return correct scope string for specific attribute and action', () => {
+        const scope = IdentityScope.scopeNeededFor({ attr: 'handle' })
+        expect(scope).toBe('identity:handle')
+      })
+
+      it('should return scope that accepts all attributes with specific action', () => {
+        const scope = IdentityScope.scopeNeededFor({ attr: '*' })
+        expect(scope).toBe('identity:*')
+      })
+    })
+  })
+
+  describe('instance', () => {
+    describe('matches', () => {
+      it('should match default attribute and action', () => {
+        const scope = IdentityScope.fromString('identity:handle')
+        expect(scope).not.toBeNull()
+        expect(scope!.matches({ attr: 'handle' })).toBe(true)
+        expect(scope!.matches({ attr: '*' })).toBe(false)
+      })
+
+      it('should match wildcard attribute with specific action', () => {
+        const scope = IdentityScope.fromString('identity:*')
+        expect(scope).not.toBeNull()
+        expect(scope!.matches({ attr: '*' })).toBe(true)
+        expect(scope!.matches({ attr: 'handle' })).toBe(true)
+      })
+    })
+
+    describe('toString', () => {
+      it('should format scope with default action', () => {
+        const scope = new IdentityScope('handle')
+        expect(scope.toString()).toBe('identity:handle')
+      })
+
+      it('should format wildcard attribute with default action', () => {
+        const scope = new IdentityScope('*')
+        expect(scope.toString()).toBe('identity:*')
+      })
+    })
+  })
+})

package/src/resources/identity-scope.ts

@@ -0,0 +1,49 @@
+import { Parser, knownValuesValidator } from '../parser.js'
+import { ResourceSyntax, isScopeForResource } from '../syntax.js'
+
+const IDENTITY_ATTRIBUTES = Object.freeze(['handle', '*'] as const)
+export type IdentityAttribute = (typeof IDENTITY_ATTRIBUTES)[number]
+
+export const identityParser = new Parser(
+  'identity',
+  {
+    attr: {
+      multiple: false,
+      required: true,
+      validate: knownValuesValidator(IDENTITY_ATTRIBUTES),
+    },
+  },
+  'attr',
+)
+
+export type IdentityScopeMatch = {
+  attr: IdentityAttribute
+}
+
+export class IdentityScope {
+  constructor(public readonly attr: IdentityAttribute) {}
+
+  matches(options: IdentityScopeMatch): boolean {
+    return this.attr === '*' || this.attr === options.attr
+  }
+
+  toString() {
+    return identityParser.format(this)
+  }
+
+  static fromString(scope: string) {
+    if (!isScopeForResource(scope, 'identity')) return null
+    const syntax = ResourceSyntax.fromString(scope)
+    return this.fromSyntax(syntax)
+  }
+
+  static fromSyntax(syntax: ResourceSyntax) {
+    const result = identityParser.parse(syntax)
+    if (!result) return null
+    return new IdentityScope(result.attr)
+  }
+
+  static scopeNeededFor(options: IdentityScopeMatch): string {
+    return identityParser.format(options)
+  }
+}