@atproto/oauth-scopes 0.0.2 → 0.2.0

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

@@ -1,9 +1,9 @@
-import { PermissionSet } from './permission-set.js'
+import { ScopePermissions } from './scope-permissions.js'
 
-describe('PermissionSet', () => {
+describe('ScopePermissions', () => {
   describe('allowsAccount', () => {
     it('should properly allow "account:email"', () => {
-      const set = new PermissionSet('account:email')
+      const set = new ScopePermissions('account:email')
 
       expect(set.allowsAccount({ attr: 'email', action: 'read' })).toBe(true)
       expect(set.allowsAccount({ attr: 'email', action: 'manage' })).toBe(false)
@@ -18,7 +18,7 @@ describe('PermissionSet', () => {
     })
 
     it('should ignore "transition:email"', () => {
-      const set = new PermissionSet('transition:email')
+      const set = new ScopePermissions('transition:email')
 
       expect(set.allowsAccount({ attr: 'email', action: 'read' })).toBe(false)
       expect(set.allowsAccount({ attr: 'email', action: 'manage' })).toBe(false)
@@ -27,31 +27,31 @@ describe('PermissionSet', () => {
 
   describe('allowsBlob', () => {
     it('should allow any mime with "blob:*/*"', () => {
-      const set = new PermissionSet('blob:*/*')
+      const set = new ScopePermissions('blob:*/*')
       expect(set.allowsBlob({ mime: 'image/png' })).toBe(true)
       expect(set.allowsBlob({ mime: 'application/json' })).toBe(true)
     })
 
     it('should only allow images with "blob:image/*"', () => {
-      const set = new PermissionSet('blob:image/*')
+      const set = new ScopePermissions('blob:image/*')
       expect(set.allowsBlob({ mime: 'image/png' })).toBe(true)
       expect(set.allowsBlob({ mime: 'application/json' })).toBe(false)
     })
 
     it('should ignore invalid scope "blob:*"', () => {
-      const set = new PermissionSet('blob:*')
+      const set = new ScopePermissions('blob:*')
       expect(set.allowsBlob({ mime: 'image/png' })).toBe(false)
       expect(set.allowsBlob({ mime: 'application/json' })).toBe(false)
     })
 
     it('should ignore invalid scope "blob:/image"', () => {
-      const set = new PermissionSet('blob:/image')
+      const set = new ScopePermissions('blob:/image')
       expect(set.allowsBlob({ mime: 'image/png' })).toBe(false)
       expect(set.allowsBlob({ mime: 'application/json' })).toBe(false)
     })
 
     it('should ignore "transition:generic"', () => {
-      const set = new PermissionSet('transition:generic')
+      const set = new ScopePermissions('transition:generic')
       expect(set.allowsBlob({ mime: 'image/png' })).toBe(false)
       expect(set.allowsBlob({ mime: 'application/json' })).toBe(false)
     })
@@ -59,7 +59,7 @@ describe('PermissionSet', () => {
 
   describe('allowsRepo', () => {
     it('should allow any repo action with "repo:*"', () => {
-      const set = new PermissionSet('repo:*')
+      const set = new ScopePermissions('repo:*')
       expect(
         set.allowsRepo({ collection: 'com.example.foo', action: 'create' }),
       ).toBe(true)
@@ -72,7 +72,7 @@ describe('PermissionSet', () => {
     })
 
     it('should allow specific repo actions', () => {
-      const set = new PermissionSet('repo:*?action=create')
+      const set = new ScopePermissions('repo:*?action=create')
       expect(
         set.allowsRepo({ collection: 'com.example.foo', action: 'create' }),
       ).toBe(true)
@@ -91,7 +91,7 @@ describe('PermissionSet', () => {
     })
 
     it('should allow specific repo collection & actions', () => {
-      const set = new PermissionSet('repo:com.example.foo?action=create')
+      const set = new ScopePermissions('repo:com.example.foo?action=create')
       expect(
         set.allowsRepo({ collection: 'com.example.foo', action: 'create' }),
       ).toBe(true)
@@ -110,7 +110,7 @@ describe('PermissionSet', () => {
     })
 
     it('should ignore transition:generic', () => {
-      const set = new PermissionSet('transition:generic')
+      const set = new ScopePermissions('transition:generic')
       expect(
         set.allowsRepo({ collection: 'app.bsky.feed.post', action: 'create' }),
       ).toBe(false)
@@ -128,19 +128,28 @@ describe('PermissionSet', () => {
 
   describe('allowsRpc', () => {
     it('should ignore "rpc:*?lxm=*"', () => {
-      const set = new PermissionSet('rpc:*?lxm=*')
+      const set = new ScopePermissions('rpc:*?lxm=*')
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.method' }),
+        set.allowsRpc({
+          aud: 'did:web:example.com',
+          lxm: 'com.example.method',
+        }),
       ).toBe(false)
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.getFeed' }),
+        set.allowsRpc({
+          aud: 'did:web:example.com',
+          lxm: 'app.bsky.feed.getFeed',
+        }),
       ).toBe(false)
     })
 
     it('should allow constraining "lxm"', () => {
-      const set = new PermissionSet('rpc:app.bsky.feed.getFeed?aud=*')
+      const set = new ScopePermissions('rpc:app.bsky.feed.getFeed?aud=*')
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.getFeed' }),
+        set.allowsRpc({
+          aud: 'did:web:example.com',
+          lxm: 'app.bsky.feed.getFeed',
+        }),
       ).toBe(true)
       expect(
         set.allowsRpc({ aud: 'did:plc:blahbla', lxm: 'app.bsky.feed.getFeed' }),
@@ -149,38 +158,62 @@ describe('PermissionSet', () => {
       // Control
 
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.method' }),
+        set.allowsRpc({
+          aud: 'did:web:example.com',
+          lxm: 'com.example.method',
+        }),
       ).toBe(false)
     })
 
     it('should allow constraining "aud"', () => {
-      const set = new PermissionSet('rpc:*?aud=did:example:123')
+      const set = new ScopePermissions('rpc:*?aud=did:web:example.com%23foo')
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.method' }),
+        set.allowsRpc({
+          aud: 'did:web:example.com#foo',
+          lxm: 'com.example.method',
+        }),
       ).toBe(true)
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.getFeed' }),
+        set.allowsRpc({
+          aud: 'did:web:example.com#foo',
+          lxm: 'app.bsky.feed.getFeed',
+        }),
       ).toBe(true)
 
       // Control
 
       expect(
-        set.allowsRpc({ aud: 'did:plc:blahbla', lxm: 'com.example.method' }),
+        set.allowsRpc({
+          aud: 'did:web:bar.com#foo', // invalid aud (wrong service id)
+          lxm: 'com.example.method',
+        }),
+      ).toBe(false)
+      expect(
+        set.allowsRpc({
+          aud: 'did:web:example.com', // invalid aud (no service id)
+          lxm: 'com.example.method',
+        }),
       ).toBe(false)
     })
 
     it('should allow constraining "lxm" and "aud"', () => {
-      const set = new PermissionSet(
-        'rpc:app.bsky.feed.getFeed?aud=did:example:123',
+      const set = new ScopePermissions(
+        'rpc:app.bsky.feed.getFeed?aud=did:web:example.com%23foo',
       )
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.getFeed' }),
+        set.allowsRpc({
+          aud: 'did:web:example.com#foo',
+          lxm: 'app.bsky.feed.getFeed',
+        }),
       ).toBe(true)
 
       // Control
 
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.method' }),
+        set.allowsRpc({
+          aud: 'did:web:example.com',
+          lxm: 'com.example.method',
+        }),
       ).toBe(false)
       expect(
         set.allowsRpc({ aud: 'did:plc:blahbla', lxm: 'app.bsky.feed.getFeed' }),
@@ -188,26 +221,32 @@ describe('PermissionSet', () => {
     })
 
     it('should ignore "transition:generic"', () => {
-      const set = new PermissionSet('transition:generic')
+      const set = new ScopePermissions('transition:generic')
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.getFeed' }),
+        set.allowsRpc({
+          aud: 'did:web:example.com',
+          lxm: 'app.bsky.feed.getFeed',
+        }),
       ).toBe(false)
       expect(
-        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.method' }),
+        set.allowsRpc({
+          aud: 'did:web:example.com',
+          lxm: 'com.example.method',
+        }),
       ).toBe(false)
     })
 
     it('should ignore "transition:chat.bsky"', () => {
-      const set = new PermissionSet('transition:chat.bsky')
+      const set = new ScopePermissions('transition:chat.bsky')
       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)
@@ -215,10 +254,13 @@ describe('PermissionSet', () => {
       // 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)
     })
   })

package/src/scope-permissions.ts

@@ -0,0 +1,91 @@
+import { ScopeMissingError } from './scope-missing-error.js'
+import {
+  AccountPermission,
+  AccountPermissionMatch,
+} from './scopes/account-permission.js'
+import {
+  BlobPermission,
+  BlobPermissionMatch,
+} from './scopes/blob-permission.js'
+import {
+  IdentityPermission,
+  IdentityPermissionMatch,
+} from './scopes/identity-permission.js'
+import {
+  RepoPermission,
+  RepoPermissionMatch,
+} from './scopes/repo-permission.js'
+import { RpcPermission, RpcPermissionMatch } from './scopes/rpc-permission.js'
+import { ScopesSet } from './scopes-set.js'
+
+export type {
+  AccountPermissionMatch,
+  BlobPermissionMatch,
+  IdentityPermissionMatch,
+  RepoPermissionMatch,
+  RpcPermissionMatch,
+}
+
+export class ScopePermissions {
+  public readonly scopes: ScopesSet
+
+  constructor(scope?: null | string | Iterable<string>) {
+    this.scopes = new ScopesSet(
+      !scope // "" | null | undefined
+        ? undefined
+        : typeof scope === 'string'
+          ? scope.split(' ')
+          : scope,
+    )
+  }
+
+  public allowsAccount(options: AccountPermissionMatch): boolean {
+    return this.scopes.matches('account', options)
+  }
+  public assertAccount(options: AccountPermissionMatch): void {
+    if (!this.allowsAccount(options)) {
+      const scope = AccountPermission.scopeNeededFor(options)
+      throw new ScopeMissingError(scope)
+    }
+  }
+
+  public allowsIdentity(options: IdentityPermissionMatch): boolean {
+    return this.scopes.matches('identity', options)
+  }
+  public assertIdentity(options: IdentityPermissionMatch): void {
+    if (!this.allowsIdentity(options)) {
+      const scope = IdentityPermission.scopeNeededFor(options)
+      throw new ScopeMissingError(scope)
+    }
+  }
+
+  public allowsBlob(options: BlobPermissionMatch): boolean {
+    return this.scopes.matches('blob', options)
+  }
+  public assertBlob(options: BlobPermissionMatch): void {
+    if (!this.allowsBlob(options)) {
+      const scope = BlobPermission.scopeNeededFor(options)
+      throw new ScopeMissingError(scope)
+    }
+  }
+
+  public allowsRepo(options: RepoPermissionMatch): boolean {
+    return this.scopes.matches('repo', options)
+  }
+  public assertRepo(options: RepoPermissionMatch): void {
+    if (!this.allowsRepo(options)) {
+      const scope = RepoPermission.scopeNeededFor(options)
+      throw new ScopeMissingError(scope)
+    }
+  }
+
+  public allowsRpc(options: RpcPermissionMatch): boolean {
+    return this.scopes.matches('rpc', options)
+  }
+  public assertRpc(options: RpcPermissionMatch): void {
+    if (!this.allowsRpc(options)) {
+      const scope = RpcPermission.scopeNeededFor(options)
+      throw new ScopeMissingError(scope)
+    }
+  }
+}

package/src/{resources/account-scope.test.ts → scopes/account-permission.test.ts}

@@ -1,67 +1,71 @@
-import { AccountScope } from './account-scope.js'
+import { AccountPermission } from './account-permission.js'
 
-describe('AccountScope', () => {
+describe('AccountPermission', () => {
   describe('static', () => {
     describe('fromString', () => {
       it('should parse valid scope strings', () => {
-        const scope1 = AccountScope.fromString('account:email?action=read')
+        const scope1 = AccountPermission.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')
+        const scope2 = AccountPermission.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')
+        const scope = AccountPermission.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')
+        const scope = AccountPermission.fromString('account:invalid')
         expect(scope).toBeNull()
       })
 
       it('should reject invalid action names', () => {
-        const scope = AccountScope.fromString('account:email?action=invalid')
+        const scope = AccountPermission.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()
+        expect(AccountPermission.fromString('invalid:email')).toBeNull()
+        expect(AccountPermission.fromString('account')).toBeNull()
+        expect(AccountPermission.fromString('')).toBeNull()
+        expect(AccountPermission.fromString('account:')).toBeNull()
       })
     })
 
     describe('scopeNeededFor', () => {
       it('should return correct scope string for read actions', () => {
         expect(
-          AccountScope.scopeNeededFor({ attr: 'email', action: 'read' }),
+          AccountPermission.scopeNeededFor({ attr: 'email', action: 'read' }),
         ).toBe('account:email')
         expect(
-          AccountScope.scopeNeededFor({ attr: 'repo', action: 'read' }),
+          AccountPermission.scopeNeededFor({ attr: 'repo', action: 'read' }),
         ).toBe('account:repo')
         expect(
-          AccountScope.scopeNeededFor({ attr: 'status', action: 'read' }),
+          AccountPermission.scopeNeededFor({ attr: 'status', action: 'read' }),
         ).toBe('account:status')
       })
 
       it('should return correct scope string for manage actions', () => {
         expect(
-          AccountScope.scopeNeededFor({ attr: 'email', action: 'manage' }),
+          AccountPermission.scopeNeededFor({ attr: 'email', action: 'manage' }),
         ).toBe('account:email?action=manage')
         expect(
-          AccountScope.scopeNeededFor({ attr: 'repo', action: 'manage' }),
+          AccountPermission.scopeNeededFor({ attr: 'repo', action: 'manage' }),
         ).toBe('account:repo?action=manage')
         expect(
-          AccountScope.scopeNeededFor({
+          AccountPermission.scopeNeededFor({
             attr: 'status',
             action: 'manage',
           }),
@@ -73,40 +77,44 @@ describe('AccountScope', () => {
   describe('instance', () => {
     describe('matches', () => {
       it('should match read action', () => {
-        const scope = AccountScope.fromString('account:email?action=read')
+        const scope = AccountPermission.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')
+        const scope = AccountPermission.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')
+        const scope = AccountPermission.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')
+        const scope = AccountPermission.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')
+        const scope = AccountPermission.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(
+        const emailScope = AccountPermission.fromString(
+          'account:email?action=read',
+        )
+        const repoScope = AccountPermission.fromString(
+          'account:repo?action=manage',
+        )
+        const statusScope = AccountPermission.fromString(
           'account:status?action=read',
         )
 
@@ -126,7 +134,9 @@ describe('AccountScope', () => {
       })
 
       it('should allow read when "manage" action is specified', () => {
-        const scope = AccountScope.fromString('account:email?action=manage')
+        const scope = AccountPermission.fromString(
+          'account:email?action=manage',
+        )
         expect(scope).not.toBeNull()
         expect(scope!.matches({ attr: 'email', action: 'read' })).toBe(true)
       })
@@ -134,24 +144,26 @@ describe('AccountScope', () => {
 
     describe('toString', () => {
       it('should format scope with explicit action', () => {
-        const scope = new AccountScope('email', 'manage')
+        const scope = new AccountPermission('email', 'manage')
         expect(scope.toString()).toBe('account:email?action=manage')
       })
 
       it('should format scope with default action', () => {
-        const scope = new AccountScope('repo', 'read')
+        const scope = new AccountPermission('repo', 'read')
         expect(scope.toString()).toBe('account:repo')
       })
 
       it('should format all attributes correctly', () => {
-        expect(new AccountScope('email', 'read').toString()).toBe(
+        expect(new AccountPermission('email', 'read').toString()).toBe(
           'account:email',
         )
-        expect(new AccountScope('repo', 'read').toString()).toBe('account:repo')
-        expect(new AccountScope('status', 'read').toString()).toBe(
+        expect(new AccountPermission('repo', 'read').toString()).toBe(
+          'account:repo',
+        )
+        expect(new AccountPermission('status', 'read').toString()).toBe(
           'account:status',
         )
-        expect(new AccountScope('email', 'manage').toString()).toBe(
+        expect(new AccountPermission('email', 'manage').toString()).toBe(
           'account:email?action=manage',
         )
       })
@@ -169,7 +181,7 @@ describe('AccountScope', () => {
     ]
 
     for (const scope of testCases) {
-      expect(AccountScope.fromString(scope)?.toString()).toBe(scope)
+      expect(AccountPermission.fromString(scope)?.toString()).toBe(scope)
     }
   })
 })

package/src/scopes/account-permission.ts

@@ -0,0 +1,75 @@
+import { Parser } from '../lib/parser.js'
+import { ResourcePermission } from '../lib/resource-permission.js'
+import { ScopeStringSyntax } from '../lib/syntax-string.js'
+import { ScopeSyntax, isScopeStringFor } from '../lib/syntax.js'
+import { knownValuesValidator } from '../lib/util.js'
+
+export const ACCOUNT_ATTRIBUTES = Object.freeze([
+  'email',
+  'repo',
+  'status',
+] as const)
+export type AccountAttribute = (typeof ACCOUNT_ATTRIBUTES)[number]
+
+export const ACCOUNT_ACTIONS = Object.freeze(['read', 'manage'] as const)
+export type AccountAction = (typeof ACCOUNT_ACTIONS)[number]
+
+export type AccountPermissionMatch = {
+  attr: AccountAttribute
+  action: AccountAction
+}
+
+export class AccountPermission
+  implements ResourcePermission<'account', AccountPermissionMatch>
+{
+  constructor(
+    public readonly attr: AccountAttribute,
+    public readonly action: AccountAction,
+  ) {}
+
+  matches(options: AccountPermissionMatch) {
+    return (
+      this.attr === options.attr &&
+      (this.action === 'manage' || this.action === options.action)
+    )
+  }
+
+  toString() {
+    return AccountPermission.parser.format(this)
+  }
+
+  protected static readonly parser = 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',
+  )
+
+  static fromString(scope: string) {
+    if (!isScopeStringFor(scope, 'account')) return null
+    const syntax = ScopeStringSyntax.fromString(scope)
+    return AccountPermission.fromSyntax(syntax)
+  }
+
+  static fromSyntax(syntax: ScopeSyntax<'account'>) {
+    const result = AccountPermission.parser.parse(syntax)
+    if (!result) return null
+
+    return new AccountPermission(result.attr, result.action)
+  }
+
+  static scopeNeededFor(options: AccountPermissionMatch) {
+    return AccountPermission.parser.format(options)
+  }
+}