@atproto/oauth-scopes 0.0.1

package/src/lib/mime.ts

@@ -0,0 +1,70 @@
+// @TODO Refactor in shared location for use with other @atproto packages
+
+function isStringSlashString(value: string): value is `${string}/${string}` {
+  const slashIndex = value.indexOf('/')
+
+  if (slashIndex === -1) return false // Missing slash
+  if (slashIndex === 0) return false // No leading part before the slash
+  if (slashIndex === value.length - 1) return false // No trailing part after the slash
+  if (value.includes('/', slashIndex + 1)) return false // More than one slash
+  if (value.includes(' ')) return false // Spaces are not allowed
+
+  return true
+}
+
+export type Mime = `${string}/${string}`
+
+export function isMime(value: string): value is Mime {
+  return isStringSlashString(value) && !value.includes('*')
+}
+
+export type Accept = '*/*' | `${string}/*` | Mime
+
+export function isAccept(value: string): value is Accept {
+  if (value === '*/*') return true // Fast path for the most common case
+  if (!isStringSlashString(value)) return false
+  return !value.includes('*') || value.endsWith('/*')
+}
+
+/**
+ * @note "unsafe" in that it does not check if either {@link accept} or
+ * {@link mime} are actually valid values (and could, therefore, lead to false
+ * positives if forged values are used).
+ */
+function matchesAcceptUnsafe(accept: Accept, mime: Mime): boolean {
+  if (accept === '*/*') {
+    return true
+  }
+  if (accept.endsWith('/*')) {
+    return mime.startsWith(accept.slice(0, -1))
+  }
+  return accept === mime
+}
+
+export function matchesAccept(accept: Accept, mime: string): boolean {
+  return isMime(mime) && matchesAcceptUnsafe(accept, mime)
+}
+
+/**
+ * @note "unsafe" in that it does not check if either {@link accept} or
+ * {@link mime} are actually valid values (and could, therefore, lead to false
+ * positives if forged values are used).
+ */
+function matchesAnyAcceptUnsafe(
+  acceptable: Iterable<Accept>,
+  mime: Mime,
+): boolean {
+  for (const accept of acceptable) {
+    if (matchesAcceptUnsafe(accept, mime)) {
+      return true
+    }
+  }
+  return false
+}
+
+export function matchesAnyAccept(
+  acceptable: Iterable<Accept>,
+  mime: string,
+): boolean {
+  return isMime(mime) && matchesAnyAcceptUnsafe(acceptable, mime)
+}

package/src/lib/nsid.ts

@@ -0,0 +1,6 @@
+export type NSID = `${string}.${string}`
+export const isNSID = (value: string): value is NSID =>
+  value.includes('.') &&
+  !value.includes(' ') &&
+  !value.startsWith('.') &&
+  !value.endsWith('.')

package/src/lib/util.ts

@@ -0,0 +1,19 @@
+export function minIdx(a: number, b: number): number {
+  if (a === -1) return b
+  if (b === -1) return a
+  return Math.min(a, b)
+}
+
+export function toRecord(
+  iterable: Iterable<[key: string, value: string]>,
+): Record<string, [string, ...string[]]> {
+  const record: Record<string, [string, ...string[]]> = Object.create(null)
+  for (const [key, value] of iterable) {
+    if (Object.hasOwn(record, key)) {
+      record[key]!.push(value)
+    } else {
+      record[key] = [value]
+    }
+  }
+  return record
+}

package/src/parser.ts

