Sharing and Permissions - AI Development Patterns: A Practitioner's Guide

When building collaborative AI coding assistants, one of the trickiest aspects isn't the AI itself—it's figuring out how to let people share their work without accidentally exposing something they shouldn't. This chapter explores patterns for implementing sharing and permissions that balance security, usability, and implementation complexity.

A common pattern for collaborative AI assistants is a three-tier sharing model. This approach balances simplicity with flexibility, using two boolean flags—private and public—to create three distinct states:

interface ShareableResource {
    private: boolean
    public: boolean
}

// Three sharing states:
// 1. Private (private: true, public: false) - Only creator access
// 2. Team (private: false, public: false) - Shared with team members
// 3. Public (private: false, public: true) - Anyone with URL can access

async updateSharingState(
    resourceID: string,
    meta: Pick<ShareableResource, 'private' | 'public'>
): Promise<void> {
    // Validate state transition
    if (meta.private && meta.public) {
        throw new Error('Invalid state: cannot be both private and public')
    }

    // Optimistic update for UI responsiveness
    this.updateLocalState(resourceID, meta)

    try {
        // Sync with server
        await this.syncToServer(resourceID, meta)
    } catch (error) {
        // Rollback on failure
        this.revertLocalState(resourceID)
        throw error
    }
}

This design choice uses two booleans instead of an enum for several reasons:

State transitions become more explicit
Prevents accidental visibility changes through single field updates
Creates an invalid fourth state that can be detected and rejected
Maps naturally to user interface controls

Permission Inheritance Patterns

When designing permission systems for hierarchical resources, you face a fundamental choice: inheritance versus independence. Complex permission inheritance can lead to unexpected exposure when parent permissions change. A simpler approach treats each resource independently.

interface HierarchicalResource {
  id: string;
  parentID?: string;
  childIDs: string[];
  permissions: ResourcePermissions;
}

// Independent permissions - each resource manages its own access
class IndependentPermissionModel {
  async updatePermissions(
    resourceID: string,
    newPermissions: ResourcePermissions,
  ): Promise<void> {
    // Only affects this specific resource
    await this.permissionStore.update(resourceID, newPermissions);

    // No cascading to children or parents
    // Users must explicitly manage each resource
  }

  async getEffectivePermissions(
    resourceID: string,
    userID: string,
  ): Promise<EffectivePermissions> {
    // Only check the resource itself
    const resource = await this.getResource(resourceID);
    return this.evaluatePermissions(resource.permissions, userID);
  }
}

// When syncing resources, treat each independently
for (const resource of resourcesToSync) {
  if (processed.has(resource.id)) {
    continue;
  }
  processed.add(resource.id);

  // Each resource carries its own permission metadata
  syncRequest.resources.push({
    id: resource.id,
    permissions: resource.permissions,
    // No inheritance from parents
  });
}

This approach keeps the permission model simple and predictable. Users understand exactly what happens when they change sharing settings without worrying about cascading effects.

URL-based sharing creates a capability system where knowledge of the URL grants access. This pattern is widely used in modern applications.

// Generate unguessable resource identifiers
type ResourceID = `R-${string}`;

function generateResourceID(): ResourceID {
  return `R-${crypto.randomUUID()}`;
}

function buildResourceURL(baseURL: URL, resourceID: ResourceID): URL {
  return new URL(`/shared/${resourceID}`, baseURL);
}

// Security considerations for URL-based sharing
class URLSharingService {
  async createShareableLink(
    resourceID: ResourceID,
    permissions: SharePermissions,
  ): Promise<ShareableLink> {
    // Generate unguessable token
    const shareToken = crypto.randomUUID();

    // Store mapping with expiration
    await this.shareStore.create({
      token: shareToken,
      resourceID,
      permissions,
      expiresAt: new Date(Date.now() + permissions.validForMs),
      createdBy: permissions.creatorID,
    });

    return {
      url: new URL(`/share/${shareToken}`, this.baseURL),
      expiresAt: new Date(Date.now() + permissions.validForMs),
      permissions,
    };
  }

