@hypercerts-org/sdk-core 0.9.0-beta.0 → 0.10.0-beta.0

package/dist/index.cjs

@@ -1,11 +1,11 @@
 'use strict';
 
 var oauthClientNode = require('@atproto/oauth-client-node');
+var zod = require('zod');
 var lexicon$1 = require('@atproto/lexicon');
 var lexicon = require('@hypercerts-org/lexicon');
 var api = require('@atproto/api');
 var eventemitter3 = require('eventemitter3');
-var zod = require('zod');
 
 /**
  * Base error class for all SDK errors.
@@ -523,6 +523,990 @@ class InMemoryStateStore {
     }
 }
 
+/**
+ * OAuth Scopes and Granular Permissions
+ *
+ * This module provides type-safe, Zod-validated OAuth scope and permission management
+ * for the ATProto SDK. It supports both legacy transitional scopes and the new
+ * granular permissions model.
+ *
+ * @see https://atproto.com/specs/oauth
+ * @see https://atproto.com/specs/permission
+ *
+ * @module auth/permissions
+ */
+/**
+ * Base OAuth scope - required for all sessions
+ *
+ * @constant
+ */
+const ATPROTO_SCOPE = "atproto";
+/**
+ * Transitional OAuth scopes for legacy compatibility.
+ *
+ * These scopes provide broad access and are maintained for backwards compatibility.
+ * New applications should use granular permissions instead.
+ *
+ * @deprecated Use granular permissions (account:*, repo:*, etc.) for better control
+ * @constant
+ */
+const TRANSITION_SCOPES = {
+    /** Broad PDS permissions including record creation, blob uploads, and preferences */
+    GENERIC: "transition:generic",
+    /** Direct messages access (requires transition:generic) */
+    CHAT: "transition:chat.bsky",
+    /** Email address and confirmation status */
+    EMAIL: "transition:email",
+};
+/**
+ * Zod schema for transitional scopes.
+ *
+ * Validates that a scope string is one of the known transitional scopes.
+ *
+ * @example
+ * ```typescript
+ * TransitionScopeSchema.parse('transition:email'); // Valid
+ * TransitionScopeSchema.parse('invalid'); // Throws ZodError
+ * ```
+ */
+const TransitionScopeSchema = zod.z
+    .enum(["transition:generic", "transition:chat.bsky", "transition:email"])
+    .describe("Legacy transitional OAuth scopes");
+/**
+ * Zod schema for account permission attributes.
+ *
+ * Account attributes specify what aspect of the account is being accessed.
+ */
+const AccountAttrSchema = zod.z.enum(["email", "repo"]);
+/**
+ * Zod schema for account actions.
+ *
+ * Account actions specify the level of access (read-only or management).
+ */
+const AccountActionSchema = zod.z.enum(["read", "manage"]);
+/**
+ * Zod schema for repository actions.
+ *
+ * Repository actions specify what operations can be performed on records.
+ */
+const RepoActionSchema = zod.z.enum(["create", "update", "delete"]);
+/**
+ * Zod schema for identity permission attributes.
+ *
+ * Identity attributes specify what identity information can be managed.
+ */
+const IdentityAttrSchema = zod.z.enum(["handle", "*"]);
+/**
+ * Zod schema for MIME type patterns.
+ *
+ * Validates MIME type strings like "image/*" or "video/mp4".
+ *
+ * @example
+ * ```typescript
+ * MimeTypeSchema.parse('image/*'); // Valid
+ * MimeTypeSchema.parse('video/mp4'); // Valid
+ * MimeTypeSchema.parse('invalid'); // Throws ZodError
+ * ```
+ */
+const MimeTypeSchema = zod.z
+    .string()
+    .regex(/^[a-z]+\/[a-z0-9*+-]+$/i, 'Invalid MIME type pattern. Expected format: type/subtype (e.g., "image/*" or "video/mp4")');
+/**
+ * Zod schema for NSID (Namespaced Identifier).
+ *
+ * NSIDs are reverse-DNS style identifiers used throughout ATProto
+ * (e.g., "app.bsky.feed.post" or "com.example.myrecord").
+ *
+ * @see https://atproto.com/specs/nsid
+ *
+ * @example
+ * ```typescript
+ * NsidSchema.parse('app.bsky.feed.post'); // Valid
+ * NsidSchema.parse('com.example.myrecord'); // Valid
+ * NsidSchema.parse('InvalidNSID'); // Throws ZodError
+ * ```
+ */
+const NsidSchema = zod.z
+    .string()
+    .regex(/^[a-zA-Z][a-zA-Z0-9-]*(\.[a-zA-Z][a-zA-Z0-9-]*)+$/, 'Invalid NSID format. Expected reverse-DNS format (e.g., "app.bsky.feed.post")');
+/**
+ * Zod schema for account permission.
+ *
+ * Account permissions control access to account-level information like email
+ * and repository management.
+ *
+ * @example Without action (read-only)
+ * ```typescript
+ * const input = { type: 'account', attr: 'email' };
+ * AccountPermissionSchema.parse(input); // Returns: "account:email"
+ * ```
+ *
+ * @example With action
+ * ```typescript
+ * const input = { type: 'account', attr: 'email', action: 'manage' };
+ * AccountPermissionSchema.parse(input); // Returns: "account:email?action=manage"
+ * ```
+ */
+const AccountPermissionSchema = zod.z
+    .object({
+    type: zod.z.literal("account"),
+    attr: AccountAttrSchema,
+    action: AccountActionSchema.optional(),
+})
+    .transform(({ attr, action }) => {
+    let perm = `account:${attr}`;
+    if (action) {
+        perm += `?action=${action}`;
+    }
+    return perm;
+});
+/**
+ * Zod schema for repository permission.
+ *
+ * Repository permissions control write access to records by collection type.
+ * The collection must be a valid NSID or wildcard (*).
+ *
+ * @example Without actions (all actions allowed)
+ * ```typescript
+ * const input = { type: 'repo', collection: 'app.bsky.feed.post' };
+ * RepoPermissionSchema.parse(input); // Returns: "repo:app.bsky.feed.post"
+ * ```
+ *
+ * @example With specific actions
+ * ```typescript
+ * const input = {
+ *   type: 'repo',
+ *   collection: 'app.bsky.feed.post',
+ *   actions: ['create', 'update']
+ * };
+ * RepoPermissionSchema.parse(input); // Returns: "repo:app.bsky.feed.post?action=create&action=update"
+ * ```
+ *
+ * @example With wildcard collection
+ * ```typescript
+ * const input = { type: 'repo', collection: '*', actions: ['delete'] };
+ * RepoPermissionSchema.parse(input); // Returns: "repo:*?action=delete"
+ * ```
+ */
+const RepoPermissionSchema = zod.z
+    .object({
+    type: zod.z.literal("repo"),
+    collection: NsidSchema.or(zod.z.literal("*")),
+    actions: zod.z.array(RepoActionSchema).optional(),
+})
+    .transform(({ collection, actions }) => {
+    let perm = `repo:${collection}`;
+    if (actions && actions.length > 0) {
+        const params = actions.map((a) => `action=${a}`).join("&");
+        perm += `?${params}`;
+    }
+    return perm;
+});
+/**
+ * Zod schema for blob permission.
+ *
+ * Blob permissions control media file uploads constrained by MIME type patterns.
+ *
+ * @example Single MIME type
+ * ```typescript
+ * const input = { type: 'blob', mimeTypes: ['image/*'] };
+ * BlobPermissionSchema.parse(input); // Returns: "blob:image/*"
+ * ```
+ *
+ * @example Multiple MIME types
+ * ```typescript
+ * const input = { type: 'blob', mimeTypes: ['image/*', 'video/*'] };
+ * BlobPermissionSchema.parse(input); // Returns: "blob?accept=image/*&accept=video/*"
+ * ```
+ */
+const BlobPermissionSchema = zod.z
+    .object({
+    type: zod.z.literal("blob"),
+    mimeTypes: zod.z.array(MimeTypeSchema).min(1, "At least one MIME type required"),
+})
+    .transform(({ mimeTypes }) => {
+    if (mimeTypes.length === 1) {
+        return `blob:${mimeTypes[0]}`;
+    }
+    const accepts = mimeTypes.map((t) => `accept=${encodeURIComponent(t)}`).join("&");
+    return `blob?${accepts}`;
+});
+/**
+ * Zod schema for RPC permission.
+ *
+ * RPC permissions control authenticated API calls to remote services.
+ * At least one of lexicon or aud must be restricted (both cannot be wildcards).
+ *
+ * @example Specific lexicon with wildcard audience
+ * ```typescript
+ * const input = {
+ *   type: 'rpc',
+ *   lexicon: 'com.atproto.repo.createRecord',
+ *   aud: '*'
+ * };
+ * RpcPermissionSchema.parse(input);
+ * // Returns: "rpc:com.atproto.repo.createRecord?aud=*"
+ * ```
+ *
+ * @example With specific audience
+ * ```typescript
+ * const input = {
+ *   type: 'rpc',
+ *   lexicon: 'com.atproto.repo.createRecord',
+ *   aud: 'did:web:api.example.com',
+ *   inheritAud: true
+ * };
+ * RpcPermissionSchema.parse(input);
+ * // Returns: "rpc:com.atproto.repo.createRecord?aud=did%3Aweb%3Aapi.example.com&inheritAud=true"
+ * ```
+ */
+const RpcPermissionSchema = zod.z
+    .object({
+    type: zod.z.literal("rpc"),
+    lexicon: NsidSchema.or(zod.z.literal("*")),
+    aud: zod.z.string().min(1, "Audience is required"),
+    inheritAud: zod.z.boolean().optional(),
+})
+    .refine(({ lexicon, aud }) => lexicon !== "*" || aud !== "*", "At least one of lexicon or aud must be restricted (wildcards cannot both be used)")
+    .transform(({ lexicon, aud, inheritAud }) => {
+    let perm = `rpc:${lexicon}?aud=${encodeURIComponent(aud)}`;
+    if (inheritAud) {
+        perm += "&inheritAud=true";
+    }
+    return perm;
+});
+/**
+ * Zod schema for identity permission.
+ *
+ * Identity permissions control access to DID documents and handles.
+ *
+ * @example Handle management
+ * ```typescript
+ * const input = { type: 'identity', attr: 'handle' };
+ * IdentityPermissionSchema.parse(input); // Returns: "identity:handle"
+ * ```
+ *
+ * @example All identity attributes
+ * ```typescript
+ * const input = { type: 'identity', attr: '*' };
+ * IdentityPermissionSchema.parse(input); // Returns: "identity:*"
+ * ```
+ */
+const IdentityPermissionSchema = zod.z
+    .object({
+    type: zod.z.literal("identity"),
+    attr: IdentityAttrSchema,
+})
+    .transform(({ attr }) => `identity:${attr}`);
+/**
+ * Zod schema for permission set inclusion.
+ *
+ * Include permissions reference permission sets bundled under a single NSID.
+ *
+ * @example Without audience
+ * ```typescript
+ * const input = { type: 'include', nsid: 'com.example.authBasicFeatures' };
+ * IncludePermissionSchema.parse(input);
+ * // Returns: "include:com.example.authBasicFeatures"
+ * ```
+ *
+ * @example With audience
+ * ```typescript
+ * const input = {
+ *   type: 'include',
+ *   nsid: 'com.example.authBasicFeatures',
+ *   aud: 'did:web:api.example.com'
+ * };
+ * IncludePermissionSchema.parse(input);
+ * // Returns: "include:com.example.authBasicFeatures?aud=did%3Aweb%3Aapi.example.com"
+ * ```
+ */
+const IncludePermissionSchema = zod.z
+    .object({
+    type: zod.z.literal("include"),
+    nsid: NsidSchema,
+    aud: zod.z.string().optional(),
+})
+    .transform(({ nsid, aud }) => {
+    let perm = `include:${nsid}`;
+    if (aud) {
+        perm += `?aud=${encodeURIComponent(aud)}`;
+    }
+    return perm;
+});
+/**
+ * Union schema for all permission types.
+ *
+ * This schema accepts any of the supported permission types and validates
+ * them according to their specific rules.
+ */
+const PermissionSchema = zod.z.union([
+    AccountPermissionSchema,
+    RepoPermissionSchema,
+    BlobPermissionSchema,
+    RpcPermissionSchema,
+    IdentityPermissionSchema,
+    IncludePermissionSchema,
+]);
+/**
+ * Fluent builder for constructing OAuth permission arrays.
+ *
+ * This class provides a convenient, type-safe way to build arrays of permissions
+ * using method chaining.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const builder = new PermissionBuilder()
+ *   .accountEmail('read')
+ *   .repoWrite('app.bsky.feed.post')
+ *   .blob(['image/*', 'video/*']);
+ *
+ * const permissions = builder.build();
+ * // Returns: ['account:email?action=read', 'repo:app.bsky.feed.post?action=create&action=update', 'blob:image/*,video/*']
+ * ```
+ *
+ * @example With transitional scopes
+ * ```typescript
+ * const builder = new PermissionBuilder()
+ *   .transition('email')
+ *   .transition('generic');
+ *
+ * const scopes = builder.build();
+ * // Returns: ['transition:email', 'transition:generic']
+ * ```
+ */
+class PermissionBuilder {
+    constructor() {
+        this.permissions = [];
+    }
+    /**
+     * Add a transitional scope.
+     *
+     * @param scope - The transitional scope name ('email', 'generic', or 'chat.bsky')
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.transition('email').transition('generic');
+     * ```
+     */
+    transition(scope) {
+        const fullScope = `transition:${scope}`;
+        const validated = TransitionScopeSchema.parse(fullScope);
+        this.permissions.push(validated);
+        return this;
+    }
+    /**
+     * Add an account permission.
+     *
+     * @param attr - The account attribute ('email' or 'repo')
+     * @param action - Optional action ('read' or 'manage')
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.accountEmail('read').accountRepo('manage');
+     * ```
+     */
+    account(attr, action) {
+        const permission = AccountPermissionSchema.parse({
+            type: "account",
+            attr,
+            action,
+        });
+        this.permissions.push(permission);
+        return this;
+    }
+    /**
+     * Convenience method for account:email permission.
+     *
+     * @param action - Optional action ('read' or 'manage')
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.accountEmail('read');
+     * ```
+     */
+    accountEmail(action) {
+        return this.account("email", action);
+    }
+    /**
+     * Convenience method for account:repo permission.
+     *
+     * @param action - Optional action ('read' or 'manage')
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.accountRepo('manage');
+     * ```
+     */
+    accountRepo(action) {
+        return this.account("repo", action);
+    }
+    /**
+     * Add a repository permission.
+     *
+     * @param collection - The NSID of the collection or '*' for all
+     * @param actions - Optional array of actions ('create', 'update', 'delete')
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.repo('app.bsky.feed.post', ['create', 'update']);
+     * ```
+     */
+    repo(collection, actions) {
+        const permission = RepoPermissionSchema.parse({
+            type: "repo",
+            collection,
+            actions,
+        });
+        this.permissions.push(permission);
+        return this;
+    }
+    /**
+     * Convenience method for repository write permissions (create + update).
+     *
+     * @param collection - The NSID of the collection or '*' for all
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.repoWrite('app.bsky.feed.post');
+     * ```
+     */
+    repoWrite(collection) {
+        return this.repo(collection, ["create", "update"]);
+    }
+    /**
+     * Convenience method for repository read permission (no actions).
+     *
+     * @param collection - The NSID of the collection or '*' for all
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.repoRead('app.bsky.feed.post');
+     * ```
+     */
+    repoRead(collection) {
+        return this.repo(collection, []);
+    }
+    /**
+     * Convenience method for full repository permissions (create + update + delete).
+     *
+     * @param collection - The NSID of the collection or '*' for all
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.repoFull('app.bsky.feed.post');
+     * ```
+     */
+    repoFull(collection) {
+        return this.repo(collection, ["create", "update", "delete"]);
+    }
+    /**
+     * Add a blob permission.
+     *
+     * @param mimeTypes - Array of MIME types or a single MIME type
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.blob(['image/*', 'video/*']);
+     * builder.blob('image/*');
+     * ```
+     */
+    blob(mimeTypes) {
+        const types = Array.isArray(mimeTypes) ? mimeTypes : [mimeTypes];
+        const permission = BlobPermissionSchema.parse({
+            type: "blob",
+            mimeTypes: types,
+        });
+        this.permissions.push(permission);
+        return this;
+    }
+    /**
+     * Add an RPC permission.
+     *
+     * @param lexicon - The NSID of the lexicon or '*' for all
+     * @param aud - The audience (DID or URL)
+     * @param inheritAud - Whether to inherit audience
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.rpc('com.atproto.repo.createRecord', 'did:web:api.example.com');
+     * ```
+     */
+    rpc(lexicon, aud, inheritAud) {
+        const permission = RpcPermissionSchema.parse({
+            type: "rpc",
+            lexicon,
+            aud,
+            inheritAud,
+        });
+        this.permissions.push(permission);
+        return this;
+    }
+    /**
+     * Add an identity permission.
+     *
+     * @param attr - The identity attribute ('handle' or '*')
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.identity('handle');
+     * ```
+     */
+    identity(attr) {
+        const permission = IdentityPermissionSchema.parse({
+            type: "identity",
+            attr,
+        });
+        this.permissions.push(permission);
+        return this;
+    }
+    /**
+     * Add an include permission.
+     *
+     * @param nsid - The NSID of the scope set to include
+     * @param aud - Optional audience restriction
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.include('com.example.authBasicFeatures');
+     * ```
+     */
+    include(nsid, aud) {
+        const permission = IncludePermissionSchema.parse({
+            type: "include",
+            nsid,
+            aud,
+        });
+        this.permissions.push(permission);
+        return this;
+    }
+    /**
+     * Add a custom permission string directly (bypasses validation).
+     *
+     * Use this for testing or special cases where you need to add
+     * a permission that doesn't fit the standard types.
+     *
+     * @param permission - The permission string
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.custom('atproto');
+     * ```
+     */
+    custom(permission) {
+        this.permissions.push(permission);
+        return this;
+    }
+    /**
+     * Add the base atproto scope.
+     *
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.atproto();
+     * ```
+     */
+    atproto() {
+        this.permissions.push(ATPROTO_SCOPE);
+        return this;
+    }
+    /**
+     * Build and return the array of permission strings.
+     *
+     * @returns Array of permission strings
+     *
+     * @example
+     * ```typescript
+     * const permissions = builder.build();
+     * ```
+     */
+    build() {
+        return [...this.permissions];
+    }
+    /**
+     * Clear all permissions from the builder.
+     *
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.clear().accountEmail('read');
+     * ```
+     */
+    clear() {
+        this.permissions = [];
+        return this;
+    }
+    /**
+     * Get the current number of permissions.
+     *
+     * @returns The number of permissions
+     *
+     * @example
+     * ```typescript
+     * const count = builder.count();
+     * ```
+     */
+    count() {
+        return this.permissions.length;
+    }
+}
+/**
+ * Build a scope string from an array of permissions.
+ *
+ * This is a convenience function that joins permission strings with spaces,
+ * which is the standard format for OAuth scope parameters.
+ *
+ * @param permissions - Array of permission strings
+ * @returns Space-separated scope string
+ *
+ * @example
+ * ```typescript
+ * const permissions = ['account:email?action=read', 'repo:app.bsky.feed.post'];
+ * const scope = buildScope(permissions);
+ * // Returns: "account:email?action=read repo:app.bsky.feed.post"
+ * ```
+ */
+function buildScope(permissions) {
+    return permissions.join(" ");
+}
+/**
+ * Pre-built scope presets for common use cases.
+ *
+ * These presets provide ready-to-use permission sets for typical application scenarios.
+ */
+const ScopePresets = {
+    /**
+     * Email access scope - allows reading user's email address.
+     *
+     * Includes:
+     * - account:email?action=read
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.EMAIL_READ;
+     * // Use in OAuth flow to request email access
+     * ```
+     */
+    EMAIL_READ: buildScope(new PermissionBuilder().accountEmail("read").build()),
+    /**
+     * Profile read scope - allows reading user's profile.
+     *
+     * Includes:
+     * - repo:app.bsky.actor.profile (read-only)
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.PROFILE_READ;
+     * ```
+     */
+    PROFILE_READ: buildScope(new PermissionBuilder().repoRead("app.bsky.actor.profile").build()),
+    /**
+     * Profile write scope - allows updating user's profile.
+     *
+     * Includes:
+     * - repo:app.bsky.actor.profile (create + update)
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.PROFILE_WRITE;
+     * ```
+     */
+    PROFILE_WRITE: buildScope(new PermissionBuilder().repoWrite("app.bsky.actor.profile").build()),
+    /**
+     * Post creation scope - allows creating and updating posts.
+     *
+     * Includes:
+     * - repo:app.bsky.feed.post (create + update)
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.POST_WRITE;
+     * ```
+     */
+    POST_WRITE: buildScope(new PermissionBuilder().repoWrite("app.bsky.feed.post").build()),
+    /**
+     * Social interactions scope - allows liking, reposting, and following.
+     *
+     * Includes:
+     * - repo:app.bsky.feed.like (create + update)
+     * - repo:app.bsky.feed.repost (create + update)
+     * - repo:app.bsky.graph.follow (create + update)
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.SOCIAL_WRITE;
+     * ```
+     */
+    SOCIAL_WRITE: buildScope(new PermissionBuilder()
+        .repoWrite("app.bsky.feed.like")
+        .repoWrite("app.bsky.feed.repost")
+        .repoWrite("app.bsky.graph.follow")
+        .build()),
+    /**
+     * Media upload scope - allows uploading images and videos.
+     *
+     * Includes:
+     * - blob permissions for image/* and video/*
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.MEDIA_UPLOAD;
+     * ```
+     */
+    MEDIA_UPLOAD: buildScope(new PermissionBuilder().blob(["image/*", "video/*"]).build()),
+    /**
+     * Image upload only scope - allows uploading images.
+     *
+     * Includes:
+     * - blob:image/*
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.IMAGE_UPLOAD;
+     * ```
+     */
+    IMAGE_UPLOAD: buildScope(new PermissionBuilder().blob("image/*").build()),
+    /**
+     * Posting app scope - full posting capabilities including media.
+     *
+     * Includes:
+     * - repo:app.bsky.feed.post (create + update)
+     * - repo:app.bsky.feed.like (create + update)
+     * - repo:app.bsky.feed.repost (create + update)
+     * - blob permissions for image/* and video/*
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.POSTING_APP;
+     * ```
+     */
+    POSTING_APP: buildScope(new PermissionBuilder()
+        .repoWrite("app.bsky.feed.post")
+        .repoWrite("app.bsky.feed.like")
+        .repoWrite("app.bsky.feed.repost")
+        .blob(["image/*", "video/*"])
+        .build()),
+    /**
+     * Read-only app scope - allows reading all repository data.
+     *
+     * Includes:
+     * - repo:* (read-only, no actions)
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.READ_ONLY;
+     * ```
+     */
+    READ_ONLY: buildScope(new PermissionBuilder().repoRead("*").build()),
+    /**
+     * Full access scope - allows all repository operations.
+     *
+     * Includes:
+     * - repo:* (create + update + delete)
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.FULL_ACCESS;
+     * ```
+     */
+    FULL_ACCESS: buildScope(new PermissionBuilder().repoFull("*").build()),
+    /**
+     * Email + Profile scope - common combination for user identification.
+     *
+     * Includes:
+     * - account:email?action=read
+     * - repo:app.bsky.actor.profile (read-only)
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.EMAIL_AND_PROFILE;
+     * ```
+     */
+    EMAIL_AND_PROFILE: buildScope(new PermissionBuilder().accountEmail("read").repoRead("app.bsky.actor.profile").build()),
+    /**
+     * Transitional email scope (legacy).
+     *
+     * Uses the transitional scope format for backward compatibility.
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.TRANSITION_EMAIL;
+     * ```
+     */
+    TRANSITION_EMAIL: buildScope(new PermissionBuilder().transition("email").build()),
+    /**
+     * Transitional generic scope (legacy).
+     *
+     * Uses the transitional scope format for backward compatibility.
+     *
+     * @example
+     * ```typescript
+     * const scope = ScopePresets.TRANSITION_GENERIC;
+     * ```
+     */
+    TRANSITION_GENERIC: buildScope(new PermissionBuilder().transition("generic").build()),
+};
+/**
+ * Parse a scope string into an array of individual permissions.
+ *
+ * This splits a space-separated scope string into individual permission strings.
+ *
+ * @param scope - Space-separated scope string
+ * @returns Array of permission strings
+ *
+ * @example
+ * ```typescript
+ * const scope = "account:email?action=read repo:app.bsky.feed.post";
+ * const permissions = parseScope(scope);
+ * // Returns: ['account:email?action=read', 'repo:app.bsky.feed.post']
+ * ```
+ */
+function parseScope(scope) {
+    return scope.trim().split(/\s+/).filter(Boolean);
+}
+/**
+ * Check if a scope string contains a specific permission.
+ *
+ * This function performs exact string matching. For more advanced
+ * permission checking (e.g., wildcard matching), you'll need to
+ * implement custom logic.
+ *
+ * @param scope - Space-separated scope string
+ * @param permission - The permission to check for
+ * @returns True if the scope contains the permission
+ *
+ * @example
+ * ```typescript
+ * const scope = "account:email?action=read repo:app.bsky.feed.post";
+ * hasPermission(scope, "account:email?action=read"); // true
+ * hasPermission(scope, "account:repo"); // false
+ * ```
+ */
+function hasPermission(scope, permission) {
+    const permissions = parseScope(scope);
+    return permissions.includes(permission);
+}
+/**
+ * Check if a scope string contains all of the specified permissions.
+ *
+ * @param scope - Space-separated scope string
+ * @param requiredPermissions - Array of permissions to check for
+ * @returns True if the scope contains all required permissions
+ *
+ * @example
+ * ```typescript
+ * const scope = "account:email?action=read repo:app.bsky.feed.post blob:image/*";
+ * hasAllPermissions(scope, ["account:email?action=read", "blob:image/*"]); // true
+ * hasAllPermissions(scope, ["account:email?action=read", "account:repo"]); // false
+ * ```
+ */
+function hasAllPermissions(scope, requiredPermissions) {
+    const permissions = parseScope(scope);
+    return requiredPermissions.every((required) => permissions.includes(required));
+}
+/**
+ * Check if a scope string contains any of the specified permissions.
+ *
+ * @param scope - Space-separated scope string
+ * @param checkPermissions - Array of permissions to check for
+ * @returns True if the scope contains at least one of the permissions
+ *
+ * @example
+ * ```typescript
+ * const scope = "account:email?action=read repo:app.bsky.feed.post";
+ * hasAnyPermission(scope, ["account:email?action=read", "account:repo"]); // true
+ * hasAnyPermission(scope, ["account:repo", "identity:handle"]); // false
+ * ```
+ */
+function hasAnyPermission(scope, checkPermissions) {
+    const permissions = parseScope(scope);
+    return checkPermissions.some((check) => permissions.includes(check));
+}
+/**
+ * Merge multiple scope strings into a single scope string with deduplicated permissions.
+ *
+ * @param scopes - Array of scope strings to merge
+ * @returns Merged scope string with unique permissions
+ *
+ * @example
+ * ```typescript
+ * const scope1 = "account:email?action=read repo:app.bsky.feed.post";
+ * const scope2 = "repo:app.bsky.feed.post blob:image/*";
+ * const merged = mergeScopes([scope1, scope2]);
+ * // Returns: "account:email?action=read repo:app.bsky.feed.post blob:image/*"
+ * ```
+ */
+function mergeScopes(scopes) {
+    const allPermissions = scopes.flatMap(parseScope);
+    const uniquePermissions = [...new Set(allPermissions)];
+    return buildScope(uniquePermissions);
+}
+/**
+ * Remove specific permissions from a scope string.
+ *
+ * @param scope - Space-separated scope string
+ * @param permissionsToRemove - Array of permissions to remove
+ * @returns New scope string without the specified permissions
+ *
+ * @example
+ * ```typescript
+ * const scope = "account:email?action=read repo:app.bsky.feed.post blob:image/*";
+ * const filtered = removePermissions(scope, ["blob:image/*"]);
+ * // Returns: "account:email?action=read repo:app.bsky.feed.post"
+ * ```
+ */
+function removePermissions(scope, permissionsToRemove) {
+    const permissions = parseScope(scope);
+    const filtered = permissions.filter((p) => !permissionsToRemove.includes(p));
+    return buildScope(filtered);
+}
+/**
+ * Validate that all permissions in a scope string are well-formed.
+ *
+ * This checks that each permission matches expected patterns for transitional
+ * or granular permissions. It does NOT validate against the full Zod schemas.
+ *
+ * @param scope - Space-separated scope string
+ * @returns Object with isValid flag and array of invalid permissions
+ *
+ * @example
+ * ```typescript
+ * const scope = "account:email?action=read invalid:permission";
+ * const result = validateScope(scope);
+ * // Returns: { isValid: false, invalidPermissions: ['invalid:permission'] }
+ * ```
+ */
+function validateScope(scope) {
+    const permissions = parseScope(scope);
+    const invalidPermissions = [];
+    // Pattern for valid permission prefixes
+    const validPrefixes = /^(atproto|transition:|account:|repo:|blob:?|rpc:|identity:|include:)/;
+    for (const permission of permissions) {
+        if (!validPrefixes.test(permission)) {
+            invalidPermissions.push(permission);
+        }
+    }
+    return {
+        isValid: invalidPermissions.length === 0,
+        invalidPermissions,
+    };
+}
+
 /**
  * OAuth 2.0 client for AT Protocol authentication with DPoP support.
  *
@@ -657,7 +1641,7 @@ class OAuthClient {
      */
     buildClientMetadata() {
         const clientIdUrl = new URL(this.config.oauth.clientId);
-        return {
+        const metadata = {
             client_id: this.config.oauth.clientId,
             client_name: "ATProto SDK Client",
             client_uri: clientIdUrl.origin,
@@ -671,6 +1655,77 @@ class OAuthClient {
             dpop_bound_access_tokens: true,
             jwks_uri: this.config.oauth.jwksUri,
         };
+        // Validate scope before returning metadata
+        this.validateClientMetadataScope(metadata.scope);
+        return metadata;
+    }
+    /**
+     * Validates the OAuth scope in client metadata and logs warnings/suggestions.
+     *
+     * This method:
+     * 1. Checks if the scope is well-formed using permission utilities
+     * 2. Detects mixing of transitional and granular permissions
+     * 3. Logs warnings for missing `atproto` scope
+     * 4. Suggests migration to granular permissions for transitional scopes
+     *
+     * @param scope - The OAuth scope string to validate
+     * @internal
+     */
+    validateClientMetadataScope(scope) {
+        // Parse the scope into individual permissions
+        const permissions = parseScope(scope);
+        // Validate well-formedness
+        const validation = validateScope(scope);
+        if (!validation.isValid) {
+            this.logger?.error("Invalid OAuth scope detected", {
+                invalidPermissions: validation.invalidPermissions,
+                scope,
+            });
+        }
+        // Check for atproto scope
+        const hasAtproto = permissions.includes(ATPROTO_SCOPE);
+        if (!hasAtproto) {
+            this.logger?.warn("OAuth scope missing 'atproto' - basic API access may be limited", {
+                scope,
+                suggestion: "Add 'atproto' to your scope for basic API access",
+            });
+        }
+        // Detect transitional scopes
+        const transitionalScopes = permissions.filter((p) => p.startsWith("transition:"));
+        const granularScopes = permissions.filter((p) => p.startsWith("account:") ||
+            p.startsWith("repo:") ||
+            p.startsWith("blob") ||
+            p.startsWith("rpc:") ||
+            p.startsWith("identity:") ||
+            p.startsWith("include:"));
+        // Log info about transitional scopes
+        if (transitionalScopes.length > 0) {
+            this.logger?.info("Using transitional OAuth scopes (legacy)", {
+                transitionalScopes,
+                note: "Transitional scopes are supported but granular permissions are recommended",
+            });
+            // Suggest migration to granular permissions
+            if (transitionalScopes.includes("transition:email")) {
+                this.logger?.info("Consider migrating 'transition:email' to granular permissions", {
+                    suggestion: "Use: account:email?action=read",
+                    example: "import { ScopePresets } from '@hypercerts-org/sdk-core'; scope: ScopePresets.EMAIL_READ",
+                });
+            }
+            if (transitionalScopes.includes("transition:generic")) {
+                this.logger?.info("Consider migrating 'transition:generic' to granular permissions", {
+                    suggestion: "Use specific permissions like: repo:* account:repo?action=read",
+                    example: "import { ScopePresets } from '@hypercerts-org/sdk-core'; scope: ScopePresets.FULL_ACCESS",
+                });
+            }
+        }
+        // Warn if mixing transitional and granular
+        if (transitionalScopes.length > 0 && granularScopes.length > 0) {
+            this.logger?.warn("Mixing transitional and granular OAuth scopes", {
+                transitionalScopes,
+                granularScopes,
+                note: "While supported, it's recommended to use either transitional or granular permissions consistently",
+            });
+        }
     }
     /**
      * Creates a fetch handler with timeout support.
@@ -4183,9 +5238,34 @@ const OAuthConfigSchema = zod.z.object({
     redirectUri: zod.z.string().url(),
     /**
      * OAuth scopes to request, space-separated.
-     * Common scopes: "atproto", "transition:generic"
+     *
+     * Can be a string of space-separated permissions or use the permission system:
+     *
+     * @example Using presets
+     * ```typescript
+     * import { ScopePresets } from '@hypercerts-org/sdk-core';
+     * scope: ScopePresets.EMAIL_AND_PROFILE
+     * ```
+     *
+     * @example Building custom scopes
+     * ```typescript
+     * import { PermissionBuilder, buildScope } from '@hypercerts-org/sdk-core';
+     * scope: buildScope(
+     *   new PermissionBuilder()
+     *     .accountEmail('read')
+     *     .repoWrite('app.bsky.feed.post')
+     *     .build()
+     * )
+     * ```
+     *
+     * @example Legacy scopes
+     * ```typescript
+     * scope: "atproto transition:generic"
+     * ```
+     *
+     * @see https://atproto.com/specs/permission for permission details
      */
-    scope: zod.z.string(),
+    scope: zod.z.string().min(1, "OAuth scope is required"),
     /**
      * URL to your public JWKS (JSON Web Key Set) endpoint.
      * Used by the authorization server to verify your client's signatures.
@@ -4477,6 +5557,91 @@ class ATProtoSDK {
         }
         return this.oauthClient.revoke(did.trim());
     }
+    /**
+     * Gets the account email address from the authenticated session.
+     *
+     * This method retrieves the email address associated with the user's account
+     * by calling the `com.atproto.server.getSession` endpoint. The email will only
+     * be returned if the appropriate OAuth scope was granted during authorization.
+     *
+     * Required OAuth scopes:
+     * - **Granular permissions**: `account:email?action=read` or `account:email`
+     * - **Transitional permissions**: `transition:email`
+     *
+     * @param session - An authenticated OAuth session
+     * @returns A Promise resolving to email info, or `null` if permission not granted
+     * @throws {@link ValidationError} if the session is invalid
+     * @throws {@link NetworkError} if the API request fails
+     *
+     * @example Using granular permissions
+     * ```typescript
+     * import { ScopePresets } from '@hypercerts-org/sdk-core';
+     *
+     * // Authorize with email scope
+     * const authUrl = await sdk.authorize("user.bsky.social", {
+     *   scope: ScopePresets.EMAIL_READ
+     * });
+     *
+     * // After callback...
+     * const emailInfo = await sdk.getAccountEmail(session);
+     * if (emailInfo) {
+     *   console.log(`Email: ${emailInfo.email}`);
+     *   console.log(`Confirmed: ${emailInfo.emailConfirmed}`);
+     * } else {
+     *   console.log("Email permission not granted");
+     * }
+     * ```
+     *
+     * @example Using transitional permissions (legacy)
+     * ```typescript
+     * // Authorize with transition:email scope
+     * const authUrl = await sdk.authorize("user.bsky.social", {
+     *   scope: "atproto transition:email"
+     * });
+     *
+     * // After callback...
+     * const emailInfo = await sdk.getAccountEmail(session);
+     * ```
+     */
+    async getAccountEmail(session) {
+        if (!session) {
+            throw new ValidationError("Session is required");
+        }
+        try {
+            // Determine PDS URL from session or config
+            const pdsUrl = this.config.servers?.pds;
+            if (!pdsUrl) {
+                throw new ValidationError("PDS server URL not configured");
+            }
+            // Call com.atproto.server.getSession endpoint using session's fetchHandler
+            // which automatically includes proper authorization with DPoP
+            const response = await session.fetchHandler("/xrpc/com.atproto.server.getSession", {
+                method: "GET",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+            });
+            if (!response.ok) {
+                throw new NetworkError(`Failed to get session info: ${response.status} ${response.statusText}`);
+            }
+            const data = (await response.json());
+            // Return null if email not present (permission not granted)
+            if (!data.email) {
+                return null;
+            }
+            return {
+                email: data.email,
+                emailConfirmed: data.emailConfirmed ?? false,
+            };
+        }
+        catch (error) {
+            this.logger?.error("Failed to get account email", { error });
+            if (error instanceof ValidationError || error instanceof NetworkError) {
+                throw error;
+            }
+            throw new NetworkError(`Failed to get account email: ${error instanceof Error ? error.message : String(error)}`, error);
+        }
+    }
     /**
      * Creates a repository instance for data operations.
      *
@@ -4791,24 +5956,50 @@ Object.defineProperty(exports, "validate", {
     enumerable: true,
     get: function () { return lexicon.validate; }
 });
+exports.ATPROTO_SCOPE = ATPROTO_SCOPE;
 exports.ATProtoSDK = ATProtoSDK;
 exports.ATProtoSDKConfigSchema = ATProtoSDKConfigSchema;
 exports.ATProtoSDKError = ATProtoSDKError;
+exports.AccountActionSchema = AccountActionSchema;
+exports.AccountAttrSchema = AccountAttrSchema;
+exports.AccountPermissionSchema = AccountPermissionSchema;
 exports.AuthenticationError = AuthenticationError;
+exports.BlobPermissionSchema = BlobPermissionSchema;
 exports.CollaboratorPermissionsSchema = CollaboratorPermissionsSchema;
 exports.CollaboratorSchema = CollaboratorSchema;
 exports.ConfigurableAgent = ConfigurableAgent;
+exports.IdentityAttrSchema = IdentityAttrSchema;
+exports.IdentityPermissionSchema = IdentityPermissionSchema;
 exports.InMemorySessionStore = InMemorySessionStore;
 exports.InMemoryStateStore = InMemoryStateStore;
+exports.IncludePermissionSchema = IncludePermissionSchema;
 exports.LexiconRegistry = LexiconRegistry;
+exports.MimeTypeSchema = MimeTypeSchema;
 exports.NetworkError = NetworkError;
+exports.NsidSchema = NsidSchema;
 exports.OAuthConfigSchema = OAuthConfigSchema;
 exports.OrganizationSchema = OrganizationSchema;
+exports.PermissionBuilder = PermissionBuilder;
+exports.PermissionSchema = PermissionSchema;
+exports.RepoActionSchema = RepoActionSchema;
+exports.RepoPermissionSchema = RepoPermissionSchema;
 exports.Repository = Repository;
+exports.RpcPermissionSchema = RpcPermissionSchema;
 exports.SDSRequiredError = SDSRequiredError;
+exports.ScopePresets = ScopePresets;
 exports.ServerConfigSchema = ServerConfigSchema;
 exports.SessionExpiredError = SessionExpiredError;
+exports.TRANSITION_SCOPES = TRANSITION_SCOPES;
 exports.TimeoutConfigSchema = TimeoutConfigSchema;
+exports.TransitionScopeSchema = TransitionScopeSchema;
 exports.ValidationError = ValidationError;
+exports.buildScope = buildScope;
 exports.createATProtoSDK = createATProtoSDK;
+exports.hasAllPermissions = hasAllPermissions;
+exports.hasAnyPermission = hasAnyPermission;
+exports.hasPermission = hasPermission;
+exports.mergeScopes = mergeScopes;
+exports.parseScope = parseScope;
+exports.removePermissions = removePermissions;
+exports.validateScope = validateScope;
 //# sourceMappingURL=index.cjs.map