@@ -0,0 +1,150 @@
+import {
+  NeRoArray,
+  ResourceSyntax,
+  ScopeForResource,
+  formatScope,
+} from './syntax.js'
+
+type InferStringPredicate<T extends undefined | ((value: string) => boolean)> =
+  T extends ((value: string) => value is infer U extends string) ? U : string
+
+type ParamsSchema = Record<
+  string,
+  | {
+      multiple: false
+      required: boolean
+      default?: string
+      normalize?: (value: string) => string
+      validate?: (value: string) => boolean
+    }
+  | {
+      multiple: true
+      required: boolean
+      default?: NeRoArray<string>
+      normalize?: (value: NeRoArray<string>) => NeRoArray<string>
+      validate?: (value: string) => boolean
+    }
+>
+
+type ParsedParams<S extends ParamsSchema> = {
+  [K in keyof S]:
+    | (S[K]['required'] extends true
+        ? never
+        : 'default' extends keyof S[K]
+          ? S[K]['default']
+          : undefined)
+    | (S[K]['multiple'] extends true
+        ? NeRoArray<InferStringPredicate<S[K]['validate']>>
+        : InferStringPredicate<S[K]['validate']>)
+} & NonNullable<unknown>
+
+export class Parser<R extends string, S extends ParamsSchema> {
+  readonly schemaKeys: ReadonlyArray<keyof S & string>
+
+  constructor(
+    readonly resource: R,
+    readonly schema: S,
+    readonly positionalName?: keyof S & string,
+  ) {
+    this.schemaKeys = Object.keys(schema)
+  }
+
+  format(values: ParsedParams<S>): ScopeForResource<R> {
+    // Build params
+    const params: [
+      name: string,
+      value: undefined | string | NeRoArray<string>,
+    ][] = []
+
+    for (const key of this.schemaKeys) {
+      const value = values[key]
+      // Ignore undefined values
+      if (value === undefined) continue
+
+      const schema = this.schema[key]
+
+      // @TODO: when the value is an array, we could remove duplicates
+
+      // Normalize the value if a normalization function is provided
+      const normalized = schema.normalize
+        ? schema.normalize(value as any)
+        : value
+
+      // Ignore values that are equal to the default value
+      if (!schema.required) {
+        if (schema.default === normalized) continue
+        if (
+          schema.multiple &&
+          schema.default &&
+          arrayParamEquals(schema.default, normalized as NeRoArray<string>)
+        ) {
+          continue
+        }
+      }
+
+      params.push([key, normalized])
+    }
+
+    return formatScope<R>(this.resource, params, this.positionalName)
+  }
+
+  parse(syntax: ResourceSyntax) {
+    if (!syntax.is(this.resource)) return null
+    if (syntax.containsParamsOtherThan(this.schemaKeys)) return null
+
+    const result: Record<string, undefined | string | NeRoArray<string>> =
+      Object.create(null)
+
+    for (const key of this.schemaKeys) {
+      const definition = this.schema[key]
+
+      const value = definition.multiple
+        ? syntax.getMulti(key, key === this.positionalName)
+        : syntax.getSingle(key, key === this.positionalName)
+
+      if (value === null) return null // Value is not valid
+      if (value === undefined && definition.required) return null
+
+      if (value !== undefined && definition.validate) {
+        if (definition.multiple) {
+          if (!(value as NeRoArray<string>).every(definition.validate)) {
+            return null
+          }
+        } else {
+          if (!definition.validate(value as string)) {
+            return null
+          }
+        }
+      }
+
+      result[key] = value ?? definition.default
+    }
+
+    return result as ParsedParams<S>
+  }
+
+  parseString(scope: string): ParsedParams<S> | null {
+    const syntax = ResourceSyntax.fromString(scope)
+    return this.parse(syntax)
+  }
+}
+
+/**
+ * Two param arrays are considered equal if they contain the same values,
+ * regardless of the order and duplicates.
+ * @param a - The first array to compare.
+ * @param b - The second array to compare.
+ */
+function arrayParamEquals(
+  a: readonly unknown[],
+  b: readonly unknown[],
+): boolean {
+  for (const item of a) if (!b.includes(item)) return false
+  for (const item of b) if (!a.includes(item)) return false
+  return true
+}
+
+export function knownValuesValidator<T extends string>(values: Iterable<T>) {
+  const set = new Set<string>(values)
+  return (value: string): value is T => set.has(value)
+}

package/src/permission-set-transition.test.ts

