@atproto/oauth-scopes 0.0.2 → 0.1.0

package/dist/scopes-set.js

@@ -3,7 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ScopesSet = exports.ScopeMissingError = void 0;
 const scope_missing_error_js_1 = require("./scope-missing-error.js");
 Object.defineProperty(exports, "ScopeMissingError", { enumerable: true, get: function () { return scope_missing_error_js_1.ScopeMissingError; } });
-const utilities_js_1 = require("./utilities.js");
+const account_permission_js_1 = require("./scopes/account-permission.js");
+const blob_permission_js_1 = require("./scopes/blob-permission.js");
+const identity_permission_js_1 = require("./scopes/identity-permission.js");
+const repo_permission_js_1 = require("./scopes/repo-permission.js");
+const rpc_permission_js_1 = require("./scopes/rpc-permission.js");
 /**
  * Utility class to manage a set of scopes and check if they match specific
  * options for a given resource.
@@ -15,14 +19,14 @@ class ScopesSet extends Set {
      */
     matches(resource, options) {
         for (const scope of this) {
-            if ((0, utilities_js_1.scopeMatches)(scope, resource, options))
+            if (permissionScopeMatches(scope, resource, options))
                 return true;
         }
         return false;
     }
     assert(resource, options) {
         if (!this.matches(resource, options)) {
-            const scope = (0, utilities_js_1.scopeNeededFor)(resource, options);
+            const scope = scopeNeededFor(resource, options);
             throw new scope_missing_error_js_1.ScopeMissingError(scope);
         }
     }
@@ -52,4 +56,46 @@ class ScopesSet extends Set {
     }
 }
 exports.ScopesSet = ScopesSet;
+function scopeNeededFor(resource, options) {
+    switch (resource) {
+        case 'account':
+            return account_permission_js_1.AccountPermission.scopeNeededFor(options);
+        case 'identity':
+            return identity_permission_js_1.IdentityPermission.scopeNeededFor(options);
+        case 'repo':
+            return repo_permission_js_1.RepoPermission.scopeNeededFor(options);
+        case 'rpc':
+            return rpc_permission_js_1.RpcPermission.scopeNeededFor(options);
+        case 'blob':
+            return blob_permission_js_1.BlobPermission.scopeNeededFor(options);
+    }
+    // @ts-expect-error
+    throw new TypeError(`Unknown resource: ${resource}`);
+}
+function permissionScopeMatches(scope, resource, options) {
+    // @NOTE we might want to cache the parsed scopes though, in practice, a
+    // single scope is unlikely to be parsed multiple times during a single
+    // request.
+    const permission = parsePermissionScope(resource, scope);
+    if (!permission)
+        return false;
+    // @ts-expect-error
+    return permission.matches(options);
+}
+function parsePermissionScope(resource, scope) {
+    switch (resource) {
+        case 'account':
+            return account_permission_js_1.AccountPermission.fromString(scope);
+        case 'identity':
+            return identity_permission_js_1.IdentityPermission.fromString(scope);
+        case 'repo':
+            return repo_permission_js_1.RepoPermission.fromString(scope);
+        case 'rpc':
+            return rpc_permission_js_1.RpcPermission.fromString(scope);
+        case 'blob':
+            return blob_permission_js_1.BlobPermission.fromString(scope);
+        default:
+            return null;
+    }
+}
 //# sourceMappingURL=scopes-set.js.map

package/dist/scopes-set.js.map

