• Publicity: Public Only All

token-procs.tcl

Account-bound, expiring action tokens. Client properties hold state within a session. Action tokens authorize a specific operation across sessions and are consumed transactionally.

Location:
packages/acs-authentication/tcl/token-procs.tcl

Procedures in this file

Detailed information

auth::token::issue (public)

 auth::token::issue -purpose purpose -user_id user_id -ttl ttl \
    [ -context context ]

Issue a token, replacing the outstanding token for this account and purpose. Deliver the returned token only through the channel authorized by the caller. Use an application-defined purpose and keep context free of credentials.

Switches:
-purpose (required)
-user_id (required)
-ttl (required)
Lifetime in seconds.
-context (optional)
Optional state for the redemption callback (up to 4000 bytes).
Returns:
The raw token, which is stored only as a digest.
See Also:

Partial Call Graph (max 5 caller/called nodes):
auth::token::lock_account auth::token::lock_account (private) db_dml db_dml (public) db_transaction db_transaction (public) auth::token::issue auth::token::issue auth::token::issue->auth::token::lock_account auth::token::issue->db_dml auth::token::issue->db_transaction

Testcases:
No testcase defined.

auth::token::redeem (public)

 auth::token::redeem -purpose purpose -token token -callback callback

Redeem a token for the expected purpose. The callback is a trusted command prefix. It receives the user ID and stored context as its final arguments and runs in the token transaction. It must enforce the operation's authorization rules. A normal return consumes the token. An error rolls back the operation and leaves the token available to retry until expiry. External side effects belong after commit.

Switches:
-purpose (required)
-token (required)
-callback (required)
Returns:
A dictionary with status invalid, or status redeemed and the callback result.

Partial Call Graph (max 5 caller/called nodes):
auth::token::lock_account auth::token::lock_account (private) db_0or1row db_0or1row (public) db_dml db_dml (public) db_string db_string (public) db_transaction db_transaction (public) auth::token::redeem auth::token::redeem auth::token::redeem->auth::token::lock_account auth::token::redeem->db_0or1row auth::token::redeem->db_dml auth::token::redeem->db_string auth::token::redeem->db_transaction

Testcases:
No testcase defined.

auth::token::revoke (public)

 auth::token::revoke -purpose purpose -user_id user_id

Revoke the outstanding token for this account and purpose. When called as part of an account update, take the token account lock before making the update and keep both operations in the same transaction.

Switches:
-purpose (required)
-user_id (required)

Partial Call Graph (max 5 caller/called nodes):
auth::token::lock_account auth::token::lock_account (private) db_dml db_dml (public) db_transaction db_transaction (public) auth::token::revoke auth::token::revoke auth::token::revoke->auth::token::lock_account auth::token::revoke->db_dml auth::token::revoke->db_transaction

Testcases:
No testcase defined.
[ hide source ] | [ make this the default ]

Content File Source

ad_library {

    Account-bound, expiring action tokens.

    Client properties hold state within a session. Action tokens authorize
    a specific operation across sessions and are consumed transactionally.

}

namespace eval auth::token {}

d_proc -public auth::token::issue {
    {-purpose:required}
    {-user_id:required}
    {-ttl:required}
    {-context ""}
} {
    Issue a token, replacing the outstanding token for this account and purpose.
    Deliver the returned token only through the channel authorized by the caller.
    Use an application-defined purpose and keep context free of credentials.

    @param ttl Lifetime in seconds.
    @param context Optional state for the redemption callback (up to 4000 bytes).
    @return The raw token, which is stored only as a digest.
    @see ad_set_client_property
    @see ad_get_client_property
} {
    if {![regexp {^[a-z][a-z0-9_]{0,63}$} $purpose]} {
        error "Invalid action token purpose"
    }
    if {![string is integer -strict $ttl] || $ttl <= 0} {
        error "Action token lifetime must be a positive integer"
    }
    if {[string bytelength $context] > 4000} {
        error "Action token context exceeds 4000 bytes"
    }

    set token [ns_crypto::randombytes -encoding hex 32]
    set digest [ns_crypto::md string -digest sha256 -encoding hex $token]
    db_transaction {
        if {![auth::token::lock_account $user_id]} {
            error "Cannot issue an action token for a missing account"
        }
        set expires_at [expr {[clock seconds] + $ttl}]
        db_dml replace_token {
            delete from auth_action_tokens where user_id = :user_id and purpose = :purpose
        }
        db_dml insert_token {
            insert into auth_action_tokens (user_id, purpose, token_digest, expires_at, token_context)
            values (:user_id, :purpose, :digest, :expires_at, :context)
        }
    }
    return $token
}

d_proc -public auth::token::redeem {
    {-purpose:required}
    {-token:required}
    {-callback:required}
} {
    Redeem a token for the expected purpose.

    The callback is a trusted command prefix. It receives the user ID and stored
    context as its final arguments and runs in the token transaction. It must
    enforce the operation's authorization rules. A normal return consumes the
    token. An error rolls back the operation and leaves the token available to
    retry until expiry. External side effects belong after commit.

    @return A dictionary with status invalid, or status redeemed and the callback result.
} {
    if {![llength $callback]} {
        error "Action token redemption requires a callback"
    }
    set invalid {status invalid}
    if {![regexp {^[0-9a-f]{64}$} $token]} {
        return $invalid
    }
    set digest [ns_crypto::md string -digest sha256 -encoding hex $token]
    set user_id [db_string find_token_account {
        select user_id from auth_action_tokens where token_digest = :digest and purpose = :purpose
    } -default ""]
    if {$user_id eq ""} {
        return $invalid
    }

    set result $invalid
    db_transaction {
        if {[auth::token::lock_account $user_id]} {
            set now [clock seconds]
            if {[db_0or1row find_redeemable_token {
                select token_context from auth_action_tokens
                 where user_id = :user_id and purpose = :purpose
                   and token_digest = :digest and expires_at > :now
            }]} {
                set value [{*}$callback $user_id $token_context]
                db_dml consume_token {
                    delete from auth_action_tokens
                     where user_id = :user_id and purpose = :purpose and token_digest = :digest
                }
                set result [dict create status redeemed result $value]
            }
        }
    }
    return $result
}

d_proc -public auth::token::revoke {
    {-purpose:required}
    {-user_id:required}
} {
    Revoke the outstanding token for this account and purpose. When called as
    part of an account update, take the token account lock before making the
    update and keep both operations in the same transaction.
} {
    db_transaction {
        if {[auth::token::lock_account $user_id]} {
            db_dml revoke_token {
                delete from auth_action_tokens where user_id = :user_id and purpose = :purpose
            }
        }
    }
}

ad_proc -private auth::token::lock_account {user_id} {
    Serialize token operations on the same account. Call inside a transaction.
} {
    return [db_0or1row lock_account {
        select 1 as account_exists from users where user_id = :user_id for update
    }]
}

# Local variables:
#    mode: tcl
#    tcl-indent-level: 4
#    indent-tabs-mode: nil
# End: