@atproto/oauth-scopes 0.0.1

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

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

package/src/resources/repo-scope.ts

@@ -0,0 +1,101 @@
+import { NSID, isNSID } from '../lib/nsid.js'
+import { Parser, knownValuesValidator } from '../parser.js'
+import { NeRoArray, ResourceSyntax, isScopeForResource } from '../syntax.js'
+
+const REPO_ACTIONS = Object.freeze(['create', 'update', 'delete'] as const)
+export type RepoAction = (typeof REPO_ACTIONS)[number]
+export const isRepoAction = knownValuesValidator(REPO_ACTIONS)
+
+export const repoParser = new Parser(
+  'repo',
+  {
+    collection: {
+      multiple: true,
+      required: true,
+      validate: (value) => value === '*' || isNSID(value),
+      normalize: (value) => {
+        if (value.length > 1 && value.includes('*')) return ['*'] as const
+        return value
+      },
+    },
+    action: {
+      multiple: true,
+      required: false,
+      validate: isRepoAction,
+      default: REPO_ACTIONS,
+    },
+  },
+  'collection',
+)
+
+export type RepoScopeMatch = {
+  collection: string
+  action: RepoAction
+}
+
+export class RepoScope {
+  constructor(
+    public readonly collection: NeRoArray<'*' | NSID>,
+    public readonly action: NeRoArray<RepoAction>,
+  ) {}
+
+  get allowsAnyCollection() {
+    return this.collection.includes('*')
+  }
+
+  matches({ action, collection }: RepoScopeMatch): boolean {
+    return (
+      this.action.includes(action) &&
+      (this.allowsAnyCollection ||
+        (this.collection as readonly string[]).includes(collection))
+    )
+  }
+
+  toString(): string {
+    // Normalize (compress, de-dupe, sort)
+    return repoParser.format({
+      collection: this.allowsAnyCollection
+        ? ['*']
+        : this.collection.length > 1
+          ? ([...new Set(this.collection)].sort() as [NSID, ...NSID[]])
+          : this.collection,
+      action:
+        this.action === REPO_ACTIONS
+          ? REPO_ACTIONS // No need to filter if the default was used
+          : (REPO_ACTIONS.filter(includedIn, this.action) as [
+              RepoAction,
+              ...RepoAction[],
+            ]),
+    })
+  }
+
+  static fromString(scope: string): RepoScope | null {
+    if (!isScopeForResource(scope, 'repo')) return null
+    const syntax = ResourceSyntax.fromString(scope)
+    return this.fromSyntax(syntax)
+  }
+
+  static fromSyntax(syntax: ResourceSyntax): RepoScope | null {
+    const result = repoParser.parse(syntax)
+    if (!result) return null
+
+    return new RepoScope(result.collection, result.action)
+  }
+
+  static scopeNeededFor(options: RepoScopeMatch): string {
+    return repoParser.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)
+}

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