@@ -1 +1 @@
-{"version":3,"file":"scopes-set.js","sourceRoot":"","sources":["../src/scopes-set.ts"],"names":[],"mappings":";;;AAAA,qEAA4D;AAOnD,kGAPA,0CAAiB,OAOA;AAN1B,iDAIuB;AAIvB;;;GAGG;AACH,MAAa,SAAU,SAAQ,GAAW;IACxC;;;OAGG;IACI,OAAO,CACZ,QAAW,EACX,OAA0C;QAE1C,KAAK,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;YACzB,IAAI,IAAA,2BAAY,EAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC;gBAAE,OAAO,IAAI,CAAA;QACzD,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IAEM,MAAM,CACX,QAAW,EACX,OAA0C;QAE1C,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC;YACrC,MAAM,KAAK,GAAG,IAAA,6BAAc,EAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;YAC/C,MAAM,IAAI,0CAAiB,CAAC,KAAK,CAAC,CAAA;QACpC,CAAC;IACH,CAAC;IAEM,IAAI,CAAC,EAA8B;QACxC,KAAK,MAAM,KAAK,IAAI,IAAI;YAAE,IAAI,EAAE,CAAC,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAA;QACpD,OAAO,KAAK,CAAA;IACd,CAAC;IAEM,KAAK,CAAC,EAA8B;QACzC,KAAK,MAAM,KAAK,IAAI,IAAI;YAAE,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAA;QACtD,OAAO,IAAI,CAAA;IACb,CAAC;IAEM,CAAC,MAAM,CAAC,EAA8B;QAC3C,KAAK,MAAM,KAAK,IAAI,IAAI;YAAE,IAAI,EAAE,CAAC,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAA;IACtD,CAAC;IAEM,CAAC,GAAG,CAAI,EAAwB;QACrC,KAAK,MAAM,KAAK,IAAI,IAAI;YAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAA;IAC3C,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,MAAe;QAC/B,OAAO,IAAI,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAA;IAC1C,CAAC;CACF;AA9CD,8BA8CC"}
+{"version":3,"file":"scopes-set.js","sourceRoot":"","sources":["../src/scopes-set.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/oauth-scopes",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "license": "MIT",
   "description": "A library for manipulating and validating ATproto OAuth scopes in TypeScript.",
   "keywords": [
@@ -24,13 +24,17 @@
       "default": "./dist/index.js"
     }
   },
-  "dependencies": {},
+  "dependencies": {
+    "@atproto/did": "^0.2.0",
+    "@atproto/lexicon": "^0.5.0",
+    "@atproto/syntax": "^0.4.1"
+  },
   "devDependencies": {
     "jest": "^28.1.2",
     "typescript": "^5.6.3"
   },
   "scripts": {
-    "build": "tsc --build tsconfig.json",
+    "build": "tsc --build tsconfig.build.json",
     "test": "jest"
   }
 }

package/src/atproto-oauth-scope.ts

@@ -0,0 +1,43 @@
+import { ScopeStringFor, isScopeStringFor } from './lib/syntax.js'
+import { AccountPermission } from './scopes/account-permission.js'
+import { BlobPermission } from './scopes/blob-permission.js'
+import { IdentityPermission } from './scopes/identity-permission.js'
+import { IncludeScope } from './scopes/include-scope.js'
+import { RepoPermission } from './scopes/repo-permission.js'
+import { RpcPermission } from './scopes/rpc-permission.js'
+
+export { type ScopeStringFor, isScopeStringFor }
+
+export type AtprotoOauthScope =
+  | 'atproto'
+  | 'transition:email'
+  | 'transition:generic'
+  | 'transition:chat.bsky'
+  | ScopeStringFor<'account'>
+  | ScopeStringFor<'blob'>
+  | ScopeStringFor<'identity'>
+  | ScopeStringFor<'include'>
+  | ScopeStringFor<'repo'>
+  | ScopeStringFor<'rpc'>
+
+/**
+ * @note This function does not only verify the scope string format (with
+ * {@link isScopeStringFor}), but also checks if the provided parameters are
+ * valid according to the respective scope syntax definition. This allows
+ * excluding scopes that cannot be fully interpreted by the current version of
+ * the code.
+ */
+export function isAtprotoOauthScope(value: string): value is AtprotoOauthScope {
+  return (
+    value === 'atproto' ||
+    value === 'transition:email' ||
+    value === 'transition:generic' ||
+    value === 'transition:chat.bsky' ||
+    AccountPermission.fromString(value) != null ||
+    BlobPermission.fromString(value) != null ||
+    IdentityPermission.fromString(value) != null ||
+    IncludeScope.fromString(value) != null ||
+    RepoPermission.fromString(value) != null ||
+    RpcPermission.fromString(value) != null
+  )
+}