  async validateShareAccess(
    shareToken: string,
    requesterID: string,
  ): Promise<AccessResult> {
    const share = await this.shareStore.get(shareToken);

    if (!share || share.expiresAt < new Date()) {
      return { allowed: false, reason: "Link expired or invalid" };
    }

    // Check if additional authentication is required
    if (share.permissions.requiresAuth && !requesterID) {
      return { allowed: false, reason: "Authentication required" };
    }

    return {
      allowed: true,
      resourceID: share.resourceID,
      effectivePermissions: share.permissions,
    };
  }
}

// Defense in depth: URL capability + authentication
class SecureAPIClient {
  async makeRequest(
    endpoint: string,
    options: RequestOptions,
  ): Promise<Response> {
    return fetch(new URL(endpoint, this.baseURL), {
      ...options,
      headers: {
        ...options.headers,
        "Content-Type": "application/json",
        Authorization: `Bearer ${this.apiKey}`,
        "X-Client-ID": this.clientID,
      },
    });
  }
}

This dual approach provides defense in depth: the URL grants capability, but authentication verifies identity. Even if someone discovers a shared URL, they still need valid credentials for sensitive operations.

Security Considerations

Implementing secure sharing requires several defensive patterns:

Optimistic Updates with Rollback

For responsive UIs, optimistic updates show changes immediately while syncing in the background:

class SecurePermissionService {
  async updatePermissions(
    resourceID: string,
    newPermissions: ResourcePermissions,
  ): Promise<void> {
    // Capture current state for rollback
    const previousState = this.localState.get(resourceID);

    try {
      // Optimistic update for immediate UI feedback
      this.localState.set(resourceID, {
        status: "syncing",
        permissions: newPermissions,
        lastUpdated: Date.now(),
      });
      this.notifyStateChange(resourceID);

      // Sync with server
      await this.syncToServer(resourceID, newPermissions);

      // Mark as synced
      this.localState.set(resourceID, {
        status: "synced",
        permissions: newPermissions,
        lastUpdated: Date.now(),
      });
    } catch (error) {
      // Rollback on failure
      if (previousState) {
        this.localState.set(resourceID, previousState);
      } else {
        this.localState.delete(resourceID);
      }
      this.notifyStateChange(resourceID);
      throw error;
    }
  }
}

Intelligent Retry Logic

Network failures shouldn't result in permanent inconsistency:

class ResilientSyncService {
  private readonly RETRY_BACKOFF_MS = 60000; // 1 minute
  private failedAttempts = new Map<string, number>();

  shouldRetrySync(resourceID: string): boolean {
    const lastFailed = this.failedAttempts.get(resourceID);
    if (!lastFailed) {
      return true; // Never failed, okay to try
    }

    const elapsed = Date.now() - lastFailed;
    return elapsed >= this.RETRY_BACKOFF_MS;
  }

  async attemptSync(resourceID: string): Promise<void> {
    try {
      await this.performSync(resourceID);
      // Clear failure record on success
      this.failedAttempts.delete(resourceID);
    } catch (error) {
      // Record failure time
      this.failedAttempts.set(resourceID, Date.now());
      throw error;
    }
  }
}

Support Access Patterns

Separate mechanisms for support access maintain clear boundaries:

class SupportAccessService {
  async grantSupportAccess(
    resourceID: string,
    userID: string,
    reason: string,
  ): Promise<SupportAccessGrant> {
    // Validate user can grant support access
    const resource = await this.getResource(resourceID);
    if (!this.canGrantSupportAccess(resource, userID)) {
      throw new Error("Insufficient permissions to grant support access");
    }

    // Create time-limited support access
    const grant: SupportAccessGrant = {
      id: crypto.randomUUID(),
      resourceID,
      grantedBy: userID,
      reason,
      expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
      permissions: { read: true, debug: true },
    };

    await this.supportAccessStore.create(grant);

    // Audit log
    await this.auditLogger.log({
      action: "support_access_granted",
      resourceID,
      grantedBy: userID,
      grantID: grant.id,
      reason,
    });

    return grant;
  }
}

These patterns provide multiple layers of protection while maintaining usability and supporting legitimate operational needs.

Real-World Implementation Details

Production systems require pragmatic solutions for common challenges:

API Versioning and Fallbacks

When evolving APIs, graceful degradation ensures system reliability:

class VersionedAPIClient {
  private useNewAPI: boolean = true;

