@atproto/oauth-scopes 0.5.2 → 0.5.3

package/src/scopes/include-scope.ts

@@ -1,208 +0,0 @@
-import { LexiconPermission, LexiconPermissionSet } 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 {
-  ScopeStringFor,
-  ScopeSyntax,
-  isScopeStringFor,
-  isScopeSyntaxFor,
-} from '../lib/syntax.js'
-import { RepoPermission } from './repo-permission.js'
-import {
-  AtprotoDidRefAbsolute,
-  RpcPermission,
-  isAtprotoDidRefAbsolute,
-} from './rpc-permission.js'
-
-export { type LexiconPermission, type LexiconPermissionSet, 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 | AtprotoDidRefAbsolute = undefined,
-  ) {}
-
-  toString() {
-    return IncludeScope.parser.format(this)
-  }
-
-  toPermissions(
-    permissionSet: LexiconPermissionSet,
-  ): Array<RepoPermission | RpcPermission> {
-    return Array.from(this.buildPermissions(permissionSet))
-  }
-
-  toScopes(
-    permissionSet: LexiconPermissionSet,
-  ): Array<ScopeStringFor<'repo' | 'rpc'>> {
-    return Array.from(this.buildPermissions(permissionSet), (p) => p.toString())
-  }
-
-  /**
-   * Converts an "include:" to the list of permissions it includes, based on the
-   * lexicon defined permission set.
-   */
-  *buildPermissions(
-    permissionSet: LexiconPermissionSet,
-  ): Generator<RepoPermission | RpcPermission, void, unknown> {
-    for (const lexPermission of permissionSet.permissions) {
-      const syntax = this.parseLexPermission(lexPermission)
-      if (!syntax) continue
-
-      const resourcePermission = toResourcePermission(syntax)
-      if (!resourcePermission) continue
-
-      if (this.isAllowedPermission(resourcePermission)) {
-        yield resourcePermission
-      }
-    }
-  }
-
-  protected parseLexPermission(
-    permission: LexiconPermission,
-  ): ScopeSyntax<'repo' | 'rpc'> | null {
-    // This function converts permissions listed in the permission set into
-    // their respective ScopeSyntax representations, handling special cases as
-    // needed.
-
-    if (isLexPermissionForResource(permission, 'repo')) {
-      return new LexPermissionSyntax(permission)
-    }
-
-    if (isLexPermissionForResource(permission, 'rpc')) {
-      // "rpc" permissions with a defined audience are not allowed in permission
-      // sets
-      if (permission.aud !== undefined && permission.aud !== '*') {
-        return null
-      }
-
-      // "rpc" permissions can "inherit" their audience from "aud" param defined
-      // in the "include:<nsid>?aud=<audience>" scope the permission set was
-      // loaded from.
-      if (
-        permission.inheritAud === true &&
-        permission.aud === undefined &&
-        this.aud !== undefined
-      ) {
-        const { inheritAud, ...rest } = permission
-        return new LexPermissionSyntax({ aud: this.aud, ...rest })
-      }
-
-      return new LexPermissionSyntax(permission)
-    }
-
-    return null
-  }
-
-  /**
-   * 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: RpcPermission | RepoPermission,
-  ): boolean {
-    if (permission instanceof RpcPermission) {
-      return permission.lxm.every(this.isParentAuthorityOf, this)
-    }
-
-    if (permission instanceof RepoPermission) {
-      return permission.collection.every(this.isParentAuthorityOf, this)
-    }
-
-    throw new TypeError(`Unexpected permission ${permission}`)
-  }
-
-  /**
-   * 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: isAtprotoDidRefAbsolute,
-      },
-    },
-    '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 toResourcePermission(
-  syntax: ScopeSyntax<'repo' | 'rpc'>,
-): RepoPermission | RpcPermission | null {
-  if (isScopeSyntaxFor(syntax, 'repo')) {
-    return RepoPermission.fromSyntax(syntax)
-  }
-  if (isScopeSyntaxFor(syntax, 'rpc')) {
-    return RpcPermission.fromSyntax(syntax)
-  }
-  return null
-}
-
-function isLexPermissionForResource<
-  P extends { resource: unknown },
-  T extends string,
->(permission: P, type: T): permission is P & { resource: T } {
-  return permission.resource === type
-}

package/src/scopes/repo-permission.test.ts

@@ -1,267 +0,0 @@
-import { RepoPermission } from './repo-permission.js'
-
-describe('RepoPermission', () => {
-  describe('static', () => {
-    describe('fromString', () => {
-      it('should parse positional scope', () => {
-        const scope = RepoPermission.fromString('repo:com.example.foo')
-        expect(scope).not.toBeNull()
-        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 = RepoPermission.fromString(
-          'repo:com.example.foo?action=create&action=update',
-        )
-        expect(scope).not.toBeNull()
-        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 = RepoPermission.fromString('repo:com.example.foo')
-        expect(scope).not.toBeNull()
-        expect(scope!.collection).toEqual(['com.example.foo'])
-        expect(scope!.action).toEqual(['create', 'update', 'delete'])
-      })
-
-      it('should allow wildcard collection with specific action', () => {
-        const scope = RepoPermission.fromString('repo:*?action=create')
-        expect(scope).not.toBeNull()
-        expect(scope!.collection).toEqual(['*'])
-        expect(scope!.action).toEqual(['create'])
-        expect(
-          scope!.matches({ action: 'create', collection: 'any.collection' }),
-        ).toBe(true)
-        expect(
-          scope!.matches({ action: 'update', collection: 'any.collection' }),
-        ).toBe(false)
-      })
-
-      it('should allow wildcard collection without actions', () => {
-        const scope = RepoPermission.fromString('repo:*')
-        expect(scope).not.toBeNull()
-        expect(scope!.collection).toEqual(['*'])
-        expect(scope!.action).toEqual(['create', 'update', 'delete'])
-        expect(
-          scope!.matches({ action: 'create', collection: 'any.collection' }),
-        ).toBe(true)
-        expect(
-          scope!.matches({ action: 'update', collection: 'any.collection' }),
-        ).toBe(true)
-        expect(
-          scope!.matches({ action: 'delete', collection: 'any.collection' }),
-        ).toBe(true)
-      })
-
-      it('should ignore scopes with invalid collection names', () => {
-        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 = RepoPermission.fromString(
-          'repo:com.example.foo?action=invalid',
-        )
-        expect(scope).toBeNull()
-      })
-
-      it('should return null for invalid repo scope', () => {
-        expect(RepoPermission.fromString('invalid')).toBeNull()
-        expect(RepoPermission.fromString('scope')).toBeNull()
-      })
-
-      for (const invalid of [
-        'repo:*?action=*',
-        'invalid',
-        'repo:invalid',
-        'repo:com.example.foo?action=invalid',
-        'repo?collection=invalid&action=invalid',
-      ]) {
-        it(`should return null for invalid rpc scope: ${invalid}`, () => {
-          expect(RepoPermission.fromString(invalid)).toBeNull()
-        })
-      }
-    })
-
-    describe('scopeNeededFor', () => {
-      it('should return correct scope string for specific collection and action', () => {
-        const scope = RepoPermission.scopeNeededFor({
-          collection: 'com.example.foo',
-          action: 'create',
-        })
-        expect(scope).toBe('repo:com.example.foo?action=create')
-      })
-
-      it('should return scope that accepts all collections with specific action', () => {
-        const scope = RepoPermission.scopeNeededFor({
-          collection: '*',
-          action: 'create',
-        })
-        expect(scope).toBe('repo:*?action=create')
-      })
-
-      it('ignores invalid options', () => {
-        // @NOTE the scopeNeededFor assumes valid input, so it does not validate
-        // collection or action.
-
-        expect(
-          RepoPermission.scopeNeededFor({
-            collection: 'invalid',
-            action: 'create',
-          }),
-        ).toBe('repo:invalid?action=create')
-      })
-    })
-  })
-
-  describe('instance', () => {
-    describe('matches', () => {
-      it('should match create action', () => {
-        const scope = RepoPermission.fromString(
-          'repo:com.example.foo?action=create',
-        )
-        expect(scope).not.toBeNull()
-        expect(
-          scope!.matches({ action: 'create', collection: 'com.example.foo' }),
-        ).toBe(true)
-      })
-
-      it('should not match unspecified action', () => {
-        const scope = RepoPermission.fromString(
-          'repo:com.example.foo?action=create',
-        )
-        expect(scope).not.toBeNull()
-        expect(
-          scope!.matches({ action: 'update', collection: 'com.example.foo' }),
-        ).toBe(false)
-      })
-
-      it('should match wildcard collection', () => {
-        const scope = RepoPermission.fromString('repo:*?action=create')
-        expect(scope).not.toBeNull()
-        expect(
-          scope!.matches({ action: 'create', collection: 'com.example.bar' }),
-        ).toBe(true)
-      })
-
-      it('should not match different action with wildcard collection', () => {
-        const scope = RepoPermission.fromString('repo:*?action=create')
-        expect(scope).not.toBeNull()
-        expect(
-          scope!.matches({ action: 'delete', collection: 'com.example.bar' }),
-        ).toBe(false)
-      })
-
-      it('should match multiple actions', () => {
-        const scope = RepoPermission.fromString(
-          'repo:com.example.foo?action=create&action=update',
-        )
-        expect(scope).not.toBeNull()
-        expect(
-          scope!.matches({ action: 'create', collection: 'com.example.foo' }),
-        ).toBe(true)
-        expect(
-          scope!.matches({ action: 'update', collection: 'com.example.foo' }),
-        ).toBe(true)
-        expect(
-          scope!.matches({ action: 'delete', collection: 'com.example.foo' }),
-        ).toBe(false)
-      })
-
-      it('should default to "create", "update", and "delete" actions', () => {
-        const scope = RepoPermission.fromString('repo:com.example.foo')
-        expect(scope).not.toBeNull()
-        expect(
-          scope!.matches({ action: 'create', collection: 'com.example.foo' }),
-        ).toBe(true)
-        expect(
-          scope!.matches({ action: 'update', collection: 'com.example.foo' }),
-        ).toBe(true)
-        expect(
-          scope!.matches({ action: 'delete', collection: 'com.example.foo' }),
-        ).toBe(true)
-      })
-    })
-
-    describe('toString', () => {
-      it('should format repo scope correctly', () => {
-        const scope = new RepoPermission(
-          ['com.example.foo'],
-          ['create', 'update'],
-        )
-        expect(scope).not.toBeNull()
-        expect(scope!.toString()).toBe(
-          'repo:com.example.foo?action=create&action=update',
-        )
-      })
-    })
-  })
-
-  describe('consistency', () => {
-    const testCases: { input: string; expected: string }[] = [
-      { input: 'repo:com.example.foo', expected: 'repo:com.example.foo' },
-      {
-        input: 'repo:com.example.foo?action=create',
-        expected: 'repo:com.example.foo?action=create',
-      },
-      {
-        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: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' },
-      {
-        input: 'repo?collection=*&action=update',
-        expected: 'repo:*?action=update',
-      },
-      {
-        input: 'repo?collection=*&collection=com.example.foo&action=update',
-        expected: 'repo:*?action=update',
-      },
-      {
-        input: 'repo?collection=*',
-        expected: 'repo:*',
-      },
-      {
-        input: 'repo?collection=*&action=create&action=update&action=delete',
-        expected: 'repo:*',
-      },
-      {
-        input: 'repo?collection=*&collection=com.example.foo',
-        expected: 'repo:*',
-      },
-      {
-        input: 'repo?action=create&collection=com.example.foo',
-        expected: 'repo:com.example.foo?action=create',
-      },
-      {
-        input:
-          'repo?collection=com.example.foo&action=create&action=update&action=delete',
-        expected: 'repo:com.example.foo',
-      },
-      {
-        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(RepoPermission.fromString(input)?.toString()).toBe(expected)
-      })
-    }
-  })
-})

package/src/scopes/repo-permission.ts

@@ -1,111 +0,0 @@
-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)
-}