package/src/index.ts

@@ -1,17 +1,13 @@
+export * from './atproto-oauth-scope.js'
+
 export * from './scope-missing-error.js'
-export * from './permission-set.js'
-export * from './permission-set-transition.js'
+export * from './scope-permissions-transition.js'
+export * from './scope-permissions.js'
 export * from './scopes-set.js'
-export * from './parser.js'
-export * from './syntax.js'
-export * from './utilities.js'
-
-export * from './resources/account-scope.js'
-export * from './resources/blob-scope.js'
-export * from './resources/identity-scope.js'
-export * from './resources/repo-scope.js'
-export * from './resources/rpc-scope.js'
 
-export * from './lib/mime.js'
-export * from './lib/did.js'
-export * from './lib/nsid.js'
+export * from './scopes/account-permission.js'
+export * from './scopes/blob-permission.js'
+export * from './scopes/identity-permission.js'
+export * from './scopes/include-scope.js'
+export * from './scopes/repo-permission.js'
+export * from './scopes/rpc-permission.js'

package/src/lib/lexicon.ts

@@ -0,0 +1 @@
+export type { LexPermission, LexPermissionSet } from '@atproto/lexicon'

package/src/lib/mime.ts

@@ -20,7 +20,8 @@ export function isMime(value: string): value is Mime {
 
 export type Accept = '*/*' | `${string}/*` | Mime
 
-export function isAccept(value: string): value is Accept {
+export function isAccept(value: unknown): value is Accept {
+  if (typeof value !== 'string') return false
   if (value === '*/*') return true // Fast path for the most common case
   if (!isStringSlashString(value)) return false
   return !value.includes('*') || value.endsWith('/*')

package/src/lib/nsid.ts

@@ -1,6 +1,5 @@
-export type NSID = `${string}.${string}`
-export const isNSID = (value: string): value is NSID =>
-  value.includes('.') &&
-  !value.includes(' ') &&
-  !value.startsWith('.') &&
-  !value.endsWith('.')
+import { isValidNsid } from '@atproto/syntax'
+
+export type Nsid = `${string}.${string}.${string}`
+export const isNsid = (v: unknown): v is Nsid =>
+  typeof v === 'string' && isValidNsid(v)

package/src/lib/parser.ts

@@ -0,0 +1,176 @@
+import { ScopeStringSyntax } from './syntax-string.js'
+import { NeRoArray, ParamValue, ScopeSyntax } from './syntax.js'
+
+type InferParamPredicate<T extends (value: ParamValue) => boolean> =
+  T extends ((value: ParamValue) => value is infer U extends ParamValue)
+    ? U
+    : ParamValue
+
+type ParamsSchema = Record<
+  string,
+  | {
+      multiple: false
+      required: boolean
+      default?: ParamValue
+      normalize?: (value: ParamValue) => ParamValue
+      validate: (value: ParamValue) => boolean
+    }
+  | {
+      multiple: true
+      required: boolean
+      default?: NeRoArray<ParamValue>
+      normalize?: (value: NeRoArray<ParamValue>) => NeRoArray<ParamValue>
+      validate: (value: ParamValue) => boolean
+    }
+>
+
+type InferParams<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<InferParamPredicate<S[K]['validate']>>
+        : InferParamPredicate<S[K]['validate']>)
+} & NonNullable<unknown>
+
+export class Parser<P extends string, S extends ParamsSchema> {
+  public readonly schemaKeys: ReadonlySet<keyof S & string>
+
+  constructor(
+    public readonly prefix: P,
+    public readonly schema: S,
+    public readonly positionalName?: keyof S & string,
+  ) {
+    this.schemaKeys = new Set(Object.keys(schema))
+  }
+
+  format(values: InferParams<S>) {
+    const params = new URLSearchParams()
+    let positional: string | undefined = undefined
+
+    for (const key of this.schemaKeys) {
+      const value = values[key]
+      // Ignore undefined values
+      if (value === undefined) continue
+
+      const schema = this.schema[key]
+
+      // 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
+        }
+      }
+
+      if (Array.isArray(normalized)) {
+        if (key === this.positionalName && normalized.length === 1) {
+          positional = String(normalized[0]!)
+        } else {
+          // remove duplicates
+          const unique = new Set(normalized.map(String))
+          for (const v of unique) params.append(key, v)
+        }
+      } else {
+        if (key === this.positionalName) {
+          positional = String(normalized)
+        } else {
+          params.set(key, String(normalized))
+        }
+      }
+    }
+
+    return new ScopeStringSyntax(this.prefix, positional, params).toString()
+  }
+
+  // @NOTE If we needed to ever have more detailed reason as to why parsing
+  // fails, this function could easily be updated to return a
+  // ValidationResult<T> type that explains the reason for failure.
+  parse(syntax: ScopeSyntax<P>) {
+    // @NOTE no need to check prefix, since the typing (P generic) already
+    // ensures it matches
+
+    for (const key of syntax.keys()) {
+      if (!this.schemaKeys.has(key)) return null
+    }
+
+    const result: Record<
+      string,
+      undefined | ParamValue | NeRoArray<ParamValue>
+    > = Object.create(null)
+
+    for (const key of this.schemaKeys) {
+      const definition = this.schema[key]
+
+      const param = definition.multiple
+        ? syntax.getMulti(key)
+        : syntax.getSingle(key)
+
+      if (param === null) {
+        return null // Value is not valid
+      } else if (param !== undefined) {
+        if (key === this.positionalName && syntax.positional !== undefined) {
+          // Positional parameter cannot be used with named parameters
+          return null
+        }
+
+        if (definition.multiple) {
+          // Empty array is not valid
+          if (!(param as ParamValue[]).length) return null
+          if (!(param as ParamValue[]).every(definition.validate)) {
+            return null
+          }
+        } else {
+          if (!definition.validate(param as ParamValue)) {
+            return null
+          }
+        }
+
+        result[key] = param as ParamValue | NeRoArray<ParamValue>
+      } else if (
+        key === this.positionalName &&
+        syntax.positional !== undefined
+      ) {
+        // No named parameters found, but there is a positional parameter
+        const { positional } = syntax
+        if (!definition.validate(positional)) {
+          return null
+        }
+        result[key] = definition.multiple ? [positional] : positional
+      } else if (definition.required) {
+        return null
+      } else {
+        result[key] = definition.default
+      }
+    }
+
+    return result as InferParams<S>
+  }
+}
+
+/**
+ * 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
+}

package/src/lib/resource-permission.ts

@@ -0,0 +1,10 @@
+import { ScopeStringFor } from './syntax.js'
+import { Matchable } from './util.js'
+
+/**
+ * Interface destined to provide consistency across parsed permission scopes for
+ * resources (blob, repo, etc.).
+ */
+export interface ResourcePermission<R extends string, T> extends Matchable<T> {
+  toString(): ScopeStringFor<R>
+}

