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

package/dist/index.mjs

@@ -1,10 +1,10 @@
 import { JoseKey, NodeOAuthClient } from '@atproto/oauth-client-node';
-import { Lexicons } from '@atproto/lexicon';
-import { HYPERCERT_COLLECTIONS, HYPERCERT_LEXICONS } from '@hypercerts-org/lexicon';
-export { AppCertifiedLocation, ComAtprotoRepoStrongRef, HYPERCERT_COLLECTIONS, HYPERCERT_LEXICONS, OrgHypercertsClaim, OrgHypercertsClaimContribution, OrgHypercertsClaimEvaluation, OrgHypercertsClaimEvidence, OrgHypercertsClaimMeasurement, OrgHypercertsClaimRights, OrgHypercertsCollection, ids, lexicons, schemaDict, schemas, validate } from '@hypercerts-org/lexicon';
+import { z } from 'zod';
 import { Agent } from '@atproto/api';
 import { EventEmitter } from 'eventemitter3';
-import { z } from 'zod';
+import { CERTIFIED_DEFS_LEXICON_JSON, LOCATION_LEXICON_JSON, STRONGREF_LEXICON_JSON, HYPERCERTS_DEFS_LEXICON_JSON, ACTIVITY_LEXICON_JSON, COLLECTION_LEXICON_JSON, CONTRIBUTION_LEXICON_JSON, EVALUATION_LEXICON_JSON, EVIDENCE_LEXICON_JSON, MEASUREMENT_LEXICON_JSON, RIGHTS_LEXICON_JSON, PROJECT_LEXICON_JSON, BADGE_AWARD_LEXICON_JSON, BADGE_DEFINITION_LEXICON_JSON, BADGE_RESPONSE_LEXICON_JSON, FUNDING_RECEIPT_LEXICON_JSON, FUNDING_RECEIPT_NSID, BADGE_RESPONSE_NSID, BADGE_DEFINITION_NSID, BADGE_AWARD_NSID, PROJECT_NSID, COLLECTION_NSID, EVIDENCE_NSID, EVALUATION_NSID, MEASUREMENT_NSID, CONTRIBUTION_NSID, LOCATION_NSID, RIGHTS_NSID, ACTIVITY_NSID, validate } from '@hypercerts-org/lexicon';
+export { AppCertifiedBadgeAward, AppCertifiedBadgeDefinition, AppCertifiedBadgeResponse, AppCertifiedLocation, ComAtprotoRepoStrongRef, HYPERCERTS_NSIDS, HYPERCERTS_NSIDS_BY_TYPE, HYPERCERTS_SCHEMAS, HYPERCERTS_SCHEMA_DICT, OrgHypercertsClaimActivity, OrgHypercertsClaimCollection, OrgHypercertsClaimContribution, OrgHypercertsClaimEvaluation, OrgHypercertsClaimEvidence, OrgHypercertsClaimMeasurement, OrgHypercertsClaimProject, OrgHypercertsClaimRights, OrgHypercertsFundingReceipt, validate } from '@hypercerts-org/lexicon';
+import '@atproto/lexicon';
 
 /**
  * Base error class for all SDK errors.
@@ -523,160 +523,1215 @@ class InMemoryStateStore {
 }
 
 /**
- * OAuth 2.0 client for AT Protocol authentication with DPoP support.
+ * OAuth Scopes and Granular Permissions
  *
- * This class wraps the `@atproto/oauth-client-node` library to provide
- * OAuth 2.0 authentication with the following features:
+ * 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.
  *
- * - **DPoP (Demonstrating Proof of Possession)**: Binds tokens to cryptographic keys
- *   to prevent token theft and replay attacks
- * - **PKCE (Proof Key for Code Exchange)**: Protects against authorization code interception
- * - **Automatic Token Refresh**: Transparently refreshes expired access tokens
- * - **Session Persistence**: Stores sessions in configurable storage backends
+ * @see https://atproto.com/specs/oauth
+ * @see https://atproto.com/specs/permission
  *
- * @remarks
- * This class is typically used internally by {@link ATProtoSDK}. Direct usage
- * is only needed for advanced scenarios.
+ * @module auth/permissions
+ */
+/**
+ * Base OAuth scope - required for all sessions
  *
- * The client uses lazy initialization - the underlying `NodeOAuthClient` is
- * created asynchronously on first use. This allows the constructor to return
- * synchronously while deferring async key parsing.
+ * @constant
+ */
+const ATPROTO_SCOPE = "atproto";
+/**
+ * Transitional OAuth scopes for legacy compatibility.
  *
- * @example Direct usage (advanced)
+ * 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
- * import { OAuthClient } from "@hypercerts-org/sdk";
+ * TransitionScopeSchema.parse('transition:email'); // Valid
+ * TransitionScopeSchema.parse('invalid'); // Throws ZodError
+ * ```
+ */
+const TransitionScopeSchema = z
+    .enum(["transition:generic", "transition:chat.bsky", "transition:email"])
+    .describe("Legacy transitional OAuth scopes");
+/**
+ * Zod schema for account permission attributes.
  *
- * const client = new OAuthClient({
- *   oauth: {
- *     clientId: "https://my-app.com/client-metadata.json",
- *     redirectUri: "https://my-app.com/callback",
- *     scope: "atproto transition:generic",
- *     jwksUri: "https://my-app.com/.well-known/jwks.json",
- *     jwkPrivate: process.env.JWK_PRIVATE_KEY!,
- *   },
- *   servers: { pds: "https://bsky.social" },
- * });
+ * Account attributes specify what aspect of the account is being accessed.
+ */
+const AccountAttrSchema = z.enum(["email", "repo"]);
+/**
+ * Zod schema for account actions.
  *
- * // Start authorization
- * const authUrl = await client.authorize("user.bsky.social");
+ * Account actions specify the level of access (read-only or management).
+ */
+const AccountActionSchema = z.enum(["read", "manage"]);
+/**
+ * Zod schema for repository actions.
  *
- * // Handle callback
- * const session = await client.callback(new URLSearchParams(callbackUrl.search));
+ * Repository actions specify what operations can be performed on records.
+ */
+const RepoActionSchema = z.enum(["create", "update", "delete"]);
+/**
+ * Zod schema for identity permission attributes.
+ *
+ * Identity attributes specify what identity information can be managed.
+ */
+const IdentityAttrSchema = 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 = 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).
  *
