@atproto/oauth-scopes 0.0.2 → 0.2.0

package/src/parser.ts

@@ -1,150 +0,0 @@
-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.ts

@@ -1,78 +0,0 @@
-import { AccountScope, AccountScopeMatch } from './resources/account-scope.js'
-import { BlobScope, BlobScopeMatch } from './resources/blob-scope.js'
-import {
-  IdentityScope,
-  IdentityScopeMatch,
-} from './resources/identity-scope.js'
-import { RepoScope, RepoScopeMatch } from './resources/repo-scope.js'
-import { RpcScope, RpcScopeMatch } from './resources/rpc-scope.js'
-import { ScopeMissingError } from './scope-missing-error.js'
-import { ScopesSet } from './scopes-set.js'
-
-export type {
-  AccountScopeMatch,
-  BlobScopeMatch,
-  IdentityScopeMatch,
-  RepoScopeMatch,
-  RpcScopeMatch,
-}
-
-export class PermissionSet {
-  public readonly scopes: ScopesSet
-
-  constructor(scopes?: null | string | Iterable<string>) {
-    this.scopes = new ScopesSet(
-      typeof scopes === 'string' ? scopes.split(' ') : scopes,
-    )
-  }
-
-  public allowsAccount(options: AccountScopeMatch): boolean {
-    return this.scopes.matches('account', options)
-  }
-  public assertAccount(options: AccountScopeMatch): void {
-    if (!this.allowsAccount(options)) {
-      const scope = AccountScope.scopeNeededFor(options)
-      throw new ScopeMissingError(scope)
-    }
-  }
-
-  public allowsIdentity(options: IdentityScopeMatch): boolean {
-    return this.scopes.matches('identity', options)
-  }
-  public assertIdentity(options: IdentityScopeMatch): void {
-    if (!this.allowsIdentity(options)) {
-      const scope = IdentityScope.scopeNeededFor(options)
-      throw new ScopeMissingError(scope)
-    }
-  }
-
-  public allowsBlob(options: BlobScopeMatch): boolean {
-    return this.scopes.matches('blob', options)
-  }
-  public assertBlob(options: BlobScopeMatch): void {
-    if (!this.allowsBlob(options)) {
-      const scope = BlobScope.scopeNeededFor(options)
-      throw new ScopeMissingError(scope)
-    }
-  }
-
-  public allowsRepo(options: RepoScopeMatch): boolean {
-    return this.scopes.matches('repo', options)
-  }
-  public assertRepo(options: RepoScopeMatch): void {
-    if (!this.allowsRepo(options)) {
-      const scope = RepoScope.scopeNeededFor(options)
-      throw new ScopeMissingError(scope)
-    }
-  }
-
-  public allowsRpc(options: RpcScopeMatch): boolean {
-    return this.scopes.matches('rpc', options)
-  }
-  public assertRpc(options: RpcScopeMatch): void {
-    if (!this.allowsRpc(options)) {
-      const scope = RpcScope.scopeNeededFor(options)
-      throw new ScopeMissingError(scope)
-    }
-  }
-}

package/src/resources/account-scope.ts

@@ -1,66 +0,0 @@
-import { Parser, knownValuesValidator } from '../parser.js'
-import { ResourceSyntax, isScopeForResource } from '../syntax.js'
-
-const ACCOUNT_ATTRIBUTES = Object.freeze(['email', 'repo', 'status'] as const)
-export type AccountAttribute = (typeof ACCOUNT_ATTRIBUTES)[number]
-
-const ACCOUNT_ACTIONS = Object.freeze(['read', 'manage'] as const)
-export type AccountAction = (typeof ACCOUNT_ACTIONS)[number]
-
-export const accountParser = new Parser(
-  'account',
-  {
-    attr: {
-      multiple: false,
-      required: true,
-      validate: knownValuesValidator(ACCOUNT_ATTRIBUTES),
-    },
-    action: {
-      multiple: false,
-      required: false,
-      validate: knownValuesValidator(ACCOUNT_ACTIONS),
-      default: 'read' as const,
-    },
-  },
-  'attr',
-)
-
-export type AccountScopeMatch = {
-  attr: AccountAttribute
-  action: AccountAction
-}
-
-export class AccountScope {
-  constructor(
-    public readonly attr: AccountAttribute,
-    public readonly action: AccountAction,
-  ) {}
-
-  matches(options: AccountScopeMatch): boolean {
-    return (
-      this.attr === options.attr &&
-      (this.action === 'manage' || this.action === options.action)
-    )
-  }
-
-  toString() {
-    return accountParser.format(this)
-  }
-
-  static fromString(scope: string) {
-    if (!isScopeForResource(scope, 'account')) return null
-    const syntax = ResourceSyntax.fromString(scope)
-    return this.fromSyntax(syntax)
-  }
-
-  static fromSyntax(syntax: ResourceSyntax) {
-    const result = accountParser.parse(syntax)
-    if (!result) return null
-
-    return new AccountScope(result.attr, result.action)
-  }
-
-  static scopeNeededFor(options: AccountScopeMatch): string {
-    return accountParser.format(options)
-  }
-}

