Temporary Links

The Temporary Link entity manages time-limited, single-use URLs for various system functions such as password resets, invitations, and privileged access. Each link has built-in security features including expiration, usage tracking, and permission requirements.

Schema Definition

type TemporaryLink = {
  // Base Properties
  _id: string;                // MongoDB ObjectId
  link_type: TemporaryLinkType; // Required link purpose
  target_url: string;         // Required destination URL
  token: string;             // Required unique token
  expires_at: Date;          // Required expiration date
  is_used: boolean;          // Required usage flag
  max_uses?: number;         // Optional usage limit
  current_uses: number;      // Required usage counter
  metadata: {                // Required metadata object
    required_permissions?: string[]; // Optional required permissions
    additional_data?: Record<string, unknown>; // Optional extra data
  };
  
  // References
  user_id?: string;          // Optional associated user
  organization_id?: string;   // Optional associated organization
  created_by_id: string;     // Required creator reference
  
  // Virtual Fields
  full_url: string;          // Auto-generated complete URL
  
  // Timestamps
  createdAt: Date;           // Auto-generated
  updatedAt: Date;           // Auto-updated
} & BaseEntity;

Field Descriptions

Base Properties

Field	Type	Required	Unique	Description
_id	ObjectId	Yes	Yes	Unique identifier for the link
link_type	TemporaryLinkType	Yes	No	Purpose of the temporary link
target_url	string	Yes	No	Destination URL
token	string	Yes	Yes	Unique token for link validation
expires_at	Date	Yes	No	Link expiration timestamp
is_used	boolean	Yes	No	Whether link has been used
max_uses	number	No	No	Maximum allowed uses
current_uses	number	Yes	No	Current usage count
metadata	object	Yes	No	Additional link metadata
user_id	ObjectId	No	No	Associated user reference
organization_id	ObjectId	No	No	Associated organization reference
created_by_id	ObjectId	Yes	No	Link creator reference
full_url	string	Virtual	No	Complete URL with token

Link Types and Metadata

enum TemporaryLinkType {
  RESET_PASSWORD = 'RESET_PASSWORD',         // Password reset flows
  SIGNUP_INVITE = 'SIGNUP_INVITE',          // New user signup invitations
  ORGANIZATION_INVITE = 'ORGANIZATION_INVITE', // Organization membership invites
  PRIVILEGED_VIEW = 'PRIVILEGED_VIEW'       // Temporary privileged access
}

const TemporaryLinkTypeMetadata = {
  RESET_PASSWORD: {
    description: 'Used for password reset flows',
    expiration: 24 * 60 * 60 * 1000, // 24 hours
  },
  SIGNUP_INVITE: {
    description: 'Used for inviting users to join an organization',
    expiration: 7 * 24 * 60 * 60 * 1000, // 7 days
  },
  ORGANIZATION_INVITE: {
    description: 'Used for inviting users to join an organization',
    expiration: 7 * 24 * 60 * 60 * 1000, // 7 days
  },
  PRIVILEGED_VIEW: {
    description: 'Used for temporary access to privileged views',
    expiration: 4 * 60 * 60 * 1000, // 4 hours
  }
};

Relationships

Primary Relationships

• TemporaryLink → User (Many-to-One, Optional)

  • Links can be associated with a specific user
  • Referenced via user_id field
  • Required for user-specific actions like password resets

• TemporaryLink → Organization (Many-to-One, Optional)

  • Links can be associated with an organization
  • Referenced via organization_id field
  • Required for organization-specific invites

• TemporaryLink → User (Creator) (Many-to-One, Required)

  • Each link must have a creator
  • Referenced via created_by_id field
  • Tracks who generated the link

Validation

1. Token Generation

   • Must be cryptographically secure
   • Must be unique across all temporary links
   • Automatically added to target URL as query parameter

2. Expiration

   • Must have a valid future expiration date
   • TTL index automatically removes expired links
   • Type-specific default expiration periods

3. Usage Tracking

   • current_uses must not exceed max_uses
   • is_used flag for single-use links
   • Atomic updates for usage counting

Link Lifecycle

1. Creation

   // Example of creating an organization invite link
   const tempLink = {
     link_type: TemporaryLinkType.ORGANIZATION_INVITE,
     target_url: "https://app.wrkbelt.com/join-org",
     token: "secure-random-token",
     expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
     is_used: false,
     current_uses: 0,
     metadata: {
       required_permissions: ["org.join"],
       additional_data: {
         organization_name: "Acme Corp"
       }
     },
     organization_id: "org123",
     created_by_id: "user456"
   };

2. Usage

   // Example of updating link usage
   await TemporaryLink.updateOne(
     { 
       _id: linkId,
       is_used: false,
       expires_at: { $gt: new Date() }
     },
     { 
       $inc: { current_uses: 1 },
       $set: { is_used: true }
     }
   );

Security Considerations

1. Token Security

   • Cryptographically secure token generation
   • No token reuse allowed
   • Token expiration enforcement

2. Access Control

   • Permission-based access via metadata
   • Organization-scoped access
   • Usage limit enforcement

3. Expiration

   • Automatic cleanup of expired links
   • No reactivation of expired links
   • Type-specific expiration periods

Performance Considerations

1. Indexes

   • Unique index on token
   • TTL index on expires_at
   • Compound indexes for common queries:
     • { user_id: 1, link_type: 1 }
     • { organization_id: 1, link_type: 1 }

2. Query Optimization

   • Efficient token validation
   • Atomic updates for usage tracking
   • Expired link cleanup

3. URL Generation

   • Virtual field for full URL
   • Efficient token parameter handling
   • URL safety validation