- * @see {@link ATProtoSDK} for the recommended high-level API
- * @see https://atproto.com/specs/oauth for AT Protocol OAuth specification
+ * 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
+ * ```
  */
-class OAuthClient {
+const NsidSchema = 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 = z
+    .object({
+    type: 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 = z
+    .object({
+    type: z.literal("repo"),
+    collection: NsidSchema.or(z.literal("*")),
+    actions: 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 = z
+    .object({
+    type: z.literal("blob"),
+    mimeTypes: 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 = z
+    .object({
+    type: z.literal("rpc"),
+    lexicon: NsidSchema.or(z.literal("*")),
+    aud: z.string().min(1, "Audience is required"),
+    inheritAud: 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 = z
+    .object({
+    type: 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 = z
+    .object({
+    type: z.literal("include"),
+    nsid: NsidSchema,
+    aud: 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 = 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 = [];
+    }
     /**
-     * Creates a new OAuth client.
+     * Add a transitional scope.
      *
-     * @param config - SDK configuration including OAuth credentials and server URLs
-     * @throws {@link AuthenticationError} if the JWK private key is not valid JSON
+     * @param scope - The transitional scope name ('email', 'generic', or 'chat.bsky')
+     * @returns This builder for chaining
      *
-     * @remarks
-     * The constructor validates the JWK format synchronously but defers
-     * the actual client initialization to the first API call.
+     * @example
+     * ```typescript
+     * builder.transition('email').transition('generic');
+     * ```
      */
-    constructor(config) {
-        /** The underlying NodeOAuthClient instance (lazily initialized) */
-        this.client = null;
-        this.config = config;
-        this.logger = config.logger;
-        // Validate JWK format synchronously (before async initialization)
-        try {
-            JSON.parse(config.oauth.jwkPrivate);
-        }
-        catch (error) {
-            throw new AuthenticationError("Failed to parse JWK private key. Ensure it is valid JSON.", error);
-        }
-        // Initialize client lazily (async initialization)
-        this.clientPromise = this.initializeClient();
+    transition(scope) {
+        const fullScope = `transition:${scope}`;
+        const validated = TransitionScopeSchema.parse(fullScope);
+        this.permissions.push(validated);
+        return this;
     }
     /**
-     * Initializes the NodeOAuthClient asynchronously.
+     * Add an account permission.
      *
-     * This method is called lazily on first use. It:
-     * 1. Parses the JWK private key(s)
-     * 2. Builds OAuth client metadata
-     * 3. Creates the underlying NodeOAuthClient
+     * @param attr - The account attribute ('email' or 'repo')
+     * @param action - Optional action ('read' or 'manage')
+     * @returns This builder for chaining
      *
-     * @returns Promise resolving to the initialized client
-     * @internal
+     * @example
+     * ```typescript
+     * builder.accountEmail('read').accountRepo('manage');
+     * ```
      */
-    async initializeClient() {
-        if (this.client) {
-            return this.client;
-        }
-        // Parse JWK private key (already validated in constructor)
-        const privateJWK = JSON.parse(this.config.oauth.jwkPrivate);
-        // Build client metadata
-        const clientMetadata = this.buildClientMetadata();
-        // Convert JWK keys to JoseKey instances (await here)
-        const keyset = await Promise.all(privateJWK.keys.map((key) => JoseKey.fromImportable(key, key.kid)));
-        // Create fetch with timeout
-        const fetchWithTimeout = this.createFetchWithTimeout(this.config.timeouts?.pdsMetadata ?? 30000);
-        // Use provided stores or fall back to in-memory implementations
-        const stateStore = this.config.storage?.stateStore ?? new InMemoryStateStore();
-        const sessionStore = this.config.storage?.sessionStore ?? new InMemorySessionStore();
-        this.client = new NodeOAuthClient({
-            clientMetadata,
-            keyset,
-            stateStore: this.createStateStoreAdapter(stateStore),
-            sessionStore: this.createSessionStoreAdapter(sessionStore),
-            handleResolver: this.config.servers?.pds,
-            fetch: this.config.fetch ?? fetchWithTimeout,
+    account(attr, action) {
+        const permission = AccountPermissionSchema.parse({
+            type: "account",
+            attr,
+            action,
         });
-        return this.client;
+        this.permissions.push(permission);
+        return this;
     }
     /**
-     * Gets the OAuth client instance, initializing if needed.
+     * Convenience method for account:email permission.
      *
-     * @returns Promise resolving to the initialized client
-     * @internal
+     * @param action - Optional action ('read' or 'manage')
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.accountEmail('read');
+     * ```
      */
-    async getClient() {
-        return this.clientPromise;
+    accountEmail(action) {
+        return this.account("email", action);
     }
     /**
-     * Builds OAuth client metadata from configuration.
-     *
-     * The metadata describes your application to the authorization server
-     * and must match what's published at your `clientId` URL.
+     * Convenience method for account:repo permission.
      *
-     * @returns OAuth client metadata object
-     * @internal
+     * @param action - Optional action ('read' or 'manage')
+     * @returns This builder for chaining
      *
-     * @remarks
-     * Key metadata fields:
-     * - `client_id`: URL to your client metadata JSON
-     * - `redirect_uris`: Where to redirect after auth (must match config)
-     * - `dpop_bound_access_tokens`: Always true for AT Protocol
-     * - `token_endpoint_auth_method`: Uses private_key_jwt for security
+     * @example
+     * ```typescript
+     * builder.accountRepo('manage');
+     * ```
      */
-    buildClientMetadata() {
-        const clientIdUrl = new URL(this.config.oauth.clientId);
-        return {
-            client_id: this.config.oauth.clientId,
-            client_name: "ATProto SDK Client",
-            client_uri: clientIdUrl.origin,
-            redirect_uris: [this.config.oauth.redirectUri],
-            scope: this.config.oauth.scope,
-            grant_types: ["authorization_code", "refresh_token"],
-            response_types: ["code"],
-            application_type: "web",
-            token_endpoint_auth_method: "private_key_jwt",
-            token_endpoint_auth_signing_alg: "ES256",
-            dpop_bound_access_tokens: true,
-            jwks_uri: this.config.oauth.jwksUri,
-        };
+    accountRepo(action) {
+        return this.account("repo", action);
     }
     /**
-     * Creates a fetch handler with timeout support.
+     * Add a repository permission.
      *
-     * @param timeoutMs - Request timeout in milliseconds
-     * @returns A fetch function that aborts after the timeout
-     * @internal
+     * @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.
+ *
+ * This class wraps the `@atproto/oauth-client-node` library to provide
+ * OAuth 2.0 authentication with the following features:
+ *
+ * - **DPoP (Demonstrating Proof of Possession)**: Binds tokens to cryptographic keys
+ *   to prevent token theft and replay attacks
+ * - **PKCE (Proof Key for Code Exchange)**: Protects against authorization code interception
+ * - **Automatic Token Refresh**: Transparently refreshes expired access tokens
+ * - **Session Persistence**: Stores sessions in configurable storage backends
+ *
+ * @remarks
+ * This class is typically used internally by {@link ATProtoSDK}. Direct usage
+ * is only needed for advanced scenarios.
+ *
+ * The client uses lazy initialization - the underlying `NodeOAuthClient` is
+ * created asynchronously on first use. This allows the constructor to return
+ * synchronously while deferring async key parsing.
+ *
+ * @example Direct usage (advanced)
+ * ```typescript
+ * import { OAuthClient } from "@hypercerts-org/sdk";
+ *
+ * const client = new OAuthClient({
+ *   oauth: {
+ *     clientId: "https://my-app.com/client-metadata.json",
+ *     redirectUri: "https://my-app.com/callback",
+ *     scope: "atproto transition:generic",
+ *     jwksUri: "https://my-app.com/.well-known/jwks.json",
+ *     jwkPrivate: process.env.JWK_PRIVATE_KEY!,
+ *   },
+ *   servers: { pds: "https://bsky.social" },
+ * });
+ *
+ * // Start authorization
+ * const authUrl = await client.authorize("user.bsky.social");
+ *
+ * // Handle callback
+ * const session = await client.callback(new URLSearchParams(callbackUrl.search));
+ * ```
+ *
+ * @see {@link ATProtoSDK} for the recommended high-level API
+ * @see https://atproto.com/specs/oauth for AT Protocol OAuth specification
+ */
+class OAuthClient {
+    /**
+     * Creates a new OAuth client.
+     *
+     * @param config - SDK configuration including OAuth credentials and server URLs
+     * @throws {@link AuthenticationError} if the JWK private key is not valid JSON
+     *
+     * @remarks
+     * The constructor validates the JWK format synchronously but defers
+     * the actual client initialization to the first API call.
+     */
+    constructor(config) {
+        /** The underlying NodeOAuthClient instance (lazily initialized) */
+        this.client = null;
+        this.config = config;
+        this.logger = config.logger;
+        // Validate JWK format synchronously (before async initialization)
+        try {
+            JSON.parse(config.oauth.jwkPrivate);
+        }
+        catch (error) {
+            throw new AuthenticationError("Failed to parse JWK private key. Ensure it is valid JSON.", error);
+        }
+        // Initialize client lazily (async initialization)
+        this.clientPromise = this.initializeClient();
+    }
+    /**
+     * Initializes the NodeOAuthClient asynchronously.
+     *
+     * This method is called lazily on first use. It:
+     * 1. Parses the JWK private key(s)
+     * 2. Builds OAuth client metadata
+     * 3. Creates the underlying NodeOAuthClient
+     *
+     * @returns Promise resolving to the initialized client
+     * @internal
+     */
+    async initializeClient() {
+        if (this.client) {
+            return this.client;
+        }
+        // Parse JWK private key (already validated in constructor)
+        const privateJWK = JSON.parse(this.config.oauth.jwkPrivate);
+        // Build client metadata
+        const clientMetadata = this.buildClientMetadata();
+        // Convert JWK keys to JoseKey instances (await here)
+        const keyset = await Promise.all(privateJWK.keys.map((key) => JoseKey.fromImportable(key, key.kid)));
+        // Create fetch with timeout
+        const fetchWithTimeout = this.createFetchWithTimeout(this.config.timeouts?.pdsMetadata ?? 30000);
+        // Use provided stores or fall back to in-memory implementations
+        const stateStore = this.config.storage?.stateStore ?? new InMemoryStateStore();
+        const sessionStore = this.config.storage?.sessionStore ?? new InMemorySessionStore();
+        this.client = new NodeOAuthClient({
+            clientMetadata,
+            keyset,
+            stateStore: this.createStateStoreAdapter(stateStore),
+            sessionStore: this.createSessionStoreAdapter(sessionStore),
+            handleResolver: this.config.servers?.pds,
+            fetch: this.config.fetch ?? fetchWithTimeout,
+        });
+        return this.client;
+    }
+    /**
+     * Gets the OAuth client instance, initializing if needed.
+     *
+     * @returns Promise resolving to the initialized client
+     * @internal
+     */
+    async getClient() {
+        return this.clientPromise;
+    }
+    /**
+     * Builds OAuth client metadata from configuration.
+     *
+     * The metadata describes your application to the authorization server
+     * and must match what's published at your `clientId` URL.
+     *
+     * @returns OAuth client metadata object
+     * @internal
+     *
+     * @remarks
+     * Key metadata fields:
+     * - `client_id`: URL to your client metadata JSON
+     * - `redirect_uris`: Where to redirect after auth (must match config)
+     * - `dpop_bound_access_tokens`: Always true for AT Protocol
+     * - `token_endpoint_auth_method`: Uses private_key_jwt for security
+     */
+    buildClientMetadata() {
+        const clientIdUrl = new URL(this.config.oauth.clientId);
+        const metadata = {
+            client_id: this.config.oauth.clientId,
+            client_name: "ATProto SDK Client",
+            client_uri: clientIdUrl.origin,
+            redirect_uris: [this.config.oauth.redirectUri],
+            scope: this.config.oauth.scope,
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            application_type: "web",
+            token_endpoint_auth_method: "private_key_jwt",
+            token_endpoint_auth_signing_alg: "ES256",
+            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.
+     *
+     * @param timeoutMs - Request timeout in milliseconds
+     * @returns A fetch function that aborts after the timeout
+     * @internal
      */
     createFetchWithTimeout(timeoutMs) {
         return async (input, init) => {
@@ -918,330 +1973,33 @@ class OAuthClient {
      *
      * @example
      * ```typescript
-     * // Log out endpoint
-     * app.post("/logout", async (req, res) => {
-     *   const userDid = req.session.userDid;
-     *   if (userDid) {
-     *     await client.revoke(userDid);
-     *     delete req.session.userDid;
-     *   }
-     *   res.redirect("/");
-     * });
-     * ```
-     *
-     * @remarks
-     * Even if revocation fails on the server, the local session is
-     * removed. The error is thrown to inform you that remote revocation
-     * may not have succeeded.
-     */
-    async revoke(did) {
-        try {
-            this.logger?.debug("Revoking session", { did });
-            const client = await this.getClient();
-            await client.revoke(did);
-            this.logger?.info("Session revoked", { did });
-        }
-        catch (error) {
-            this.logger?.error("Failed to revoke session", { did, error });
-            throw new AuthenticationError(`Failed to revoke session: ${error instanceof Error ? error.message : String(error)}`, error);
-        }
-    }
-}
-
-/**
- * Registry for managing and validating AT Protocol lexicon schemas.
- *
- * Lexicons are schema definitions that describe the structure of records
- * in the AT Protocol. This registry allows you to:
- *
- * - Register custom lexicons for your application's record types
- * - Validate records against their lexicon schemas
- * - Extend the AT Protocol Agent with custom lexicon support
- *
- * @remarks
- * The SDK automatically registers hypercert lexicons when creating a Repository.
- * You only need to use this class directly if you're working with custom
- * record types.
- *
- * **Lexicon IDs** follow the NSID (Namespaced Identifier) format:
- * `{authority}.{name}` (e.g., `org.hypercerts.hypercert`)
- *
- * @example Registering custom lexicons
- * ```typescript
- * const registry = sdk.getLexiconRegistry();
- *
- * // Register a single lexicon
- * registry.register({
- *   lexicon: 1,
- *   id: "org.example.myRecord",
- *   defs: {
- *     main: {
- *       type: "record",
- *       key: "tid",
- *       record: {
- *         type: "object",
- *         required: ["title", "createdAt"],
- *         properties: {
- *           title: { type: "string" },
- *           description: { type: "string" },
- *           createdAt: { type: "string", format: "datetime" },
- *         },
- *       },
- *     },
- *   },
- * });
- *
- * // Register multiple lexicons at once
- * registry.registerMany([lexicon1, lexicon2, lexicon3]);
- * ```
- *
- * @example Validating records
- * ```typescript
- * const result = registry.validate("org.example.myRecord", {
- *   title: "Test",
- *   createdAt: new Date().toISOString(),
- * });
- *
- * if (!result.valid) {
- *   console.error(`Validation failed: ${result.error}`);
- * }
- * ```
- *
- * @see https://atproto.com/specs/lexicon for the Lexicon specification
- */
-class LexiconRegistry {
-    /**
-     * Creates a new LexiconRegistry.
-     *
-     * The registry starts empty. Use {@link register} or {@link registerMany}
-     * to add lexicons.
-     */
-    constructor() {
-        /** Map of lexicon ID to lexicon document */
-        this.lexicons = new Map();
-        this.lexiconsCollection = new Lexicons();
-    }
-    /**
-     * Registers a single lexicon schema.
-     *
-     * @param lexicon - The lexicon document to register
-     * @throws {@link ValidationError} if the lexicon doesn't have an `id` field
-     *
-     * @remarks
-     * If a lexicon with the same ID is already registered, it will be
-     * replaced with the new definition. This is useful for testing but
-     * should generally be avoided in production.
-     *
-     * @example
-     * ```typescript
-     * registry.register({
-     *   lexicon: 1,
-     *   id: "org.example.post",
-     *   defs: {
-     *     main: {
-     *       type: "record",
-     *       key: "tid",
-     *       record: {
-     *         type: "object",
-     *         required: ["text", "createdAt"],
-     *         properties: {
-     *           text: { type: "string", maxLength: 300 },
-     *           createdAt: { type: "string", format: "datetime" },
-     *         },
-     *       },
-     *     },
-     *   },
-     * });
-     * ```
-     */
-    register(lexicon) {
-        if (!lexicon.id) {
-            throw new ValidationError("Lexicon must have an 'id' field");
-        }
-        // Remove existing lexicon if present (to allow overwriting)
-        if (this.lexicons.has(lexicon.id)) {
-            // Lexicons collection doesn't support removal, so we create a new one
-            // This is a limitation - in practice, lexicons shouldn't be overwritten
-            // But we allow it for testing and flexibility
-            const existingLexicon = this.lexicons.get(lexicon.id);
-            if (existingLexicon) {
-                // Try to remove from collection (may fail if not supported)
-                try {
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                    this.lexiconsCollection.remove?.(lexicon.id);
-                }
-                catch {
-                    // If removal fails, create a new collection
-                    this.lexiconsCollection = new Lexicons();
-                    // Re-register all other lexicons
-                    for (const [id, lex] of this.lexicons.entries()) {
-                        if (id !== lexicon.id) {
-                            this.lexiconsCollection.add(lex);
-                        }
-                    }
-                }
-            }
-        }
-        this.lexicons.set(lexicon.id, lexicon);
-        this.lexiconsCollection.add(lexicon);
-    }
-    /**
-     * Registers multiple lexicons at once.
-     *
-     * @param lexicons - Array of lexicon documents to register
-     *
-     * @example
-     * ```typescript
-     * import { HYPERCERT_LEXICONS } from "@hypercerts-org/sdk/lexicons";
-     *
-     * registry.registerMany(HYPERCERT_LEXICONS);
-     * ```
-     */
-    registerMany(lexicons) {
-        for (const lexicon of lexicons) {
-            this.register(lexicon);
-        }
-    }
-    /**
-     * Gets a lexicon document by ID.
-     *
-     * @param id - The lexicon NSID (e.g., "org.hypercerts.hypercert")
-     * @returns The lexicon document, or `undefined` if not registered
-     *
-     * @example
-     * ```typescript
-     * const lexicon = registry.get("org.hypercerts.hypercert");
-     * if (lexicon) {
-     *   console.log(`Found lexicon: ${lexicon.id}`);
-     * }
-     * ```
-     */
-    get(id) {
-        return this.lexicons.get(id);
-    }
-    /**
-     * Validates a record against a collection's lexicon schema.
-     *
-     * @param collection - The collection NSID (same as lexicon ID)
-     * @param record - The record data to validate
-     * @returns Validation result with `valid` boolean and optional `error` message
-     *
-     * @remarks
-     * - If no lexicon is registered for the collection, validation passes
-     *   (we can't validate against unknown schemas)
-     * - Validation checks required fields and type constraints defined
-     *   in the lexicon schema
-     *
-     * @example
-     * ```typescript
-     * const result = registry.validate("org.hypercerts.hypercert", {
-     *   title: "My Hypercert",
-     *   description: "Description...",
-     *   // ... other fields
-     * });
-     *
-     * if (!result.valid) {
-     *   throw new Error(`Invalid record: ${result.error}`);
-     * }
-     * ```
-     */
-    validate(collection, record) {
-        // Check if we have a lexicon registered for this collection
-        // Collection format is typically "namespace.collection" (e.g., "app.bsky.feed.post")
-        // Lexicon ID format is the same
-        const lexiconId = collection;
-        const lexicon = this.lexicons.get(lexiconId);
-        if (!lexicon) {
-            // No lexicon registered - validation passes (can't validate unknown schemas)
-            return { valid: true };
-        }
-        // Check required fields if the lexicon defines them
-        const recordDef = lexicon.defs?.record;
-        if (recordDef && typeof recordDef === "object" && "record" in recordDef) {
-            const recordSchema = recordDef.record;
-            if (typeof recordSchema === "object" && "required" in recordSchema && Array.isArray(recordSchema.required)) {
-                const recordObj = record;
-                for (const requiredField of recordSchema.required) {
-                    if (typeof requiredField === "string" && !(requiredField in recordObj)) {
-                        return {
-                            valid: false,
-                            error: `Missing required field: ${requiredField}`,
-                        };
-                    }
-                }
-            }
-        }
-        try {
-            this.lexiconsCollection.assertValidRecord(collection, record);
-            return { valid: true };
-        }
-        catch (error) {
-            // If error indicates lexicon not found, treat as validation pass
-            // (the lexicon might exist in Agent's collection but not ours)
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            if (errorMessage.includes("not found") || errorMessage.includes("Lexicon not found")) {
-                return { valid: true };
-            }
-            return {
-                valid: false,
-                error: errorMessage,
-            };
-        }
-    }
-    /**
-     * Adds all registered lexicons to an AT Protocol Agent instance.
-     *
-     * This allows the Agent to understand custom lexicon types when making
-     * API requests.
-     *
-     * @param agent - The Agent instance to extend
-     *
-     * @remarks
-     * This is called automatically when creating a Repository. You typically
-     * don't need to call this directly unless you're using the Agent
-     * independently.
-     *
-     * @internal
-     */
-    addToAgent(agent) {
-        // Access the internal lexicons collection and merge our lexicons
-        // The Agent's lex property is a Lexicons instance
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const agentLex = agent.lex;
-        // Add each registered lexicon to the agent
-        for (const lexicon of this.lexicons.values()) {
-            agentLex.add(lexicon);
-        }
-    }
-    /**
-     * Gets all registered lexicon IDs.
-     *
-     * @returns Array of lexicon NSIDs
-     *
-     * @example
-     * ```typescript
-     * const ids = registry.getRegisteredIds();
-     * console.log(`Registered lexicons: ${ids.join(", ")}`);
-     * ```
-     */
-    getRegisteredIds() {
-        return Array.from(this.lexicons.keys());
-    }
-    /**
-     * Checks if a lexicon is registered.
-     *
-     * @param id - The lexicon NSID to check
-     * @returns `true` if the lexicon is registered
-     *
-     * @example
-     * ```typescript
-     * if (registry.has("org.hypercerts.hypercert")) {
-     *   // Hypercert lexicon is available
-     * }
+     * // Log out endpoint
+     * app.post("/logout", async (req, res) => {
+     *   const userDid = req.session.userDid;
+     *   if (userDid) {
+     *     await client.revoke(userDid);
+     *     delete req.session.userDid;
+     *   }
+     *   res.redirect("/");
+     * });
      * ```
+     *
+     * @remarks
+     * Even if revocation fails on the server, the local session is
+     * removed. The error is thrown to inform you that remote revocation
+     * may not have succeeded.
      */
-    has(id) {
-        return this.lexicons.has(id);
+    async revoke(did) {
+        try {
+            this.logger?.debug("Revoking session", { did });
+            const client = await this.getClient();
+            await client.revoke(did);
+            this.logger?.info("Session revoked", { did });
+        }
+        catch (error) {
+            this.logger?.error("Failed to revoke session", { did, error });
+            throw new AuthenticationError(`Failed to revoke session: ${error instanceof Error ? error.message : String(error)}`, error);
+        }
     }
 }
 
@@ -1373,14 +2131,12 @@ class RecordOperationsImpl {
      *
      * @param agent - AT Protocol Agent for making API calls
      * @param repoDid - DID of the repository to operate on
-     * @param lexiconRegistry - Registry for record validation
      *
      * @internal
      */
-    constructor(agent, repoDid, lexiconRegistry) {
+    constructor(agent, repoDid) {
         this.agent = agent;
         this.repoDid = repoDid;
-        this.lexiconRegistry = lexiconRegistry;
     }
     /**
      * Creates a new record in the specified collection.
@@ -1416,10 +2172,6 @@ class RecordOperationsImpl {
      * ```
      */
     async create(params) {
-        const validation = this.lexiconRegistry.validate(params.collection, params.record);
-        if (!validation.valid) {
-            throw new ValidationError(`Invalid record for collection ${params.collection}: ${validation.error}`);
-        }
         try {
             const result = await this.agent.com.atproto.repo.createRecord({
                 repo: this.repoDid,
@@ -1474,10 +2226,6 @@ class RecordOperationsImpl {
      * ```
      */
     async update(params) {
-        const validation = this.lexiconRegistry.validate(params.collection, params.record);
-        if (!validation.valid) {
-            throw new ValidationError(`Invalid record for collection ${params.collection}: ${validation.error}`);
-        }
         try {
             const result = await this.agent.com.atproto.repo.putRecord({
                 repo: this.repoDid,
@@ -2069,6 +2817,148 @@ class ProfileOperationsImpl {
     }
 }
 
+/**
+ * Lexicons entrypoint - Lexicon definitions and registry.
+ *
+ * This sub-entrypoint exports the lexicon registry and hypercert
+ * lexicon constants for working with AT Protocol record schemas.
+ *
+ * @remarks
+ * Import from `@hypercerts-org/sdk/lexicons`:
+ *
+ * ```typescript
+ * import {
+ *   LexiconRegistry,
+ *   HYPERCERT_LEXICONS,
+ *   HYPERCERT_COLLECTIONS,
+ * } from "@hypercerts-org/sdk/lexicons";
+ * ```
+ *
+ * **Exports**:
+ * - {@link LexiconRegistry} - Registry for managing and validating lexicons
+ * - {@link HYPERCERT_LEXICONS} - Array of all hypercert lexicon documents
+ * - {@link HYPERCERT_COLLECTIONS} - Constants for collection NSIDs
+ *
+ * @example Using collection constants
+ * ```typescript
+ * import { HYPERCERT_COLLECTIONS } from "@hypercerts-org/sdk/lexicons";
+ *
+ * // List hypercerts using the correct collection name
+ * const records = await repo.records.list({
+ *   collection: HYPERCERT_COLLECTIONS.RECORD,
+ * });
+ *
+ * // List contributions
+ * const contributions = await repo.records.list({
+ *   collection: HYPERCERT_COLLECTIONS.CONTRIBUTION,
+ * });
+ * ```
+ *
+ * @example Custom lexicon registration
+ * ```typescript
+ * import { LexiconRegistry } from "@hypercerts-org/sdk/lexicons";
+ *
+ * const registry = sdk.getLexiconRegistry();
+ *
+ * // Register custom lexicon
+ * registry.register({
+ *   lexicon: 1,
+ *   id: "org.myapp.customRecord",
+ *   defs: { ... },
+ * });
+ *
+ * // Validate a record
+ * const result = registry.validate("org.myapp.customRecord", record);
+ * if (!result.valid) {
+ *   console.error(result.error);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * All hypercert-related lexicons for registration with AT Protocol Agent.
+ * This array contains all lexicon documents from the published package.
+ */
+const HYPERCERT_LEXICONS = [
+    CERTIFIED_DEFS_LEXICON_JSON,
+    LOCATION_LEXICON_JSON,
+    STRONGREF_LEXICON_JSON,
+    HYPERCERTS_DEFS_LEXICON_JSON,
+    ACTIVITY_LEXICON_JSON,
+    COLLECTION_LEXICON_JSON,
+    CONTRIBUTION_LEXICON_JSON,
+    EVALUATION_LEXICON_JSON,
+    EVIDENCE_LEXICON_JSON,
+    MEASUREMENT_LEXICON_JSON,
+    RIGHTS_LEXICON_JSON,
+    PROJECT_LEXICON_JSON,
+    BADGE_AWARD_LEXICON_JSON,
+    BADGE_DEFINITION_LEXICON_JSON,
+    BADGE_RESPONSE_LEXICON_JSON,
+    FUNDING_RECEIPT_LEXICON_JSON,
+];
+/**
+ * Collection NSIDs (Namespaced Identifiers) for hypercert records.
+ *
+ * Use these constants when performing record operations to ensure
+ * correct collection names.
+ */
+const HYPERCERT_COLLECTIONS = {
+    /**
+     * Main hypercert claim record collection.
+     */
+    CLAIM: ACTIVITY_NSID,
+    /**
+     * Rights record collection.
+     */
+    RIGHTS: RIGHTS_NSID,
+    /**
+     * Location record collection (shared certified lexicon).
+     */
+    LOCATION: LOCATION_NSID,
+    /**
+     * Contribution record collection.
+     */
+    CONTRIBUTION: CONTRIBUTION_NSID,
+    /**
+     * Measurement record collection.
+     */
+    MEASUREMENT: MEASUREMENT_NSID,
+    /**
+     * Evaluation record collection.
+     */
+    EVALUATION: EVALUATION_NSID,
+    /**
+     * Evidence record collection.
+     */
+    EVIDENCE: EVIDENCE_NSID,
+    /**
+     * Collection record collection (groups of hypercerts).
+     */
+    COLLECTION: COLLECTION_NSID,
+    /**
+     * Project record collection.
+     */
+    PROJECT: PROJECT_NSID,
+    /**
+     * Badge award record collection.
+     */
+    BADGE_AWARD: BADGE_AWARD_NSID,
+    /**
+     * Badge definition record collection.
+     */
+    BADGE_DEFINITION: BADGE_DEFINITION_NSID,
+    /**
+     * Badge response record collection.
+     */
+    BADGE_RESPONSE: BADGE_RESPONSE_NSID,
+    /**
+     * Funding receipt record collection.
+     */
+    FUNDING_RECEIPT: FUNDING_RECEIPT_NSID,
+};
+
 /**
  * HypercertOperationsImpl - High-level hypercert operations.
  *
@@ -2132,17 +3022,15 @@ class HypercertOperationsImpl extends EventEmitter {
      * @param agent - AT Protocol Agent for making API calls
      * @param repoDid - DID of the repository to operate on
      * @param _serverUrl - Server URL (reserved for future use)
-     * @param lexiconRegistry - Registry for record validation
      * @param logger - Optional logger for debugging
      *
      * @internal
      */
-    constructor(agent, repoDid, _serverUrl, lexiconRegistry, logger) {
+    constructor(agent, repoDid, _serverUrl, logger) {
         super();
         this.agent = agent;
         this.repoDid = repoDid;
         this._serverUrl = _serverUrl;
-        this.lexiconRegistry = lexiconRegistry;
         this.logger = logger;
     }
     /**
@@ -2162,6 +3050,202 @@ class HypercertOperationsImpl extends EventEmitter {
             }
         }
     }
+    /**
+     * Uploads an image blob and returns a blob reference.
+     *
+     * @param image - Image blob to upload
+     * @param onProgress - Optional progress callback
+     * @returns Promise resolving to blob reference or undefined
+     * @throws {@link NetworkError} if upload fails
+     * @internal
+     */
+    async uploadImageBlob(image, onProgress) {
+        this.emitProgress(onProgress, { name: "uploadImage", status: "start" });
+        try {
+            const arrayBuffer = await image.arrayBuffer();
+            const uint8Array = new Uint8Array(arrayBuffer);
+            const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
+                encoding: image.type || "image/jpeg",
+            });
+            if (uploadResult.success) {
+                const blobRef = {
+                    $type: "blob",
+                    ref: { $link: uploadResult.data.blob.ref.toString() },
+                    mimeType: uploadResult.data.blob.mimeType,
+                    size: uploadResult.data.blob.size,
+                };
+                this.emitProgress(onProgress, {
+                    name: "uploadImage",
+                    status: "success",
+                    data: { size: image.size },
+                });
+                return blobRef;
+            }
+            throw new NetworkError("Image upload succeeded but returned no blob reference");
+        }
+        catch (error) {
+            this.emitProgress(onProgress, { name: "uploadImage", status: "error", error: error });
+            throw new NetworkError(`Failed to upload image: ${error instanceof Error ? error.message : "Unknown"}`, error);
+        }
+    }
+    /**
+     * Creates a rights record for a hypercert.
+     *
+     * @param rights - Rights data
+     * @param createdAt - ISO timestamp for creation
+     * @param onProgress - Optional progress callback
+     * @returns Promise resolving to rights URI and CID
+     * @throws {@link ValidationError} if validation fails
+     * @throws {@link NetworkError} if creation fails
+     * @internal
+     */
+    async createRightsRecord(rights, createdAt, onProgress) {
+        this.emitProgress(onProgress, { name: "createRights", status: "start" });
+        const rightsRecord = {
+            $type: HYPERCERT_COLLECTIONS.RIGHTS,
+            rightsName: rights.name,
+            rightsType: rights.type,
+            rightsDescription: rights.description,
+            createdAt,
+        };
+        const rightsValidation = validate(rightsRecord, HYPERCERT_COLLECTIONS.RIGHTS, "main", false);
+        if (!rightsValidation.success) {
+            throw new ValidationError(`Invalid rights record: ${rightsValidation.error?.message}`);
+        }
+        const rightsResult = await this.agent.com.atproto.repo.createRecord({
+            repo: this.repoDid,
+            collection: HYPERCERT_COLLECTIONS.RIGHTS,
+            record: rightsRecord,
+        });
+        if (!rightsResult.success) {
+            throw new NetworkError("Failed to create rights record");
+        }
+        const uri = rightsResult.data.uri;
+        const cid = rightsResult.data.cid;
+        this.emit("rightsCreated", { uri, cid });
+        this.emitProgress(onProgress, {
+            name: "createRights",
+            status: "success",
+            data: { uri },
+        });
+        return { uri, cid };
+    }
+    /**
+     * Creates the main hypercert record.
+     *
+     * @param params - Hypercert creation parameters
+     * @param rightsUri - URI of the associated rights record
+     * @param rightsCid - CID of the associated rights record
+     * @param imageBlobRef - Optional image blob reference
+     * @param createdAt - ISO timestamp for creation
+     * @param onProgress - Optional progress callback
+     * @returns Promise resolving to hypercert URI and CID
+     * @throws {@link ValidationError} if validation fails
+     * @throws {@link NetworkError} if creation fails
+     * @internal
+     */
+    async createHypercertRecord(params, rightsUri, rightsCid, imageBlobRef, createdAt, onProgress) {
+        this.emitProgress(onProgress, { name: "createHypercert", status: "start" });
+        const hypercertRecord = {
+            $type: HYPERCERT_COLLECTIONS.CLAIM,
+            title: params.title,
+            shortDescription: params.shortDescription,
+            description: params.description,
+            workScope: params.workScope,
+            workTimeFrameFrom: params.workTimeFrameFrom,
+            workTimeFrameTo: params.workTimeFrameTo,
+            rights: { uri: rightsUri, cid: rightsCid },
+            createdAt,
+        };
+        if (imageBlobRef) {
+            hypercertRecord.image = imageBlobRef;
+        }
+        if (params.evidence && params.evidence.length > 0) {
+            hypercertRecord.evidence = params.evidence;
+        }
+        const hypercertValidation = validate(hypercertRecord, HYPERCERT_COLLECTIONS.CLAIM, "#main", false);
+        if (!hypercertValidation.success) {
+            throw new ValidationError(`Invalid hypercert record: ${hypercertValidation.error?.message}`);
+        }
+        const hypercertResult = await this.agent.com.atproto.repo.createRecord({
+            repo: this.repoDid,
+            collection: HYPERCERT_COLLECTIONS.CLAIM,
+            record: hypercertRecord,
+        });
+        if (!hypercertResult.success) {
+            throw new NetworkError("Failed to create hypercert record");
+        }
+        const uri = hypercertResult.data.uri;
+        const cid = hypercertResult.data.cid;
+        this.emit("recordCreated", { uri, cid });
+        this.emitProgress(onProgress, {
+            name: "createHypercert",
+            status: "success",
+            data: { uri },
+        });
+        return { uri, cid };
+    }
+    /**
+     * Attaches a location to a hypercert with progress tracking.
+     *
+     * @param hypercertUri - URI of the hypercert
+     * @param location - Location data
+     * @param onProgress - Optional progress callback
+     * @returns Promise resolving to location URI
+     * @internal
+     */
+    async attachLocationWithProgress(hypercertUri, location, onProgress) {
+        this.emitProgress(onProgress, { name: "attachLocation", status: "start" });
+        try {
+            const locationResult = await this.attachLocation(hypercertUri, location);
+            this.emitProgress(onProgress, {
+                name: "attachLocation",
+                status: "success",
+                data: { uri: locationResult.uri },
+            });
+            return locationResult.uri;
+        }
+        catch (error) {
+            this.emitProgress(onProgress, { name: "attachLocation", status: "error", error: error });
+            this.logger?.warn(`Failed to attach location: ${error instanceof Error ? error.message : "Unknown"}`);
+            throw error;
+        }
+    }
+    /**
+     * Creates contribution records with progress tracking.
+     *
+     * @param hypercertUri - URI of the hypercert
+     * @param contributions - Array of contribution data
+     * @param onProgress - Optional progress callback
+     * @returns Promise resolving to array of contribution URIs
+     * @internal
+     */
+    async createContributionsWithProgress(hypercertUri, contributions, onProgress) {
+        this.emitProgress(onProgress, { name: "createContributions", status: "start" });
+        try {
+            const contributionUris = [];
+            for (const contrib of contributions) {
+                const contribResult = await this.addContribution({
+                    hypercertUri,
+                    contributors: contrib.contributors,
+                    role: contrib.role,
+                    description: contrib.description,
+                });
+                contributionUris.push(contribResult.uri);
+            }
+            this.emitProgress(onProgress, {
+                name: "createContributions",
+                status: "success",
+                data: { count: contributionUris.length },
+            });
+            return contributionUris;
+        }
+        catch (error) {
+            this.emitProgress(onProgress, { name: "createContributions", status: "error", error: error });
+            this.logger?.warn(`Failed to create contributions: ${error instanceof Error ? error.message : "Unknown"}`);
+            throw error;
+        }
+    }
     /**
      * Creates a new hypercert with all related records.
      *
@@ -2238,142 +3322,31 @@ class HypercertOperationsImpl extends EventEmitter {
         };
         try {
             // Step 1: Upload image if provided
-            let imageBlobRef;
-            if (params.image) {
-                this.emitProgress(params.onProgress, { name: "uploadImage", status: "start" });
-                try {
-                    const arrayBuffer = await params.image.arrayBuffer();
-                    const uint8Array = new Uint8Array(arrayBuffer);
-                    const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
-                        encoding: params.image.type || "image/jpeg",
-                    });
-                    if (uploadResult.success) {
-                        imageBlobRef = {
-                            $type: "blob",
-                            ref: { $link: uploadResult.data.blob.ref.toString() },
-                            mimeType: uploadResult.data.blob.mimeType,
-                            size: uploadResult.data.blob.size,
-                        };
-                    }
-                    this.emitProgress(params.onProgress, {
-                        name: "uploadImage",
-                        status: "success",
-                        data: { size: params.image.size },
-                    });
-                }
-                catch (error) {
-                    this.emitProgress(params.onProgress, { name: "uploadImage", status: "error", error: error });
-                    throw new NetworkError(`Failed to upload image: ${error instanceof Error ? error.message : "Unknown"}`, error);
-                }
-            }
+            const imageBlobRef = params.image ? await this.uploadImageBlob(params.image, params.onProgress) : undefined;
             // Step 2: Create rights record
-            this.emitProgress(params.onProgress, { name: "createRights", status: "start" });
-            const rightsRecord = {
-                $type: HYPERCERT_COLLECTIONS.RIGHTS,
-                rightsName: params.rights.name,
-                rightsType: params.rights.type,
-                rightsDescription: params.rights.description,
-                createdAt,
-            };
-            const rightsValidation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.RIGHTS, rightsRecord);
-            if (!rightsValidation.valid) {
-                throw new ValidationError(`Invalid rights record: ${rightsValidation.error}`);
-            }
-            const rightsResult = await this.agent.com.atproto.repo.createRecord({
-                repo: this.repoDid,
-                collection: HYPERCERT_COLLECTIONS.RIGHTS,
-                record: rightsRecord,
-            });
-            if (!rightsResult.success) {
-                throw new NetworkError("Failed to create rights record");
-            }
-            result.rightsUri = rightsResult.data.uri;
-            result.rightsCid = rightsResult.data.cid;
-            this.emit("rightsCreated", { uri: result.rightsUri, cid: result.rightsCid });
-            this.emitProgress(params.onProgress, {
-                name: "createRights",
-                status: "success",
-                data: { uri: result.rightsUri },
-            });
+            const { uri: rightsUri, cid: rightsCid } = await this.createRightsRecord(params.rights, createdAt, params.onProgress);
+            result.rightsUri = rightsUri;
+            result.rightsCid = rightsCid;
             // Step 3: Create hypercert record
-            this.emitProgress(params.onProgress, { name: "createHypercert", status: "start" });
-            const hypercertRecord = {
-                $type: HYPERCERT_COLLECTIONS.CLAIM,
-                title: params.title,
-                shortDescription: params.shortDescription,
-                description: params.description,
-                workScope: params.workScope,
-                workTimeFrameFrom: params.workTimeFrameFrom,
-                workTimeFrameTo: params.workTimeFrameTo,
-                rights: { uri: result.rightsUri, cid: result.rightsCid },
-                createdAt,
-            };
-            if (imageBlobRef) {
-                hypercertRecord.image = imageBlobRef;
-            }
-            if (params.evidence && params.evidence.length > 0) {
-                hypercertRecord.evidence = params.evidence;
-            }
-            const hypercertValidation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.CLAIM, hypercertRecord);
-            if (!hypercertValidation.valid) {
-                throw new ValidationError(`Invalid hypercert record: ${hypercertValidation.error}`);
-            }
-            const hypercertResult = await this.agent.com.atproto.repo.createRecord({
-                repo: this.repoDid,
-                collection: HYPERCERT_COLLECTIONS.CLAIM,
-                record: hypercertRecord,
-            });
-            if (!hypercertResult.success) {
-                throw new NetworkError("Failed to create hypercert record");
-            }
-            result.hypercertUri = hypercertResult.data.uri;
-            result.hypercertCid = hypercertResult.data.cid;
-            this.emit("recordCreated", { uri: result.hypercertUri, cid: result.hypercertCid });
-            this.emitProgress(params.onProgress, {
-                name: "createHypercert",
-                status: "success",
-                data: { uri: result.hypercertUri },
-            });
+            const { uri: hypercertUri, cid: hypercertCid } = await this.createHypercertRecord(params, rightsUri, rightsCid, imageBlobRef, createdAt, params.onProgress);
+            result.hypercertUri = hypercertUri;
+            result.hypercertCid = hypercertCid;
             // Step 4: Attach location if provided
             if (params.location) {
-                this.emitProgress(params.onProgress, { name: "attachLocation", status: "start" });
                 try {
-                    const locationResult = await this.attachLocation(result.hypercertUri, params.location);
-                    result.locationUri = locationResult.uri;
-                    this.emitProgress(params.onProgress, {
-                        name: "attachLocation",
-                        status: "success",
-                        data: { uri: result.locationUri },
-                    });
+                    result.locationUri = await this.attachLocationWithProgress(hypercertUri, params.location, params.onProgress);
                 }
-                catch (error) {
-                    this.emitProgress(params.onProgress, { name: "attachLocation", status: "error", error: error });
-                    this.logger?.warn(`Failed to attach location: ${error instanceof Error ? error.message : "Unknown"}`);
+                catch {
+                    // Error already logged and progress emitted
                 }
             }
             // Step 5: Create contributions if provided
             if (params.contributions && params.contributions.length > 0) {
-                this.emitProgress(params.onProgress, { name: "createContributions", status: "start" });
-                result.contributionUris = [];
                 try {
-                    for (const contrib of params.contributions) {
-                        const contribResult = await this.addContribution({
-                            hypercertUri: result.hypercertUri,
-                            contributors: contrib.contributors,
-                            role: contrib.role,
-                            description: contrib.description,
-                        });
-                        result.contributionUris.push(contribResult.uri);
-                    }
-                    this.emitProgress(params.onProgress, {
-                        name: "createContributions",
-                        status: "success",
-                        data: { count: result.contributionUris.length },
-                    });
+                    result.contributionUris = await this.createContributionsWithProgress(hypercertUri, params.contributions, params.onProgress);
                 }
-                catch (error) {
-                    this.emitProgress(params.onProgress, { name: "createContributions", status: "error", error: error });
-                    this.logger?.warn(`Failed to create contributions: ${error instanceof Error ? error.message : "Unknown"}`);
+                catch {
+                    // Error already logged and progress emitted
                 }
             }
             return result;
@@ -2475,9 +3448,9 @@ class HypercertOperationsImpl extends EventEmitter {
                 // Preserve existing image
                 recordForUpdate.image = existingRecord.image;
             }
-            const validation = this.lexiconRegistry.validate(collection, recordForUpdate);
-            if (!validation.valid) {
-                throw new ValidationError(`Invalid hypercert record: ${validation.error}`);
+            const validation = validate(recordForUpdate, collection, "main", false);
+            if (!validation.success) {
+                throw new ValidationError(`Invalid hypercert record: ${validation.error?.message}`);
             }
             const result = await this.agent.com.atproto.repo.putRecord({
                 repo: this.repoDid,
@@ -2526,10 +3499,10 @@ class HypercertOperationsImpl extends EventEmitter {
             if (!result.success) {
                 throw new NetworkError("Failed to get hypercert");
             }
-            // Validate with lexicon registry (more lenient - doesn't require $type)
-            const validation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.CLAIM, result.data.value);
-            if (!validation.valid) {
-                throw new ValidationError(`Invalid hypercert record format: ${validation.error}`);
+            // Validate with lexicon (more lenient - doesn't require $type)
+            const validation = validate(result.data.value, HYPERCERT_COLLECTIONS.CLAIM, "main", false);
+            if (!validation.success) {
+                throw new ValidationError(`Invalid hypercert record format: ${validation.error?.message}`);
             }
             return {
                 uri: result.data.uri,
@@ -2712,9 +3685,9 @@ class HypercertOperationsImpl extends EventEmitter {
                 name: location.name,
                 description: location.description,
             };
-            const validation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.LOCATION, locationRecord);
-            if (!validation.valid) {
-                throw new ValidationError(`Invalid location record: ${validation.error}`);
+            const validation = validate(locationRecord, HYPERCERT_COLLECTIONS.LOCATION, "main", false);
+            if (!validation.success) {
+                throw new ValidationError(`Invalid location record: ${validation.error?.message}`);
             }
             const result = await this.agent.com.atproto.repo.createRecord({
                 repo: this.repoDid,
@@ -2808,9 +3781,9 @@ class HypercertOperationsImpl extends EventEmitter {
                 const hypercert = await this.get(params.hypercertUri);
                 contributionRecord.hypercert = { uri: hypercert.uri, cid: hypercert.cid };
             }
-            const validation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.CONTRIBUTION, contributionRecord);
-            if (!validation.valid) {
-                throw new ValidationError(`Invalid contribution record: ${validation.error}`);
+            const validation = validate(contributionRecord, HYPERCERT_COLLECTIONS.CONTRIBUTION, "main", false);
+            if (!validation.success) {
+                throw new ValidationError(`Invalid contribution record: ${validation.error?.message}`);
             }
             const result = await this.agent.com.atproto.repo.createRecord({
                 repo: this.repoDid,
@@ -2872,9 +3845,9 @@ class HypercertOperationsImpl extends EventEmitter {
                 measurementMethodURI: params.methodUri,
                 evidenceURI: params.evidenceUris,
             };
-            const validation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.MEASUREMENT, measurementRecord);
-            if (!validation.valid) {
-                throw new ValidationError(`Invalid measurement record: ${validation.error}`);
+            const validation = validate(measurementRecord, HYPERCERT_COLLECTIONS.MEASUREMENT, "main", false);
+            if (!validation.success) {
+                throw new ValidationError(`Invalid measurement record: ${validation.error?.message}`);
             }
             const result = await this.agent.com.atproto.repo.createRecord({
                 repo: this.repoDid,
@@ -2925,9 +3898,9 @@ class HypercertOperationsImpl extends EventEmitter {
                 summary: params.summary,
                 createdAt,
             };
-            const validation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.EVALUATION, evaluationRecord);
-            if (!validation.valid) {
-                throw new ValidationError(`Invalid evaluation record: ${validation.error}`);
+            const validation = validate(evaluationRecord, HYPERCERT_COLLECTIONS.EVALUATION, "main", false);
+            if (!validation.success) {
+                throw new ValidationError(`Invalid evaluation record: ${validation.error?.message}`);
             }
             const result = await this.agent.com.atproto.repo.createRecord({
                 repo: this.repoDid,
@@ -3005,9 +3978,9 @@ class HypercertOperationsImpl extends EventEmitter {
             if (coverPhotoRef) {
                 collectionRecord.coverPhoto = coverPhotoRef;
             }
-            const validation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.COLLECTION, collectionRecord);
-            if (!validation.valid) {
-                throw new ValidationError(`Invalid collection record: ${validation.error}`);
+            const validation = validate(collectionRecord, HYPERCERT_COLLECTIONS.COLLECTION, "main", false);
+            if (!validation.success) {
+                throw new ValidationError(`Invalid collection record: ${validation.error?.message}`);
             }
             const result = await this.agent.com.atproto.repo.createRecord({
                 repo: this.repoDid,
@@ -3057,9 +4030,9 @@ class HypercertOperationsImpl extends EventEmitter {
                 throw new NetworkError("Failed to get collection");
             }
             // Validate with lexicon registry (more lenient - doesn't require $type)
-            const validation = this.lexiconRegistry.validate(HYPERCERT_COLLECTIONS.COLLECTION, result.data.value);
-            if (!validation.valid) {
-                throw new ValidationError(`Invalid collection record format: ${validation.error}`);
+            const validation = validate(result.data.value, HYPERCERT_COLLECTIONS.COLLECTION, "#main", false);
+            if (!validation.success) {
+                throw new ValidationError(`Invalid collection record format: ${validation.error?.message}`);
             }
             return {
                 uri: result.data.uri,
@@ -3856,7 +4829,6 @@ class Repository {
      * @param session - Authenticated OAuth session
      * @param serverUrl - Base URL of the AT Protocol server
      * @param repoDid - DID of the repository to operate on
-     * @param lexiconRegistry - Registry for lexicon validation
      * @param isSDS - Whether this is a Shared Data Server
      * @param logger - Optional logger for debugging
      *
@@ -3866,20 +4838,16 @@ class Repository {
      *
      * @internal
      */
-    constructor(session, serverUrl, repoDid, lexiconRegistry, isSDS, logger) {
+    constructor(session, serverUrl, repoDid, isSDS, logger) {
         this.session = session;
         this.serverUrl = serverUrl;
         this.repoDid = repoDid;
-        this.lexiconRegistry = lexiconRegistry;
         this._isSDS = isSDS;
         this.logger = logger;
         // Create a ConfigurableAgent that routes requests to the specified server URL
         // This allows routing to PDS, SDS, or any custom server while maintaining
         // the OAuth session's authentication
         this.agent = new ConfigurableAgent(session, serverUrl);
-        this.lexiconRegistry.addToAgent(this.agent);
-        // Register hypercert lexicons
-        this.lexiconRegistry.registerMany(HYPERCERT_LEXICONS);
     }
     /**
      * The DID (Decentralized Identifier) of this repository.
@@ -3950,7 +4918,7 @@ class Repository {
      * ```
      */
     repo(did) {
-        return new Repository(this.session, this.serverUrl, did, this.lexiconRegistry, this._isSDS, this.logger);
+        return new Repository(this.session, this.serverUrl, did, this._isSDS, this.logger);
     }
     /**
      * Low-level record operations for CRUD on any AT Protocol record type.
@@ -3983,7 +4951,7 @@ class Repository {
      */
     get records() {
         if (!this._records) {
-            this._records = new RecordOperationsImpl(this.agent, this.repoDid, this.lexiconRegistry);
+            this._records = new RecordOperationsImpl(this.agent, this.repoDid);
         }
         return this._records;
     }
@@ -4078,7 +5046,7 @@ class Repository {
      */
     get hypercerts() {
         if (!this._hypercerts) {
-            this._hypercerts = new HypercertOperationsImpl(this.agent, this.repoDid, this.serverUrl, this.lexiconRegistry, this.logger);
+            this._hypercerts = new HypercertOperationsImpl(this.agent, this.repoDid, this.serverUrl, this.logger);
         }
         return this._hypercerts;
     }
@@ -4182,9 +5150,34 @@ const OAuthConfigSchema = z.object({
     redirectUri: 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: z.string(),
+    scope: 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.
@@ -4349,8 +5342,6 @@ class ATProtoSDK {
         this.logger = config.logger;
         // Initialize OAuth client
         this.oauthClient = new OAuthClient(configWithDefaults);
-        // Initialize lexicon registry
-        this.lexiconRegistry = new LexiconRegistry();
         this.logger?.info("ATProto SDK initialized");
     }
     /**
@@ -4476,6 +5467,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.
      *
@@ -4547,30 +5623,7 @@ class ATProtoSDK {
         }
         // Get repository DID (default to session DID)
         const repoDid = session.did || session.sub;
-        return new Repository(session, serverUrl, repoDid, this.lexiconRegistry, isSDS, this.logger);
-    }
-    /**
-     * Gets the lexicon registry for schema validation.
-     *
-     * The lexicon registry manages AT Protocol lexicon schemas used for
-     * validating record data. You can register custom lexicons to extend
-     * the SDK's capabilities.
-     *
-     * @returns The {@link LexiconRegistry} instance
-     *
-     * @example
-     * ```typescript
-     * const registry = sdk.getLexiconRegistry();
-     *
-     * // Register custom lexicons
-     * registry.register(myCustomLexicons);
-     *
-     * // Check if a lexicon is registered
-     * const hasLexicon = registry.has("org.example.myRecord");
-     * ```
-     */
-    getLexiconRegistry() {
-        return this.lexiconRegistry;
+        return new Repository(session, serverUrl, repoDid, isSDS, this.logger);
     }
     /**
      * The configured PDS (Personal Data Server) URL.
@@ -4726,5 +5779,5 @@ const CollaboratorSchema = z.object({
     revokedAt: z.string().optional(),
 });
 
-export { ATProtoSDK, ATProtoSDKConfigSchema, ATProtoSDKError, AuthenticationError, CollaboratorPermissionsSchema, CollaboratorSchema, ConfigurableAgent, InMemorySessionStore, InMemoryStateStore, LexiconRegistry, NetworkError, OAuthConfigSchema, OrganizationSchema, Repository, SDSRequiredError, ServerConfigSchema, SessionExpiredError, TimeoutConfigSchema, ValidationError, createATProtoSDK };
+export { ATPROTO_SCOPE, ATProtoSDK, ATProtoSDKConfigSchema, ATProtoSDKError, AccountActionSchema, AccountAttrSchema, AccountPermissionSchema, AuthenticationError, BlobPermissionSchema, CollaboratorPermissionsSchema, CollaboratorSchema, ConfigurableAgent, HYPERCERT_COLLECTIONS, HYPERCERT_LEXICONS, IdentityAttrSchema, IdentityPermissionSchema, InMemorySessionStore, InMemoryStateStore, IncludePermissionSchema, MimeTypeSchema, NetworkError, NsidSchema, OAuthConfigSchema, OrganizationSchema, PermissionBuilder, PermissionSchema, RepoActionSchema, RepoPermissionSchema, Repository, RpcPermissionSchema, SDSRequiredError, ScopePresets, ServerConfigSchema, SessionExpiredError, TRANSITION_SCOPES, TimeoutConfigSchema, TransitionScopeSchema, ValidationError, buildScope, createATProtoSDK, hasAllPermissions, hasAnyPermission, hasPermission, mergeScopes, parseScope, removePermissions, validateScope };
 //# sourceMappingURL=index.mjs.map