package/src/lib/syntax-lexicon.ts

@@ -0,0 +1,55 @@
+import { LexPermission } from './lexicon.js'
+import { ScopeSyntax } from './syntax.js'
+
+/**
+ * Translates a {@link LexPermission} into a {@link ScopeSyntax}.
+ */
+export class LexPermissionSyntax<P extends string = string>
+  implements ScopeSyntax<P>
+{
+  constructor(
+    readonly lexPermission: Readonly<LexPermission & { resource: P }>,
+  ) {}
+
+  get prefix() {
+    return this.lexPermission.resource
+  }
+
+  get positional() {
+    return undefined
+  }
+
+  get(key: string) {
+    // Ignore reserved keywords
+    if (key === 'type') return undefined
+    if (key === 'resource') return undefined
+
+    // Ignore inherited properties (toString(), etc.)
+    if (!Object.hasOwn(this.lexPermission, key)) return undefined
+
+    return this.lexPermission[key]
+  }
+
+  *keys() {
+    for (const key of Object.keys(this.lexPermission)) {
+      if (this.get(key) !== undefined) yield key
+    }
+  }
+
+  getSingle(key: string) {
+    const value = this.get(key)
+    if (Array.isArray(value)) return null
+    return value
+  }
+
+  getMulti(key: string) {
+    const value = this.get(key)
+    if (value === undefined) return undefined
+    if (!Array.isArray(value)) return null
+    return value
+  }
+
+  toJSON() {
+    return this.lexPermission
+  }
+}

package/src/lib/syntax-string.test.ts

@@ -0,0 +1,130 @@
+import { ScopeStringSyntax } from './syntax-string.js'
+import { ScopeStringFor } from './syntax.js'
+
+describe('ScopeStringSyntax', () => {
+  for (const { scope, content } of [
+    {
+      scope: 'my-res',
+      content: { prefix: 'my-res' },
+    },
+    {
+      scope: 'my-res:my-pos',
+      content: { prefix: 'my-res', positional: 'my-pos' },
+    },
+    {
+      scope: 'my-res:',
+      content: { prefix: 'my-res', positional: '' },
+    },
+    {
+      scope: 'my-res:foo?x=value&y=value-y',
+      content: {
+        prefix: 'my-res',
+        positional: 'foo',
+        params: { x: ['value'], y: ['value-y'] },
+      },
+    },
+    {
+      scope: 'my-res?x=value&y=value-y',
+      content: { prefix: 'my-res', params: { x: ['value'], y: ['value-y'] } },
+    },
+    {
+      scope: 'my-res?x=foo&x=bar&x=baz',
+      content: { prefix: 'my-res', params: { x: ['foo', 'bar', 'baz'] } },
+    },
+    {
+      scope: 'rpc:foo.bar?aud=did:foo:bar?lxm=bar.baz',
+      content: {
+        prefix: 'rpc',
+        positional: 'foo.bar',
+        params: { aud: ['did:foo:bar?lxm=bar.baz'] },
+      },
+    },
+  ] satisfies Array<{
+    scope: ScopeStringFor<'my-res' | 'rpc'>
+    content: {
+      prefix: string
+      positional?: string
+      params?: Record<string, string[]>
+    }
+  }>) {
+    const syntax = ScopeStringSyntax.fromString<'my-res' | 'rpc'>(scope)
+
+    describe(scope, () => {
+      it('should match the expected syntax', () => {
+        expect(syntax).toMatchObject({
+          prefix: content.prefix,
+          positional: content.positional,
+        })
+      })
+
+      it(`should match ${scope} prefix`, () => {
+        expect(syntax.prefix).toBe(content.prefix)
+      })
+
+      it(`should return positional parameter`, () => {
+        expect(syntax.positional).toBe(content.positional)
+      })
+
+      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(`only contain allowed parameters`, () => {
+          const allowedParams = Object.keys(params) as [string, ...string[]]
+          expect(
+            Array.from(syntax.keys()).every((key) =>
+              allowedParams.includes(key),
+            ),
+          ).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()
+            })
+          }
+        }
+      }
+    })
+  }
+
+  describe('invalid positional parameters', () => {
+    it('should return null for positional parameters used together with named parameters', () => {
+      const syntax = ScopeStringSyntax.fromString('my-res:pos?x=value')
+      expect(syntax.getSingle('x')).toBe('value')
+      expect(syntax.getMulti('x')).toEqual(['value'])
+    })
+  })
+
+  describe('url encoding', () => {
+    it('should handle URL encoding in positional parameters', () => {
+      const syntax = ScopeStringSyntax.fromString('my-res:my%20pos')
+      expect(syntax.positional).toBe('my pos')
+    })
+
+    it('should handle URL encoding in named parameters', () => {
+      const syntax = ScopeStringSyntax.fromString('my-res?x=my%20value')
+      expect(syntax.getSingle('x')).toBe('my value')
+    })
+
+    it(`should allow colon (:) in positional parameters`, () => {
+      const syntax = ScopeStringSyntax.fromString('my-res:my:pos')
+      expect(syntax.positional).toBe('my:pos')
+    })
+  })
+})