OAuth scopes and email

[bitbeckers]

Add OAuth Scopes and Granular Permissions System

This PR implements a comprehensive OAuth permissions system to help developers easily define correct OAuth scopes, with specific support for accessing user emails via the OAuth flow.

Key Features

1. Permission Type System

• Zod schemas for all ATProto permission types: account, repo, blob, rpc, identity, include
• Support for both transitional (legacy) and granular permission models
• Type-safe transformations with proper validation and error messages

2. Fluent Permission Builder API

import { PermissionBuilder, buildScope } from '@hypercerts-org/sdk-core';

const scope = buildScope(
  new PermissionBuilder()
    .accountEmail('read')
    .repoWrite('app.bsky.feed.post')
    .blob(['image/*'])
    .build()
);

3. Scope Utilities

• buildScope(), parseScope(), hasPermission(), mergeScopes(), validateScope() and more
• 8 utility functions for working with OAuth scopes

4. Pre-built Scope Presets

import { ScopePresets } from '@hypercerts-org/sdk-core';

await sdk.authorize("user.bsky.social", { 
  scope: ScopePresets.EMAIL_AND_PROFILE 
});

• 14 ready-to-use presets: EMAIL_READ, POSTING_APP, FULL_ACCESS, etc.

5. Enhanced OAuth Integration

• Improved documentation with comprehensive examples
• Automatic scope validation with helpful warnings
• Migration suggestions from transitional to granular permissions

6. Email Access Helper

const emailInfo = await sdk.getAccountEmail(session);
if (emailInfo) {
  console.log(`Email: ${emailInfo.email}`);
  console.log(`Confirmed: ${emailInfo.emailConfirmed}`);
}

[changeset-bot]

🦋 Changeset detected

Latest commit: ec17a44

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@hypercerts-org/sdk-core	Minor
@hypercerts-org/sdk-react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR