@atproto/oauth-scopes 0.0.2 → 0.2.0

package/src/scopes/include-scope.ts

@@ -0,0 +1,168 @@
+import { AtprotoAudience, isAtprotoAudience } from '@atproto/did'
+import { LexPermission, LexPermissionSet } from '../lib/lexicon.js'
+import { Nsid, isNsid } from '../lib/nsid.js'
+import { Parser } from '../lib/parser.js'
+import { LexPermissionSyntax } from '../lib/syntax-lexicon.js'
+import { ScopeStringSyntax } from '../lib/syntax-string.js'
+import { ScopeSyntax, isScopeStringFor } from '../lib/syntax.js'
+import { BlobPermission } from './blob-permission.js'
+import { RepoPermission } from './repo-permission.js'
+import { RpcPermission } from './rpc-permission.js'
+
+export { type LexPermission, type LexPermissionSet, type Nsid, isNsid }
+
+/**
+ * This is used to handle "include:" oauth scope values, used to include
+ * permissions from a lexicon defined permission set. Not being a resource
+ * permission, it does not implement `Matchable`.
+ */
+export class IncludeScope {
+  constructor(
+    public readonly nsid: Nsid,
+    public readonly aud: undefined | AtprotoAudience = undefined,
+  ) {}
+
+  toString() {
+    return IncludeScope.parser.format(this)
+  }
+
+  /**
+   * Converts an "include:" to the list of permissions it includes, based on the
+   * lexicon defined permission set.
+   */
+  toPermissions(permissionSet: LexPermissionSet) {
+    return permissionSet.permissions
+      .map(this.parsePermission, this)
+      .filter(this.isAllowedPermission, this)
+  }
+
+  protected parsePermission(permission: LexPermission) {
+    if (
+      permission.resource === 'rpc' &&
+      permission.inheritAud === true &&
+      permission.aud === undefined &&
+      this.aud !== undefined
+    ) {
+      // "rpc" permissions can "inherit" their audience from "aud" param defined
+      // in the "include:<nsid>?aud=<audience>" scope the permission set was
+      // loaded from.
+      return parsePermission({
+        ...permission,
+        inheritAud: undefined,
+        aud: this.aud,
+      })
+    }
+
+    return parsePermission(permission)
+  }
+
+  /**
+   * Verifies that a permission included through a lexicon permission set is
+   * allowed in the context of the `include:` scope. This basically checks that
+   * the permission is "under" the namespace authority of the `include:` scope,
+   * and that it only contains "repo:", "rpc:", or "blob:" permissions.
+   */
+  protected isAllowedPermission(
+    permission: unknown,
+  ): permission is RpcPermission | RepoPermission | BlobPermission {
+    if (permission instanceof RpcPermission) {
+      return permission.lxm.every(this.isParentAuthorityOf, this)
+    }
+
+    if (permission instanceof RepoPermission) {
+      return permission.collection.every(this.isParentAuthorityOf, this)
+    }
+
+    if (permission instanceof BlobPermission) {
+      return true
+    }
+
+    return false
+  }
+
+  /**
+   * Verifies that a permission item's nsid is under the same authority as the
+   * nsid of the lexicon itself (which is the same as the nsid of the `include:`
+   * scope).
+   */
+  public isParentAuthorityOf(otherNsid: '*' | Nsid) {
+    if (otherNsid === '*') {
+      return false
+    }
+
+    const lexiconNsid = this.nsid
+
+    const groupPrefixEnd = lexiconNsid.lastIndexOf('.')
+
+    // There should always be a dot, but since this is a security feature, let's
+    // be strict about it.
+    if (groupPrefixEnd === -1) {
+      throw new TypeError('Dot character (".") missing from lexicon NSID')
+    }
+
+    // Make sure that otherNsid is at least as long as the "group prefix"
+    if (groupPrefixEnd >= otherNsid.length - 1) {
+      return false
+    }
+
+    // Make sure that the "otherNsid" starts with the group of the lexiconNsid,
+    // up to the dot itself. We check in reverse order as nsids tend to have
+    // long common prefixes.
+    for (let i = groupPrefixEnd; i >= 0; i--) {
+      if (lexiconNsid.charCodeAt(i) !== otherNsid.charCodeAt(i)) {
+        return false
+      }
+    }
+
+    return true
+  }
+
+  protected static readonly parser = new Parser(
+    'include',
+    {
+      nsid: {
+        multiple: false,
+        required: true,
+        validate: isNsid,
+      },
+      aud: {
+        multiple: false,
+        required: false,
+        validate: isAtprotoAudience,
+      },
+    },
+    'nsid',
+  )
+
+  static fromString(scope: string) {
+    if (!isScopeStringFor(scope, 'include')) return null
+    const syntax = ScopeStringSyntax.fromString(scope)
+    return IncludeScope.fromSyntax(syntax)
+  }
+
+  static fromSyntax(syntax: ScopeSyntax<'include'>) {
+    const result = IncludeScope.parser.parse(syntax)
+    if (!result) return null
+    return new IncludeScope(result.nsid, result.aud)
+  }
+}
+
+function parsePermission(permission: LexPermission) {
+  if (isPermissionForResource(permission, 'repo')) {
+    return RepoPermission.fromSyntax(new LexPermissionSyntax(permission))
+  }
+  if (isPermissionForResource(permission, 'rpc')) {
+    return RpcPermission.fromSyntax(new LexPermissionSyntax(permission))
+  }
+  if (isPermissionForResource(permission, 'blob')) {
+    return BlobPermission.fromSyntax(new LexPermissionSyntax(permission))
+  }
+  return null
+}
+
+function isPermissionForResource<P extends LexPermission, T extends string>(
+  permission: P,
+  type: T,
+): permission is P & { resource: T } {
+  return permission.resource === type
+}

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

