← Back to index

tac.core.identity_manager v1.0.0

Provides consistent identity creation, validation, and management APIs. An "identity" represents a user with separate NFC and RFID credentials. NFC cards are high-security (require physical tap), while RFID badges are lower-security (can be scanned at distance).

Author: Twijn • License: MIT
View on GitHub →

Examples

-- In your extension:
function MyExtension.init(tac)
    -- Create an identity with both NFC and RFID
    local identity, err = tac.identityManager.createIdentity({
        name = "John Doe",
        tags = {"tenant.1", "vip"},
        nfcEnabled = true,
        rfidEnabled = true,
        maxDistance = 3.0  -- Max RFID scan distance
    })
    
    -- Create a subscription identity
    local subIdentity, err = tac.identityManager.createSubscriptionIdentity({
        username = "player1",
        duration = 30,
        slot = "tenant.premium",
        nfcEnabled = true,
        rfidEnabled = false
    })
    
    -- Renew an identity
    tac.identityManager.renewIdentity("tenant_1_player1", 30)
    
    -- Get identity info
    local info, err = tac.identityManager.getIdentityInfo("tenant_1_player1")
    if info then
        print("Identity expires in " .. (info.timeUntilExpiration / 86400000) .. " days")
    end
    
    -- Regenerate RFID data for an identity
    tac.identityManager.regenerateRfid("tenant_1_player1")
end

Functions

MyExtension.init()

View source

In your extension:

identityManager.createIdentity(options)

View source

Create a new identity with standard validation and logging Creates an identity with separate NFC and RFID credentials. NFC data is the primary identifier, RFID data is a separate scannable token. - id (string, optional): Identity ID (auto-generated if not provided) - name (string, required): Display name for the identity - tags (table, required): Array of access tags - nfcEnabled (boolean, optional): Enable NFC access (default: true) - rfidEnabled (boolean, optional): Enable RFID access (default: true) - nfcData (string, optional): NFC card data (auto-generated if not provided) - rfidData (string, optional): RFID badge data (auto-generated if not provided) - maxDistance (number, optional): Max RFID scan distance (default: nil = use door setting) - expiration (number, optional): UTC epoch timestamp when identity expires - username (string, optional): Username associated with identity (used in ID generation) - prefix (string, optional): Prefix for auto-generated ID - createdBy (string, optional): Who/what created the identity (default: "system") - metadata (table, optional): Additional custom data - logMessage (string, optional): Custom log message

Parameters:
Returns: string|nil Error message if creation failed

identityManager.createSubscriptionIdentity(options)

View source

Create a subscription identity (with expiration) Specialized function for creating time-limited subscription identities. Commonly used by ShopK integration for selling temporary access. - username (string, required): Username of the subscriber - duration (number, required): Subscription duration in days - slot (string, required): Access level/slot (becomes the identity tag) - nfcEnabled (boolean, optional): Enable NFC access (default: true) - rfidEnabled (boolean, optional): Enable RFID access (default: true) - maxDistance (number, optional): Max RFID scan distance - createdBy (string, optional): Creator identifier (default: "shopk") - purchaseValue (number, optional): Purchase price for metadata - transactionId (string, optional): Transaction ID for metadata - logMessage (string, optional): Custom log message

Parameters:
Returns: string|nil Error message if creation failed

identityManager.renewIdentity(identityId, additionalDuration, options)

View source

Renew an existing identity Extends the expiration date of an existing identity by the specified duration. Updates renewal metadata and logs the renewal event. - renewedBy (string, optional): Who renewed the identity (default: "system") - transactionId (string, optional): Transaction ID for metadata - logMessage (string, optional): Custom log message

Parameters:
Returns: string|nil Error message if renewal failed

identityManager.regenerateRfid(identityId)

View source

Regenerate RFID data for an identity Creates a new RFID token for the identity, invalidating the old one. Useful if an RFID badge is lost or compromised.

Parameters:
Returns: string|nil Error message if regeneration failed

identityManager.setNfcData(identityId, nfcData)

View source

Set NFC data for an identity Associates NFC card data with an identity. Called after writing an NFC card.

Parameters:
Returns: string|nil Error message if update failed

identityManager.setRfidData(identityId, rfidData)

View source

Set RFID data for an identity Associates RFID badge data with an identity. Useful when reprogramming RFID cards using the server writer.

Parameters:
Returns: string|nil Error message if update failed

identityManager.findByNfc(nfcData)

View source

Look up identity by NFC data

Parameters:
Returns: table|nil Identity data if found, nil otherwise

identityManager.findByRfid(rfidData)

View source

Look up identity by RFID data

Parameters:
Returns: table|nil Identity data if found, nil otherwise

identityManager.getIdentityInfo(identityId)

View source

Get identity status and info Retrieves comprehensive information about an identity including expiration status. Returns structured data with calculated fields like isExpired and timeUntilExpiration. - id (string): Identity ID - name (string): Identity display name - tags (table): Access tags array - nfcEnabled (boolean): Whether NFC is enabled - rfidEnabled (boolean): Whether RFID is enabled - hasNfcData (boolean): Whether NFC card data is set - hasRfidData (boolean): Whether RFID badge data is set - maxDistance (number|nil): Max RFID scan distance - created (number): Creation timestamp - createdBy (string): Creator identifier - isExpired (boolean): Whether identity is currently expired - timeUntilExpiration (number|nil): Milliseconds until expiration (nil if no expiration) - expiration (number|nil): Expiration timestamp if set - metadata (table): Custom metadata

Parameters:
Returns: string|nil Error message if identity not found

identityManager.isValidIdentityId(identityId)

View source

Validate identity ID format Checks if an identity ID meets basic format requirements (non-empty string).

Parameters:
Returns: boolean True if valid identity ID format

identityManager.canAccess(identityId, accessMethod)

View source

Check if identity is valid for a specific access method

Parameters:
Returns: string|nil Error message if not valid

identityManager.updateIdentity(identityId, updates)

View source

Update identity settings (enable/disable access methods, distance, etc.)

Parameters:
Returns: string|nil Error message if update failed

identityManager.getAll()

View source

Get all identities

Returns: table All identities

identityManager.deleteIdentity(identityId)

View source

Delete an identity

Parameters:
Returns: string|nil Error message if failed