@atproto/oauth-scopes 0.0.1

package/src/resources/rpc-scope.ts

@@ -0,0 +1,77 @@
+import { DIDLike, isDIDLike } from '../lib/did.js'
+import { NSID, isNSID } from '../lib/nsid.js'
+import { Parser } from '../parser.js'
+import { NeRoArray, ResourceSyntax, isScopeForResource } from '../syntax.js'
+
+const validateLxmParam = (value: string) => value === '*' || isNSID(value)
+const validateAudParam = (value: string) => value === '*' || isDIDLike(value)
+
+export const rpcParser = new Parser(
+  'rpc',
+  {
+    lxm: {
+      multiple: true,
+      required: true,
+      validate: validateLxmParam,
+    },
+    aud: {
+      multiple: false,
+      required: true,
+      validate: validateAudParam,
+    },
+  },
+  'lxm',
+)
+
+export type RpcScopeMatch = {
+  lxm: string
+  aud: string
+}
+
+export class RpcScope {
+  constructor(
+    public readonly aud: '*' | DIDLike,
+    public readonly lxm: NeRoArray<'*' | NSID>,
+  ) {}
+
+  matches(options: RpcScopeMatch): boolean {
+    const { aud, lxm } = this
+    return (
+      (aud === '*' || aud === options.aud) &&
+      (lxm.includes('*') || (lxm as readonly string[]).includes(options.lxm))
+    )
+  }
+
+  toString(): string {
+    const { lxm, aud } = this
+    return rpcParser.format({
+      aud,
+      lxm: lxm.includes('*')
+        ? ['*']
+        : ([...new Set(lxm)].sort() as [NSID, ...NSID[]]),
+    })
+  }
+
+  static fromString(scope: string): RpcScope | null {
+    if (!isScopeForResource(scope, 'rpc')) return null
+    const syntax = ResourceSyntax.fromString(scope)
+    return this.fromSyntax(syntax)
+  }
+
+  static fromSyntax(syntax: ResourceSyntax): RpcScope | null {
+    const result = rpcParser.parse(syntax)
+    if (!result) return null
+
+    // rpc:*?aud=* is forbidden
+    if (result.aud === '*' && result.lxm.includes('*')) return null
+
+    return new RpcScope(result.aud, result.lxm)
+  }
+
+  static scopeNeededFor(options: RpcScopeMatch): string {
+    return rpcParser.format({
+      aud: options.aud as DIDLike,
+      lxm: [options.lxm as NSID],
+    })
+  }
+}

package/src/scope-missing-error.ts

@@ -0,0 +1,15 @@
+export class ScopeMissingError extends Error {
+  name = 'ScopeMissingError'
+
+  // compatibility layer with http-errors package. The goal if to make
+  // isHttpError(new ScopeMissingError) return true.
+  status = 403
+  expose = true
+  get statusCode() {
+    return this.status
+  }
+
+  constructor(public readonly scope: string) {
+    super(`Missing required scope "${scope}"`)
+  }
+}

package/src/scopes-set.test.ts

@@ -0,0 +1,47 @@
+import { ScopesSet } from './scopes-set.js'
+
+describe('ScopesSet', () => {
+  it('should initialize with an empty set', () => {
+    const set = new ScopesSet()
+    expect(set.size).toBe(0)
+  })
+
+  it('should add scopes correctly', () => {
+    const set = new ScopesSet()
+    set.add('repo:read')
+    expect(set.size).toBe(1)
+    expect(set.has('repo:read')).toBe(true)
+    expect(set.has('repo:write')).toBe(false)
+  })
+
+  it('should remove scopes correctly', () => {
+    const set = new ScopesSet(['repo:read'])
+    set.delete('repo:read')
+    expect(set.size).toBe(0)
+    expect(set.has('repo:read')).toBe(false)
+  })
+
+  it('should match included scopes', () => {
+    const set = new ScopesSet(['repo:foo.bar'])
+    expect(
+      set.matches('repo', { action: 'create', collection: 'foo.bar' }),
+    ).toBe(true)
+    expect(
+      set.matches('repo', { action: 'create', collection: 'baz.qux' }),
+    ).toBe(false)
+  })
+
+  it('should not match missing scopes', () => {
+    const set = new ScopesSet(['repo:foo.bar?action=create'])
+    expect(
+      set.matches('repo', { action: 'delete', collection: 'foo.bar' }),
+    ).toBe(false)
+  })
+
+  it('should not match invalid scopes', () => {
+    const set = new ScopesSet(['repo:not-a-valid-nsid'])
+    expect(
+      set.matches('repo', { action: 'create', collection: 'not-a-valid-nsid' }),
+    ).toBe(false)
+  })
+})