@@ -0,0 +1,109 @@
+import { PermissionSetTransition } from './permission-set-transition.js'
+
+describe('PermissionSetTransition', () => {
+  describe('allowsAccount', () => {
+    it('should allow account:email with transition:email', () => {
+      const set = new PermissionSetTransition('transition:email account:repo')
+      expect(set.allowsAccount({ attr: 'email', action: 'read' })).toBe(true)
+      expect(set.allowsAccount({ attr: 'email', action: 'manage' })).toBe(true)
+
+      expect(set.allowsAccount({ attr: 'repo', action: 'read' })).toBe(true)
+      expect(set.allowsAccount({ attr: 'repo', action: 'manage' })).toBe(false)
+
+      expect(set.allowsAccount({ attr: 'status', action: 'read' })).toBe(false)
+      expect(set.allowsAccount({ attr: 'status', action: 'manage' })).toBe(
+        false,
+      )
+    })
+  })
+
+  describe('allowsBlob', () => {
+    it('should allow blob with transition:generic', () => {
+      const set = new PermissionSetTransition('transition:generic')
+      expect(set.allowsBlob({ mime: 'foo/bar' })).toBe(true)
+    })
+  })
+
+  describe('allowsRepo', () => {
+    it('should allow repo with transition:generic', () => {
+      const set = new PermissionSetTransition('transition:generic')
+      expect(
+        set.allowsRepo({ collection: 'app.bsky.feed.post', action: 'create' }),
+      ).toBe(true)
+      expect(
+        set.allowsRepo({ collection: 'app.bsky.feed.post', action: 'delete' }),
+      ).toBe(true)
+      expect(
+        set.allowsRepo({ collection: 'com.example.foo', action: 'create' }),
+      ).toBe(true)
+      expect(
+        set.allowsRepo({ collection: 'com.example.foo', action: 'update' }),
+      ).toBe(true)
+    })
+  })
+
+  describe('allowsRpc', () => {
+    it('should allow rpc with transition:generic', () => {
+      const set = new PermissionSetTransition('transition:generic')
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.post' }),
+      ).toBe(true)
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.foo' }),
+      ).toBe(true)
+      expect(set.allowsRpc({ aud: 'did:example:123', lxm: '*' })).toBe(true)
+    })
+
+    it('should allow chat.bsky.* methods with "transition:chat.bsky"', () => {
+      const set = new PermissionSetTransition('transition:chat.bsky')
+      expect(
+        set.allowsRpc({
+          aud: 'did:example:123',
+          lxm: 'chat.bsky.message.send',
+        }),
+      ).toBe(true)
+      expect(
+        set.allowsRpc({
+          aud: 'did:example:123',
+          lxm: 'chat.bsky.conversation.get',
+        }),
+      ).toBe(true)
+
+      // Control
+
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.post' }),
+      ).toBe(false)
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.foo' }),
+      ).toBe(false)
+      expect(set.allowsRpc({ aud: 'did:example:123', lxm: '*' })).toBe(false)
+    })
+
+    it('should reject chat methods with "transition:generic"', () => {
+      const set = new PermissionSetTransition('transition:generic')
+
+      expect(
+        set.allowsRpc({
+          aud: 'did:example:123',
+          lxm: 'chat.bsky.message.send',
+        }),
+      ).toBe(false)
+      expect(
+        set.allowsRpc({
+          aud: 'did:example:123',
+          lxm: 'chat.bsky.conversation.get',
+        }),
+      ).toBe(false)
+
+      // Control
+
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.post' }),
+      ).toBe(true)
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.foo' }),
+      ).toBe(true)
+    })
+  })
+})

package/src/permission-set-transition.ts