@@ -0,0 +1,280 @@
+import { RpcScope } from './rpc-scope.js'
+
+describe('RpcScope', () => {
+  describe('static', () => {
+    describe('fromString', () => {
+      it('should parse positional scope', () => {
+        const scope = RpcScope.fromString(
+          'rpc:com.example.service?aud=did:example:123',
+        )
+        expect(scope).not.toBeNull()
+        expect(scope!.aud).toBe('did:example:123')
+        expect(scope!.lxm).toEqual(['com.example.service'])
+      })
+
+      it('should parse strings correctly', () => {
+        expect(
+          RpcScope.fromString('rpc?lxm=com.example.method1&aud=*'),
+        ).toEqual({
+          aud: '*',
+          lxm: ['com.example.method1'],
+        })
+        expect(RpcScope.fromString('rpc:com.example.method1?aud=*')).toEqual({
+          aud: '*',
+          lxm: ['com.example.method1'],
+        })
+      })
+
+      it('should render strings correctly', () => {
+        expect(
+          new RpcScope('did:example:123', ['com.example.service']).toString(),
+        ).toBe('rpc:com.example.service?aud=did:example:123')
+        expect(new RpcScope('*', ['com.example.method1']).toString()).toBe(
+          'rpc:com.example.method1?aud=*',
+        )
+        expect(
+          new RpcScope('did:example:123', [
+            'com.example.method1',
+            'com.example.method2',
+          ]).toString(),
+        ).toBe(
+          'rpc?lxm=com.example.method1&lxm=com.example.method2&aud=did:example:123',
+        )
+      })
+
+      it('should reject scopes without lxm', () => {
+        expect(RpcScope.fromString('rpc?aud=did:example:123')).toBeNull()
+        expect(RpcScope.fromString('rpc:?aud=did:example:123')).toBeNull()
+      })
+
+      it('should reject scopes without aud', () => {
+        expect(RpcScope.fromString('rpc?lxm=com.example.method1')).toBeNull()
+        expect(RpcScope.fromString('rpc:com.example.method1')).toBeNull()
+      })
+
+      it('should reject scopes with lxm in both positional and query form', () => {
+        expect(
+          RpcScope.fromString(
+            'rpc:com.example.method1?aud=did:example:123&lxm=com.example.method2',
+          ),
+        ).toBeNull()
+      })
+
+      it('should parse valid rpc scope with multiple lxm', () => {
+        const scope = RpcScope.fromString(
+          'rpc?aud=*&lxm=com.example.method1&lxm=com.example.method2',
+        )
+        expect(scope).not.toBeNull()
+        expect(scope!.aud).toBe('*')
+        expect(scope!.lxm).toEqual([
+          'com.example.method1',
+          'com.example.method2',
+        ])
+      })
+
+      it('should reject rpc scope without lxm', () => {
+        const scope = RpcScope.fromString('rpc?aud=did:example:123')
+        expect(scope).toBeNull()
+      })
+
+      it('should reject rpc scope without aud', () => {
+        const scope = RpcScope.fromString('rpc?lxm=com.example.method1')
+        expect(scope).toBeNull()
+      })
+
+      it('should reject any aud/any lxm', () => {
+        expect(RpcScope.fromString('rpc?aud=*&lxm=*')).toBeNull()
+        expect(RpcScope.fromString('rpc:*?aud=*')).toBeNull()
+      })
+
+      it('should reject missing aud', () => {
+        expect(RpcScope.fromString('rpc:com.example.service')).toBeNull()
+      })
+
+      it('should reject invalid aud', () => {
+        expect(
+          RpcScope.fromString('rpc:com.example.service?aud=invalid'),
+        ).toBeNull()
+      })
+
+      it('should reject invalid lxm', () => {
+        expect(RpcScope.fromString('rpc:invalid')).toBeNull()
+        expect(RpcScope.fromString('rpc?lxm=invalid')).toBeNull()
+      })
+
+      for (const invalid of [
+        'rpc:*',
+        'invalid',
+        'rpc:invalid',
+        'rpc:invalid?aud=did:foo:bar',
+        'rpc:foo.bar?aud=did:foo:bar&lxm=bar.baz',
+        'rpc:foo.bar?aud=invalid',
+        'rpc:invalid?aud=did:example:123',
+        'rpc:com.example.service?aud=invalid',
+        'notrpc:com.example.service?aud=did:example:123',
+        'rpc?lxm=invalid&aud=invalid',
+      ]) {
+        it(`should return null for invalid rpc scope: ${invalid}`, () => {
+          expect(RpcScope.fromString(invalid)).toBeNull()
+        })
+      }
+    })
+
+    describe('scopeNeededFor', () => {
+      it('should return correct scope string for specific lxm and aud', () => {
+        const scope = RpcScope.scopeNeededFor({
+          lxm: 'com.example.service',
+          aud: 'did:example:123',
+        })
+        expect(scope).toBe('rpc:com.example.service?aud=did:example:123')
+      })
+
+      it('should return scope that accepts all aud with specific lxm', () => {
+        const scope = RpcScope.scopeNeededFor({
+          lxm: 'com.example.method1',
+          aud: '*',
+        })
+        expect(scope).toBe('rpc:com.example.method1?aud=*')
+      })
+    })
+  })
+
+  describe('instance', () => {
+    describe('matches', () => {
+      it('should match exact lxm and aud', () => {
+        const scope = RpcScope.fromString(
+          'rpc:com.example.service?aud=did:example:123',
+        )
+        expect(scope).not.toBeNull()
+        expect(
+          scope!.matches({
+            lxm: 'com.example.service',
+            aud: 'did:example:123',
+          }),
+        ).toBe(true)
+      })
+
+      it('should not match different lxm', () => {
+        const scope = RpcScope.fromString(
+          'rpc:com.example.service?aud=did:example:123',
+        )
+        expect(scope).not.toBeNull()
+        expect(
+          scope!.matches({
+            lxm: 'com.example.OtherService',
+            aud: 'did:example:123',
+          }),
+        ).toBe(false)
+      })
+
+      it('should not match different aud', () => {
+        const scope = RpcScope.fromString(
+          'rpc:com.example.service?aud=did:example:123',
+        )
+        expect(scope).not.toBeNull()
+        expect(
+          scope!.matches({
+            lxm: 'com.example.service',
+            aud: 'did:example:456',
+          }),
+        ).toBe(false)
+      })
+
+      it('should match wildcard aud', () => {
+        const scope = RpcScope.fromString('rpc:com.example.method1?aud=*')
+        expect(scope).not.toBeNull()
+        expect(
+          scope!.matches({
+            lxm: 'com.example.method1',
+            aud: 'did:example:123',
+          }),
+        ).toBe(true)
+      })
+
+      it('should match wildcard lxm', () => {
+        const scope = RpcScope.fromString('rpc:*?aud=did:example:123')
+        expect(scope).not.toBeNull()
+        expect(
+          scope!.matches({
+            lxm: 'com.example.method1',
+            aud: 'did:example:123',
+          }),
+        ).toBe(true)
+      })
+
+      it('should not match different lxm with wildcard aud', () => {
+        const scope = RpcScope.fromString('rpc:*?aud=did:example:123')
+        expect(scope).not.toBeNull()
+        expect(
+          scope!.matches({
+            lxm: 'com.example.anyMethod',
+            aud: 'did:example:123',
+          }),
+        ).toBe(true)
+      })
+    })
+
+    describe('toString', () => {
+      it('should format scope with lxm and aud', () => {
+        const scope = new RpcScope('did:example:123', ['com.example.service'])
+        expect(scope.toString()).toBe(
+          'rpc:com.example.service?aud=did:example:123',
+        )
+      })
+
+      it('should format scope with wildcard aud', () => {
+        const scope = new RpcScope('*', ['com.example.method1'])
+        expect(scope.toString()).toBe('rpc:com.example.method1?aud=*')
+      })
+
+      it('should format scope with wildcard lxm', () => {
+        const scope = new RpcScope('did:example:123', ['*'])
+        expect(scope.toString()).toBe('rpc:*?aud=did:example:123')
+      })
+
+      it('simplifies lxm if one of them is "*"', () => {
+        const scope = new RpcScope('did:example:123', [
+          '*',
+          'com.example.method1',
+        ])
+        expect(scope.toString()).toBe('rpc:*?aud=did:example:123')
+      })
+    })
+  })
+
+  describe('consistency', () => {
+    const testCases: { input: string; expected: string }[] = [
+      {
+        input: 'rpc:com.example.service?aud=did:example:123',
+        expected: 'rpc:com.example.service?aud=did:example:123',
+      },
+      {
+        input: 'rpc?lxm=com.example.method1&lxm=com.example.method2&aud=*',
+        expected: 'rpc?lxm=com.example.method1&lxm=com.example.method2&aud=*',
+      },
+      {
+        input:
+          'rpc?lxm=com.example.method1&lxm=com.example.method2&lxm=*&aud=did:example:123',
+        expected: 'rpc:*?aud=did:example:123',
+      },
+      {
+        input: 'rpc?aud=did:example:123&lxm=com.example.service',
+        expected: 'rpc:com.example.service?aud=did:example:123',
+      },
+      {
+        input: 'rpc?lxm=com.example.method1&aud=did:example:123',
+        expected: 'rpc:com.example.method1?aud=did:example:123',
+      },
+      {
+        input: 'rpc:com.example.method1?&aud=*',
+        expected: 'rpc:com.example.method1?aud=*',
+      },
+    ]
+
+    for (const { input, expected } of testCases) {
+      it(`should properly re-format ${input}`, () => {
+        expect(RpcScope.fromString(input)?.toString()).toBe(expected)
+      })
+    }
+  })
+})