@@ -1,33 +1,33 @@
-import { RepoScope } from './repo-scope.js'
+import { RepoPermission } from './repo-permission.js'
 
-describe('RepoScope', () => {
+describe('RepoPermission', () => {
   describe('static', () => {
     describe('fromString', () => {
       it('should parse positional scope', () => {
-        const scope = RepoScope.fromString('repo:foo.bar')
+        const scope = RepoPermission.fromString('repo:com.example.foo')
         expect(scope).not.toBeNull()
-        expect(scope!.collection).toEqual(['foo.bar'])
+        expect(scope!.collection).toEqual(['com.example.foo'])
         expect(scope!.action).toEqual(['create', 'update', 'delete'])
       })
 
       it('should parse valid repo scope with multiple actions', () => {
-        const scope = RepoScope.fromString(
-          'repo:foo.bar?action=create&action=update',
+        const scope = RepoPermission.fromString(
+          'repo:com.example.foo?action=create&action=update',
         )
         expect(scope).not.toBeNull()
-        expect(scope!.collection).toEqual(['foo.bar'])
+        expect(scope!.collection).toEqual(['com.example.foo'])
         expect(scope!.action).toEqual(['create', 'update'])
       })
 
       it('should parse valid repo scope without actions (defaults to create, update, delete)', () => {
-        const scope = RepoScope.fromString('repo:foo.bar')
+        const scope = RepoPermission.fromString('repo:com.example.foo')
         expect(scope).not.toBeNull()
-        expect(scope!.collection).toEqual(['foo.bar'])
+        expect(scope!.collection).toEqual(['com.example.foo'])
         expect(scope!.action).toEqual(['create', 'update', 'delete'])
       })
 
       it('should allow wildcard collection with specific action', () => {
-        const scope = RepoScope.fromString('repo:*?action=create')
+        const scope = RepoPermission.fromString('repo:*?action=create')
         expect(scope).not.toBeNull()
         expect(scope!.collection).toEqual(['*'])
         expect(scope!.action).toEqual(['create'])
@@ -40,7 +40,7 @@ describe('RepoScope', () => {
       })
 
       it('should allow wildcard collection without actions', () => {
-        const scope = RepoScope.fromString('repo:*')
+        const scope = RepoPermission.fromString('repo:*')
         expect(scope).not.toBeNull()
         expect(scope!.collection).toEqual(['*'])
         expect(scope!.action).toEqual(['create', 'update', 'delete'])
@@ -56,60 +56,63 @@ describe('RepoScope', () => {
       })
 
       it('should ignore scopes with invalid collection names', () => {
-        expect(RepoScope.fromString('repo:foo bar')).toBeNull()
-        expect(RepoScope.fromString('repo:.foo')).toBeNull()
-        expect(RepoScope.fromString('repo:bar.')).toBeNull()
+        expect(RepoPermission.fromString('repo:foo bar')).toBeNull()
+        expect(RepoPermission.fromString('repo:.foo')).toBeNull()
+        expect(RepoPermission.fromString('repo:bar.')).toBeNull()
       })
 
       it('should reject invalid action names', () => {
-        const scope = RepoScope.fromString('repo:foo.bar?action=invalid')
+        const scope = RepoPermission.fromString(
+          'repo:com.example.foo?action=invalid',
+        )
         expect(scope).toBeNull()
       })
 
       it('should return null for invalid repo scope', () => {
-        expect(RepoScope.fromString('invalid')).toBeNull()
-        expect(RepoScope.fromString('scope')).toBeNull()
+        expect(RepoPermission.fromString('invalid')).toBeNull()
+        expect(RepoPermission.fromString('scope')).toBeNull()
       })
 
       for (const invalid of [
         'repo:*?action=*',
         'invalid',
         'repo:invalid',
-        'repo:foo.bar?action=invalid',
+        'repo:com.example.foo?action=invalid',
         'repo?collection=invalid&action=invalid',
       ]) {
         it(`should return null for invalid rpc scope: ${invalid}`, () => {
-          expect(RepoScope.fromString(invalid)).toBeNull()
+          expect(RepoPermission.fromString(invalid)).toBeNull()
         })
       }
     })
 
     describe('scopeNeededFor', () => {
       it('should return correct scope string for specific collection and action', () => {
-        const scope = RepoScope.scopeNeededFor({
-          collection: 'foo.bar',
+        const scope = RepoPermission.scopeNeededFor({
+          collection: 'com.example.foo',
           action: 'create',
         })
-        expect(scope).toBe('repo:foo.bar?action=create')
+        expect(scope).toBe('repo:com.example.foo?action=create')
       })
 
       it('should return scope that accepts all collections with specific action', () => {
-        const scope = RepoScope.scopeNeededFor({
+        const scope = RepoPermission.scopeNeededFor({
           collection: '*',
           action: 'create',
         })
         expect(scope).toBe('repo:*?action=create')
       })
 
-      it('ignores invalid collection names', () => {
+      it('ignores invalid options', () => {
         // @NOTE the scopeNeededFor assumes valid input, so it does not validate
         // collection or action.
-        const scope = RepoScope.scopeNeededFor({
-          collection: 'invalid',
-          // @ts-expect-error
-          action: 'not-an-action',
-        })
-        expect(scope).toBe('repo:invalid?action=not-an-action')
+
+        expect(
+          RepoPermission.scopeNeededFor({
+            collection: 'invalid',
+            action: 'create',
+          }),
+        ).toBe('repo:invalid?action=create')
       })
     })
   })
@@ -117,74 +120,81 @@ describe('RepoScope', () => {
   describe('instance', () => {
     describe('matches', () => {
       it('should match create action', () => {
-        const scope = RepoScope.fromString('repo:foo.bar?action=create')
+        const scope = RepoPermission.fromString(
+          'repo:com.example.foo?action=create',
+        )
         expect(scope).not.toBeNull()
         expect(
-          scope!.matches({ action: 'create', collection: 'foo.bar' }),
+          scope!.matches({ action: 'create', collection: 'com.example.foo' }),
         ).toBe(true)
       })
 
       it('should not match unspecified action', () => {
-        const scope = RepoScope.fromString('repo:foo.bar?action=create')
+        const scope = RepoPermission.fromString(
+          'repo:com.example.foo?action=create',
+        )
         expect(scope).not.toBeNull()
         expect(
-          scope!.matches({ action: 'update', collection: 'foo.bar' }),
+          scope!.matches({ action: 'update', collection: 'com.example.foo' }),
         ).toBe(false)
       })
 
       it('should match wildcard collection', () => {
-        const scope = RepoScope.fromString('repo:*?action=create')
+        const scope = RepoPermission.fromString('repo:*?action=create')
         expect(scope).not.toBeNull()
         expect(
-          scope!.matches({ action: 'create', collection: 'any.collection' }),
+          scope!.matches({ action: 'create', collection: 'com.example.bar' }),
         ).toBe(true)
       })
 
       it('should not match different action with wildcard collection', () => {
-        const scope = RepoScope.fromString('repo:*?action=create')
+        const scope = RepoPermission.fromString('repo:*?action=create')
         expect(scope).not.toBeNull()
         expect(
-          scope!.matches({ action: 'delete', collection: 'any.collection' }),
+          scope!.matches({ action: 'delete', collection: 'com.example.bar' }),
         ).toBe(false)
       })
 
       it('should match multiple actions', () => {
-        const scope = RepoScope.fromString(
-          'repo:foo.bar?action=create&action=update',
+        const scope = RepoPermission.fromString(
+          'repo:com.example.foo?action=create&action=update',
         )
         expect(scope).not.toBeNull()
         expect(
-          scope!.matches({ action: 'create', collection: 'foo.bar' }),
+          scope!.matches({ action: 'create', collection: 'com.example.foo' }),
         ).toBe(true)
         expect(
-          scope!.matches({ action: 'update', collection: 'foo.bar' }),
+          scope!.matches({ action: 'update', collection: 'com.example.foo' }),
         ).toBe(true)
         expect(
-          scope!.matches({ action: 'delete', collection: 'foo.bar' }),
+          scope!.matches({ action: 'delete', collection: 'com.example.foo' }),
         ).toBe(false)
       })
 
       it('should default to "create", "update", and "delete" actions', () => {
-        const scope = RepoScope.fromString('repo:foo.bar')
+        const scope = RepoPermission.fromString('repo:com.example.foo')
         expect(scope).not.toBeNull()
         expect(
-          scope!.matches({ action: 'create', collection: 'foo.bar' }),
+          scope!.matches({ action: 'create', collection: 'com.example.foo' }),
         ).toBe(true)
         expect(
-          scope!.matches({ action: 'update', collection: 'foo.bar' }),
+          scope!.matches({ action: 'update', collection: 'com.example.foo' }),
         ).toBe(true)
         expect(
-          scope!.matches({ action: 'delete', collection: 'foo.bar' }),
+          scope!.matches({ action: 'delete', collection: 'com.example.foo' }),
         ).toBe(true)
       })
     })
 
     describe('toString', () => {
       it('should format repo scope correctly', () => {
-        const scope = new RepoScope(['foo.bar'], ['create', 'update'])
+        const scope = new RepoPermission(
+          ['com.example.foo'],
+          ['create', 'update'],
+        )
         expect(scope).not.toBeNull()
         expect(scope!.toString()).toBe(
-          'repo:foo.bar?action=create&action=update',
+          'repo:com.example.foo?action=create&action=update',
         )
       })
     })
@@ -192,22 +202,22 @@ describe('RepoScope', () => {
 
   describe('consistency', () => {
     const testCases: { input: string; expected: string }[] = [
-      { input: 'repo:foo.bar', expected: 'repo:foo.bar' },
+      { input: 'repo:com.example.foo', expected: 'repo:com.example.foo' },
       {
-        input: 'repo:foo.bar?action=create',
-        expected: 'repo:foo.bar?action=create',
+        input: 'repo:com.example.foo?action=create',
+        expected: 'repo:com.example.foo?action=create',
       },
       {
-        input: 'repo:foo.bar?action=create&action=update',
-        expected: 'repo:foo.bar?action=create&action=update',
+        input: 'repo:com.example.foo?action=create&action=update',
+        expected: 'repo:com.example.foo?action=create&action=update',
       },
       {
         input: 'repo:*?action=create&action=update&action=delete',
         expected: 'repo:*',
       },
       {
-        input: 'repo:foo.bar?action=create&action=update&action=delete',
-        expected: 'repo:foo.bar',
+        input: 'repo:com.example.foo?action=create&action=update&action=delete',
+        expected: 'repo:com.example.foo',
       },
       { input: 'repo:*?action=create', expected: 'repo:*?action=create' },
       { input: 'repo:*?action=update', expected: 'repo:*?action=update' },
@@ -216,7 +226,7 @@ describe('RepoScope', () => {
         expected: 'repo:*?action=update',
       },
       {
-        input: 'repo?collection=*&collection=foo.bar&action=update',
+        input: 'repo?collection=*&collection=com.example.foo&action=update',
         expected: 'repo:*?action=update',
       },
       {
@@ -228,27 +238,29 @@ describe('RepoScope', () => {
         expected: 'repo:*',
       },
       {
-        input: 'repo?collection=*&collection=foo.bar',
+        input: 'repo?collection=*&collection=com.example.foo',
         expected: 'repo:*',
       },
       {
-        input: 'repo?action=create&collection=foo.bar',
-        expected: 'repo:foo.bar?action=create',
+        input: 'repo?action=create&collection=com.example.foo',
+        expected: 'repo:com.example.foo?action=create',
       },
       {
         input:
-          'repo?collection=foo.bar&action=create&action=update&action=delete',
-        expected: 'repo:foo.bar',
+          'repo?collection=com.example.foo&action=create&action=update&action=delete',
+        expected: 'repo:com.example.foo',
       },
       {
-        input: 'repo?action=create&collection=foo.bar&collection=baz.qux',
-        expected: 'repo?collection=baz.qux&collection=foo.bar&action=create',
+        input:
+          'repo?action=create&collection=com.example.foo&collection=com.example.bar',
+        expected:
+          'repo?collection=com.example.bar&collection=com.example.foo&action=create',
       },
     ]
 
     for (const { input, expected } of testCases) {
       it(`should properly re-format ${input}`, () => {
-        expect(RepoScope.fromString(input)?.toString()).toBe(expected)
+        expect(RepoPermission.fromString(input)?.toString()).toBe(expected)
       })
     }
   })

package/src/scopes/repo-permission.ts

@@ -0,0 +1,111 @@
+import { Nsid, isNsid } from '../lib/nsid.js'
+import { Parser } from '../lib/parser.js'
+import { ResourcePermission } from '../lib/resource-permission.js'
+import { ScopeStringSyntax } from '../lib/syntax-string.js'
+import {
+  NeArray,
+  NeRoArray,
+  ScopeSyntax,
+  isScopeStringFor,
+} from '../lib/syntax.js'
+import { knownValuesValidator } from '../lib/util.js'
+
+export { type Nsid, isNsid }
+
+export const REPO_ACTIONS = Object.freeze([
+  'create',
+  'update',
+  'delete',
+] as const)
+export type RepoAction = (typeof REPO_ACTIONS)[number]
+export const isRepoAction = knownValuesValidator(REPO_ACTIONS)
+
+export type CollectionParam = '*' | Nsid
+export const isCollectionParam = (value: unknown): value is CollectionParam =>
+  value === '*' || isNsid(value)
+
+export type RepoPermissionMatch = {
+  collection: string
+  action: RepoAction
+}
+
+export class RepoPermission
+  implements ResourcePermission<'repo', RepoPermissionMatch>
+{
+  constructor(
+    public readonly collection: NeRoArray<'*' | Nsid>,
+    public readonly action: NeRoArray<RepoAction>,
+  ) {}
+
+  matches({ action, collection }: RepoPermissionMatch) {
+    return (
+      this.action.includes(action) &&
+      (this.collection.includes('*') ||
+        (this.collection as readonly string[]).includes(collection))
+    )
+  }
+
+  toString() {
+    return RepoPermission.parser.format(this)
+  }
+
+  protected static readonly parser = new Parser(
+    'repo',
+    {
+      collection: {
+        multiple: true,
+        required: true,
+        validate: isCollectionParam,
+        normalize: (value) => {
+          if (value.length > 1) {
+            if (value.includes('*')) return ['*'] as const
+            return [...new Set(value)].sort() as NeArray<Nsid>
+          }
+          return value as ['*' | Nsid]
+        },
+      },
+      action: {
+        multiple: true,
+        required: false,
+        validate: isRepoAction,
+        default: REPO_ACTIONS,
+        normalize: (value) => {
+          return value === REPO_ACTIONS
+            ? REPO_ACTIONS // No need to filter if the default was used
+            : (REPO_ACTIONS.filter(includedIn, value) as NeArray<RepoAction>)
+        },
+      },
+    },
+    'collection',
+  )
+
+  static fromString(scope: string): RepoPermission | null {
+    if (!isScopeStringFor(scope, 'repo')) return null
+    const syntax = ScopeStringSyntax.fromString(scope)
+    return RepoPermission.fromSyntax(syntax)
+  }
+
+  static fromSyntax(syntax: ScopeSyntax<'repo'>): RepoPermission | null {
+    const result = RepoPermission.parser.parse(syntax)
+    if (!result) return null
+
+    return new RepoPermission(result.collection, result.action)
+  }
+
+  static scopeNeededFor(options: RepoPermissionMatch): string {
+    return RepoPermission.parser.format({
+      collection: [options.collection as '*' | Nsid],
+      action: [options.action],
+    })
+  }
+}
+
+/**
+ * Special utility function to be used as predicate for array methods like
+ * `Array.prototype.includes`, etc. When used as predicate, it expects that
+ * the array method is called with a `thisArg` that is a readonly array of
+ * the same type as the `value` parameter.
+ */
+function includedIn<T>(this: readonly T[], value: T): boolean {
+  return this.includes(value)
+}