@@ -0,0 +1,67 @@
+import {
+  AccountScopeMatch,
+  BlobScopeMatch,
+  PermissionSet,
+  RepoScopeMatch,
+  RpcScopeMatch,
+} from './permission-set.js'
+
+/**
+ * Overrides the default permission set to allow transitional scopes to be used
+ * in place of the generic scopes.
+ */
+export class PermissionSetTransition extends PermissionSet {
+  get hasTransitionGeneric(): boolean {
+    return this.scopes.has('transition:generic')
+  }
+
+  get hasTransitionEmail(): boolean {
+    return this.scopes.has('transition:email')
+  }
+
+  get hasTransitionChatBsky(): boolean {
+    return this.scopes.has('transition:chat.bsky')
+  }
+
+  override allowsAccount(options: AccountScopeMatch): boolean {
+    if (options.attr === 'email' && this.hasTransitionEmail) {
+      return true
+    }
+
+    return super.allowsAccount(options)
+  }
+
+  override allowsBlob(options: BlobScopeMatch): boolean {
+    if (this.hasTransitionGeneric) {
+      return true
+    }
+
+    return super.allowsBlob(options)
+  }
+
+  override allowsRepo(options: RepoScopeMatch): boolean {
+    if (this.hasTransitionGeneric) {
+      return true
+    }
+
+    return super.allowsRepo(options)
+  }
+
+  override allowsRpc(options: RpcScopeMatch) {
+    const { lxm } = options
+
+    if (this.hasTransitionGeneric && lxm === '*') {
+      return true
+    }
+
+    if (this.hasTransitionGeneric && !lxm.startsWith('chat.bsky.')) {
+      return true
+    }
+
+    if (this.hasTransitionChatBsky && lxm.startsWith('chat.bsky.')) {
+      return true
+    }
+
+    return super.allowsRpc(options)
+  }
+}

package/src/permission-set.test.ts