package/src/scopes-set.ts

@@ -0,0 +1,60 @@
+import { ScopeMissingError } from './scope-missing-error.js'
+import {
+  ScopeMatchingOptionsByResource,
+  scopeMatches,
+  scopeNeededFor,
+} from './utilities.js'
+
+export { ScopeMissingError }
+
+/**
+ * Utility class to manage a set of scopes and check if they match specific
+ * options for a given resource.
+ */
+export class ScopesSet extends Set<string> {
+  /**
+   * Check if the container has a scope that matches the given options for a
+   * specific resource.
+   */
+  public matches<R extends keyof ScopeMatchingOptionsByResource>(
+    resource: R,
+    options: ScopeMatchingOptionsByResource[R],
+  ): boolean {
+    for (const scope of this) {
+      if (scopeMatches(scope, resource, options)) return true
+    }
+    return false
+  }
+
+  public assert<R extends keyof ScopeMatchingOptionsByResource>(
+    resource: R,
+    options: ScopeMatchingOptionsByResource[R],
+  ) {
+    if (!this.matches(resource, options)) {
+      const scope = scopeNeededFor(resource, options)
+      throw new ScopeMissingError(scope)
+    }
+  }
+
+  public some(fn: (scope: string) => boolean): boolean {
+    for (const scope of this) if (fn(scope)) return true
+    return false
+  }
+
+  public every(fn: (scope: string) => boolean): boolean {
+    for (const scope of this) if (!fn(scope)) return false
+    return true
+  }
+
+  public *filter(fn: (scope: string) => boolean) {
+    for (const scope of this) if (fn(scope)) yield scope
+  }
+
+  public *map<O>(fn: (scope: string) => O) {
+    for (const scope of this) yield fn(scope)
+  }
+
+  static fromString(string?: string): ScopesSet {
+    return new ScopesSet(string?.split(' '))
+  }
+}

package/src/syntax.test.ts

@@ -0,0 +1,203 @@
+import { ResourceSyntax, isScopeForResource } from './syntax.js'
+
+describe('isScopeForResource', () => {
+  describe('exact match', () => {
+    it('should return true for exact match', () => {
+      expect(isScopeForResource('resource', 'resource')).toBe(true)
+    })
+
+    it('should return false for different resource', () => {
+      expect(isScopeForResource('resource', 'differentResource')).toBe(false)
+    })
+  })
+
+  describe('with positional parameter', () => {
+    it('should return true for exact match with positional parameter', () => {
+      expect(isScopeForResource('resource:positional', 'resource')).toBe(true)
+    })
+
+    it('should return false for different resource with positional parameter', () => {
+      expect(
+        isScopeForResource('differentResource:positional', 'resource'),
+      ).toBe(false)
+    })
+  })
+
+  describe('with named parameters', () => {
+    it('should return true for exact match with named parameters', () => {
+      expect(isScopeForResource('resource?param=value', 'resource')).toBe(true)
+    })
+
+    it('should return false for different resource with named parameters', () => {
+      expect(
+        isScopeForResource('differentResource?param=value', 'resource'),
+      ).toBe(false)
+    })
+  })
+})
+
+for (const { scope, normalized = scope, content } of [
+  {
+    scope: 'my-res',
+    content: { resource: 'my-res' },
+  },
+  {
+    scope: 'my-res:my-pos',
+    content: { resource: 'my-res', positional: 'my-pos' },
+  },
+  {
+    scope: 'my-res:',
+    content: { resource: 'my-res', positional: '' },
+  },
+  {
+    scope: 'my-res:foo?x=value&y=value-y',
+    content: {
+      resource: 'my-res',
+      positional: 'foo',
+      params: { x: ['value'], y: ['value-y'] },
+    },
+  },
+  {
+    scope: 'my-res?x=value&y=value-y',
+    content: { resource: 'my-res', params: { x: ['value'], y: ['value-y'] } },
+  },
+  {
+    scope: 'my-res?x=foo&x=bar&x=baz',
+    content: { resource: 'my-res', params: { x: ['foo', 'bar', 'baz'] } },
+  },
+  {
+    scope: 'rpc:foo.bar?aud=did:foo:bar?lxm=bar.baz',
+    normalized: 'rpc:foo.bar?aud=did:foo:bar%3Flxm%3Dbar.baz',
+    content: {
+      resource: 'rpc',
+      positional: 'foo.bar',
+      params: { aud: ['did:foo:bar?lxm=bar.baz'] },
+    },
+  },
+] as Array<{
+  scope: string
+  normalized?: string
+  content: {
+    resource: string
+    positional?: string
+    params?: Record<string, string[]>
+  }
+}>) {
+  describe(`Valid "${scope}"`, () => {
+    const syntax = ResourceSyntax.fromString(scope)
+
+    it('should match the expected syntax', () => {
+      expect(syntax).toEqual({
+        resource: content.resource,
+        positional: content.positional,
+        params: content.params
+          ? new URLSearchParams(
+              Object.entries(content.params).flatMap(([k, v]) =>
+                v.map((val) => [k, val]),
+              ),
+            )
+          : undefined,
+      })
+    })
+
+    it(`should stringify ${scope} correctly`, () => {
+      expect(syntax.toString()).toBe(normalized)
+    })
+
+    it(`should parse ${scope} correctly`, () => {
+      expect(syntax.toJSON()).toMatchObject(content)
+    })
+
+    it(`should match ${scope} resource`, () => {
+      expect(syntax.is(content.resource)).toBe(true)
+    })
+
+    it(`should return undefined for nonexistent single-value param`, () => {
+      expect(syntax.getSingle('nonexistent')).toBeUndefined()
+    })
+
+    it(`should return undefined for nonexistent multi-value param`, () => {
+      expect(syntax.getMulti('nonexistent')).toBeUndefined()
+    })
+
+    const { params } = content
+    if (params) {
+      it(`should allow detecting unknown params`, () => {
+        const allowedParams = Object.keys(params) as [string, ...string[]]
+        expect(syntax.containsParamsOtherThan(allowedParams)).toBe(false)
+
+        if (allowedParams.length > 1) {
+          const woFirst = allowedParams.slice(1) as [string, ...string[]]
+          expect(syntax.containsParamsOtherThan(woFirst)).toBe(true)
+
+          const woLast = allowedParams.slice(0, -1) as [string, ...string[]]
+          expect(syntax.containsParamsOtherThan(woLast)).toBe(true)
+        }
+      })
+
+      for (const [key, values] of Object.entries(params)) {
+        it(`should get an array when reading "${key}"`, () => {
+          expect(syntax.getMulti(key)).toEqual(values)
+        })
+
+        if (values.length === 1) {
+          it(`should allow retrieving single-value params`, () => {
+            expect(syntax.getSingle(key)).toEqual(values[0])
+          })
+        } else {
+          it(`should return null for multi-value params`, () => {
+            expect(syntax.getSingle(key)).toBeNull()
+            expect(syntax.getSingle(key, true)).toBeNull()
+          })
+        }
+      }
+    }
+
+    const { positional } = content
+    if (positional !== undefined) {
+      it(`should return positional parameter`, () => {
+        expect(syntax.positional).toBe(positional)
+      })
+
+      it(`should return positional parameter when reading as single-value`, () => {
+        expect(syntax.getSingle('nonexistent', true)).toBe(positional)
+      })
+
+      it(`should return positional parameter when reading as multi-value`, () => {
+        expect(syntax.getMulti('nonexistent', true)).toEqual([positional])
+      })
+    }
+  })
+}
+
+describe('invalid positional parameters', () => {
+  it('should return null for positional parameters used together with named parameters', () => {
+    const syntax = ResourceSyntax.fromString('my-res:pos?x=value')
+    expect(syntax.getSingle('x', true)).toBeNull()
+    expect(syntax.getMulti('x', true)).toBeNull()
+  })
+})
+
+describe('containsParamsOtherThan', () => {
+  it('should return true if there are additional params', () => {
+    const syntax = ResourceSyntax.fromString('my-res?x=value&y=value-y')
+    expect(syntax.containsParamsOtherThan(['x'])).toBe(true)
+  })
+})
+
+describe('url encoding', () => {
+  it('should handle URL encoding in positional parameters', () => {
+    const syntax = ResourceSyntax.fromString('my-res:my%20pos')
+    expect(syntax.positional).toBe('my pos')
+  })
+
+  it('should handle URL encoding in named parameters', () => {
+    const syntax = ResourceSyntax.fromString('my-res?x=my%20value')
+    expect(syntax.getSingle('x')).toBe('my value')
+  })
+
+  it(`should allow colon (:) in positional parameters`, () => {
+    const syntax = ResourceSyntax.fromString('my-res:my:pos')
+    expect(syntax.positional).toBe('my:pos')
+  })
+})