  async updateResource(
    resourceID: string,
    updates: ResourceUpdates,
  ): Promise<void> {
    let newAPISucceeded = false;

    if (this.useNewAPI) {
      try {
        const response = await this.callNewAPI(resourceID, updates);
        if (response.ok) {
          newAPISucceeded = true;
        }
      } catch (error) {
        // Log but don't fail - will try fallback
        this.logAPIError("new_api_failed", error);
      }
    }

    if (!newAPISucceeded) {
      // Fallback to older API format
      await this.callLegacyAPI(resourceID, this.transformToLegacy(updates));
    }
  }

  private transformToLegacy(updates: ResourceUpdates): LegacyUpdates {
    // Transform new format to legacy API expectations
    return {
      private: updates.visibility === "private",
      public: updates.visibility === "public",
      // Map other fields...
    };
  }
}

Avoiding Empty State Sync

Don't synchronize resources that provide no value:

class IntelligentSyncService {
  shouldSyncResource(resource: SyncableResource): boolean {
    // Skip empty or placeholder resources
    if (this.isEmpty(resource)) {
      return false;
    }

    // Skip resources that haven't been meaningfully used
    if (this.isUnused(resource)) {
      return false;
    }

    // Skip resources with only metadata
    if (this.hasOnlyMetadata(resource)) {
      return false;
    }

    return true;
  }

  private isEmpty(resource: SyncableResource): boolean {
    return (
      !resource.content?.length &&
      !resource.interactions?.length &&
      !resource.modifications?.length
    );
  }

  private isUnused(resource: SyncableResource): boolean {
    const timeSinceCreation = Date.now() - resource.createdAt;
    const hasMinimalUsage = resource.interactionCount < 3;

    // Created recently but barely used
    return timeSinceCreation < 5 * 60 * 1000 && hasMinimalUsage;
  }
}

Configuration-Driven Behavior

Use feature flags for gradual rollouts and emergency rollbacks:

interface FeatureFlags {
  enableNewPermissionSystem: boolean;
  strictPermissionValidation: boolean;
  allowCrossTeamSharing: boolean;
  enableAuditLogging: boolean;
}

class ConfigurablePermissionService {
  constructor(
    private config: FeatureFlags,
    private legacyService: LegacyPermissionService,
    private newService: NewPermissionService,
  ) {}

  async checkPermissions(
    resourceID: string,
    userID: string,
  ): Promise<PermissionResult> {
    if (this.config.enableNewPermissionSystem) {
      const result = await this.newService.check(resourceID, userID);

      if (this.config.strictPermissionValidation) {
        // Also validate with legacy system for comparison
        const legacyResult = await this.legacyService.check(resourceID, userID);
        this.compareResults(result, legacyResult, resourceID, userID);
      }

      return result;
    } else {
      return this.legacyService.check(resourceID, userID);
    }
  }
}

These patterns acknowledge that production systems evolve gradually and need mechanisms for safe transitions.

Performance Optimizations

Permission systems can become performance bottlenecks without careful optimization:

Batching and Debouncing

Group rapid changes to reduce server load:

class OptimizedSyncService {
  private pendingUpdates = new BehaviorSubject<Set<string>>(new Set());

  constructor() {
    // Batch updates with debouncing
    this.pendingUpdates
      .pipe(
        filter((updates) => updates.size > 0),
        debounceTime(3000), // Wait 3 seconds for additional changes
        map((updates) => Array.from(updates)),
      )
      .subscribe((resourceIDs) => {
        this.processBatch(resourceIDs).catch((error) => {
          this.logger.error("Batch sync failed:", error);
        });
      });
  }

  queueUpdate(resourceID: string): void {
    const current = this.pendingUpdates.value;
    current.add(resourceID);
    this.pendingUpdates.next(current);
  }

  private async processBatch(resourceIDs: string[]): Promise<void> {
    // Batch API call instead of individual requests
    const updates = await this.gatherUpdates(resourceIDs);
    await this.apiClient.batchUpdate(updates);

    // Clear processed items
    const remaining = this.pendingUpdates.value;
    resourceIDs.forEach((id) => remaining.delete(id));
    this.pendingUpdates.next(remaining);
  }
}

Local Caching Strategy

Cache permission state locally for immediate UI responses:

class CachedPermissionService {
  private permissionCache = new Map<string, CachedPermission>();
  private readonly CACHE_TTL = 5 * 60 * 1000; // 5 minutes