@@ -0,0 +1,225 @@
+import { PermissionSet } from './permission-set.js'
+
+describe('PermissionSet', () => {
+  describe('allowsAccount', () => {
+    it('should properly allow "account:email"', () => {
+      const set = new PermissionSet('account:email')
+
+      expect(set.allowsAccount({ attr: 'email', action: 'read' })).toBe(true)
+      expect(set.allowsAccount({ attr: 'email', action: 'manage' })).toBe(false)
+
+      expect(set.allowsAccount({ attr: 'repo', action: 'read' })).toBe(false)
+      expect(set.allowsAccount({ attr: 'repo', action: 'manage' })).toBe(false)
+
+      expect(set.allowsAccount({ attr: 'status', action: 'read' })).toBe(false)
+      expect(set.allowsAccount({ attr: 'status', action: 'manage' })).toBe(
+        false,
+      )
+    })
+
+    it('should ignore "transition:email"', () => {
+      const set = new PermissionSet('transition:email')
+
+      expect(set.allowsAccount({ attr: 'email', action: 'read' })).toBe(false)
+      expect(set.allowsAccount({ attr: 'email', action: 'manage' })).toBe(false)
+    })
+  })
+
+  describe('allowsBlob', () => {
+    it('should allow any mime with "blob:*/*"', () => {
+      const set = new PermissionSet('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/*')
+      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:*')
+      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')
+      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')
+      expect(set.allowsBlob({ mime: 'image/png' })).toBe(false)
+      expect(set.allowsBlob({ mime: 'application/json' })).toBe(false)
+    })
+  })
+
+  describe('allowsRepo', () => {
+    it('should allow any repo action with "repo:*"', () => {
+      const set = new PermissionSet('repo:*')
+      expect(
+        set.allowsRepo({ collection: 'com.example.foo', action: 'create' }),
+      ).toBe(true)
+      expect(
+        set.allowsRepo({ collection: 'com.example.foo', action: 'update' }),
+      ).toBe(true)
+      expect(
+        set.allowsRepo({ collection: 'app.bsky.feed.post', action: 'delete' }),
+      ).toBe(true)
+    })
+
+    it('should allow specific repo actions', () => {
+      const set = new PermissionSet('repo:*?action=create')
+      expect(
+        set.allowsRepo({ collection: 'com.example.foo', action: 'create' }),
+      ).toBe(true)
+      expect(
+        set.allowsRepo({ collection: 'app.bsky.feed.post', action: 'create' }),
+      ).toBe(true)
+
+      // Control
+
+      expect(
+        set.allowsRepo({ collection: 'com.example.foo', action: 'update' }),
+      ).toBe(false)
+      expect(
+        set.allowsRepo({ collection: 'app.bsky.feed.post', action: 'delete' }),
+      ).toBe(false)
+    })
+
+    it('should allow specific repo collection & actions', () => {
+      const set = new PermissionSet('repo:com.example.foo?action=create')
+      expect(
+        set.allowsRepo({ collection: 'com.example.foo', action: 'create' }),
+      ).toBe(true)
+
+      // Control
+
+      expect(
+        set.allowsRepo({ collection: 'com.example.foo', action: 'update' }),
+      ).toBe(false)
+      expect(
+        set.allowsRepo({ collection: 'app.bsky.feed.post', action: 'delete' }),
+      ).toBe(false)
+      expect(
+        set.allowsRepo({ collection: 'app.bsky.feed.post', action: 'create' }),
+      ).toBe(false)
+    })
+
+    it('should ignore transition:generic', () => {
+      const set = new PermissionSet('transition:generic')
+      expect(
+        set.allowsRepo({ collection: 'app.bsky.feed.post', action: 'create' }),
+      ).toBe(false)
+      expect(
+        set.allowsRepo({ collection: 'app.bsky.feed.post', action: 'delete' }),
+      ).toBe(false)
+      expect(
+        set.allowsRepo({ collection: 'com.example.foo', action: 'create' }),
+      ).toBe(false)
+      expect(
+        set.allowsRepo({ collection: 'com.example.foo', action: 'update' }),
+      ).toBe(false)
+    })
+  })
+
+  describe('allowsRpc', () => {
+    it('should ignore "rpc:*?lxm=*"', () => {
+      const set = new PermissionSet('rpc:*?lxm=*')
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.method' }),
+      ).toBe(false)
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.getFeed' }),
+      ).toBe(false)
+    })
+
+    it('should allow constraining "lxm"', () => {
+      const set = new PermissionSet('rpc:app.bsky.feed.getFeed?aud=*')
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.getFeed' }),
+      ).toBe(true)
+      expect(
+        set.allowsRpc({ aud: 'did:plc:blahbla', lxm: 'app.bsky.feed.getFeed' }),
+      ).toBe(true)
+
+      // Control
+
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.method' }),
+      ).toBe(false)
+    })
+
+    it('should allow constraining "aud"', () => {
+      const set = new PermissionSet('rpc:*?aud=did:example:123')
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.method' }),
+      ).toBe(true)
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.getFeed' }),
+      ).toBe(true)
+
+      // Control
+
+      expect(
+        set.allowsRpc({ aud: 'did:plc:blahbla', 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',
+      )
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.getFeed' }),
+      ).toBe(true)
+
+      // Control
+
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.method' }),
+      ).toBe(false)
+      expect(
+        set.allowsRpc({ aud: 'did:plc:blahbla', lxm: 'app.bsky.feed.getFeed' }),
+      ).toBe(false)
+    })
+
+    it('should ignore "transition:generic"', () => {
+      const set = new PermissionSet('transition:generic')
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.getFeed' }),
+      ).toBe(false)
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.method' }),
+      ).toBe(false)
+    })
+
+    it('should ignore "transition:chat.bsky"', () => {
+      const set = new PermissionSet('transition:chat.bsky')
+      expect(
+        set.allowsRpc({
+          aud: 'did:example:123',
+          lxm: 'chat.bsky.message.send',
+        }),
+      ).toBe(false)
+      expect(
+        set.allowsRpc({
+          aud: 'did:example:123',
+          lxm: 'chat.bsky.conversation.get',
+        }),
+      ).toBe(false)
+
+      // Control
+
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'app.bsky.feed.post' }),
+      ).toBe(false)
+      expect(
+        set.allowsRpc({ aud: 'did:example:123', lxm: 'com.example.foo' }),
+      ).toBe(false)
+    })
+  })
+})