package/src/resources/blob-scope.ts

@@ -1,86 +0,0 @@
-import { Accept, isAccept, matchesAnyAccept } from '../lib/mime.js'
-import { Parser } from '../parser.js'
-import { NeRoArray, ResourceSyntax, isScopeForResource } from '../syntax.js'
-
-export const DEFAULT_ACCEPT = Object.freeze(['*/*'] as const)
-
-export const blobParser = new Parser(
-  'blob',
-  {
-    accept: {
-      multiple: true,
-      required: true,
-      validate: isAccept,
-      normalize: (value) => {
-        // Returns a more concise representation of the accept values.
-        if (value.includes('*/*')) return DEFAULT_ACCEPT
-
-        return value.map(toLowerCase).filter(isNonRedundant) as [
-          Accept,
-          ...Accept[],
-        ]
-      },
-    },
-  },
-  'accept',
-)
-
-export type BlobScopeMatch = {
-  mime: string
-}
-
-export class BlobScope {
-  constructor(public readonly accept: NeRoArray<Accept>) {}
-
-  matches(options: BlobScopeMatch) {
-    return matchesAnyAccept(this.accept, options.mime)
-  }
-
-  toString() {
-    return blobParser.format(this)
-  }
-
-  static fromString(scope: string) {
-    if (!isScopeForResource(scope, 'blob')) return null
-    const syntax = ResourceSyntax.fromString(scope)
-    return this.fromSyntax(syntax)
-  }
-
-  static fromSyntax(syntax: ResourceSyntax) {
-    const result = blobParser.parse(syntax)
-    if (!result) return null
-
-    return new BlobScope(result.accept)
-  }
-
-  static scopeNeededFor(options: BlobScopeMatch) {
-    return blobParser.format({
-      accept: [options.mime as Accept],
-    })
-  }
-}
-
-function toLowerCase(value: string): string {
-  return value.toLowerCase()
-}
-
-function isNonRedundant(
-  value: string,
-  index: number,
-  arr: readonly string[],
-): boolean {
-  if (value.endsWith('/*')) {
-    // assuming the array contains unique element, wildcards cannot be redundant
-    // with one another ('image/*' is not redundant with 'text/*')
-    return true
-  }
-  const base = value.split('/', 1)[0]
-  if (arr.includes(`${base}/*`)) {
-    // If another value in the array is a wildcard for the same base, we can
-    // skip this one as it is redundant. e.g. if the array contains 'image/png'
-    // and 'image/*', we can skip 'image/png' because 'image/*' already covers
-    // it.
-    return false
-  }
-  return true
-}

package/src/resources/identity-scope.ts

@@ -1,49 +0,0 @@
-import { Parser, knownValuesValidator } from '../parser.js'
-import { ResourceSyntax, isScopeForResource } from '../syntax.js'
-
-const IDENTITY_ATTRIBUTES = Object.freeze(['handle', '*'] as const)
-export type IdentityAttribute = (typeof IDENTITY_ATTRIBUTES)[number]
-
-export const identityParser = new Parser(
-  'identity',
-  {
-    attr: {
-      multiple: false,
-      required: true,
-      validate: knownValuesValidator(IDENTITY_ATTRIBUTES),
-    },
-  },
-  'attr',
-)
-
-export type IdentityScopeMatch = {
-  attr: IdentityAttribute
-}
-
-export class IdentityScope {
-  constructor(public readonly attr: IdentityAttribute) {}
-
-  matches(options: IdentityScopeMatch): boolean {
-    return this.attr === '*' || this.attr === options.attr
-  }
-
-  toString() {
-    return identityParser.format(this)
-  }
-
-  static fromString(scope: string) {
-    if (!isScopeForResource(scope, 'identity')) return null
-    const syntax = ResourceSyntax.fromString(scope)
-    return this.fromSyntax(syntax)
-  }
-
-  static fromSyntax(syntax: ResourceSyntax) {
-    const result = identityParser.parse(syntax)
-    if (!result) return null
-    return new IdentityScope(result.attr)
-  }
-
-  static scopeNeededFor(options: IdentityScopeMatch): string {
-    return identityParser.format(options)
-  }
-}

package/src/resources/repo-scope.ts

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