  async checkPermission(
    resourceID: string,
    userID: string,
  ): Promise<PermissionResult> {
    const cacheKey = `${resourceID}:${userID}`;
    const cached = this.permissionCache.get(cacheKey);

    // Return cached result if fresh
    if (cached && this.isFresh(cached)) {
      return cached.result;
    }

    // Fetch from server
    const result = await this.fetchPermission(resourceID, userID);

    // Cache for future use
    this.permissionCache.set(cacheKey, {
      result,
      timestamp: Date.now(),
    });

    return result;
  }

  private isFresh(cached: CachedPermission): boolean {
    return Date.now() - cached.timestamp < this.CACHE_TTL;
  }

  // Invalidate cache when permissions change
  invalidateUser(userID: string): void {
    for (const [key, _] of this.permissionCache) {
      if (key.endsWith(`:${userID}`)) {
        this.permissionCache.delete(key);
      }
    }
  }

  invalidateResource(resourceID: string): void {
    for (const [key, _] of this.permissionCache) {
      if (key.startsWith(`${resourceID}:`)) {
        this.permissionCache.delete(key);
      }
    }
  }
}

Preemptive Permission Loading

Load permissions for likely-needed resources:

class PreemptivePermissionLoader {
  async preloadPermissions(context: UserContext): Promise<void> {
    // Load permissions for recently accessed resources
    const recentResources = await this.getRecentResources(context.userID);

    // Load permissions for team resources
    const teamResources = await this.getTeamResources(context.teamIDs);

    // Batch load to minimize API calls
    const allResources = [...recentResources, ...teamResources];
    const permissions = await this.batchLoadPermissions(
      allResources,
      context.userID,
    );

    // Populate cache
    permissions.forEach((perm) => {
      this.cache.set(`${perm.resourceID}:${context.userID}`, {
        result: perm,
        timestamp: Date.now(),
      });
    });
  }
}

These optimizations ensure that permission checks don't become a user experience bottleneck while maintaining security guarantees.

Design Trade-offs

The implementation reveals several interesting trade-offs:

Simplicity vs. Flexibility: The three-tier model is simple to understand and implement but doesn't support fine-grained permissions like "share with specific users" or "read-only access." This is probably the right choice for a tool focused on individual developers and small teams.

Security vs. Convenience: URL-based sharing makes it easy to share threads (just send a link!) but means anyone with the URL can access public threads. The UUID randomness provides security, but it's still a capability-based model.

Consistency vs. Performance: The optimistic updates make the UI feel responsive, but they create a window where the local state might not match the server state. The implementation handles this gracefully with rollbacks, but it's added complexity.

Backward Compatibility vs. Clean Code: The fallback API mechanism adds code complexity but ensures smooth deployments and rollbacks. This is the kind of pragmatic decision that production systems require.

Implementation Principles

When building sharing systems for collaborative AI tools, consider these key principles:

1. Start Simple

The three-tier model (private/team/public) covers most use cases without complex ACL systems. You can always add complexity later if needed.

2. Make State Transitions Explicit

Using separate flags rather than enums makes permission changes more intentional and prevents accidental exposure.

3. Design for Failure

Implement optimistic updates with rollback, retry logic with backoff, and graceful degradation patterns.

4. Cache Strategically

Local caching prevents permission checks from blocking UI interactions while maintaining security.

5. Support Operational Needs

Plan for support workflows, debugging access, and administrative overrides from the beginning.

6. Optimize for Common Patterns

Most developers follow predictable sharing patterns:

Private work during development
Team sharing for code review
Public sharing for teaching or documentation

Design your system around these natural workflows rather than trying to support every possible permission combination.

7. Maintain Audit Trails

Track permission changes for debugging, compliance, and security analysis.

interface PermissionAuditEvent {
  timestamp: Date;
  resourceID: string;
  userID: string;
  action: "granted" | "revoked" | "modified";
  previousState?: PermissionState;
  newState: PermissionState;
  reason?: string;
}

8. Consider Privacy by Design

Default to private sharing and require explicit action to increase visibility. Make the implications of each sharing level clear to users.

The most important insight is that effective permission systems align with human trust patterns and workflows. Technical complexity should serve user needs, not create barriers to collaboration.