This library has not yet been ported to the New Pico Engine |
Developer credential protected methods to create picos, manage rulesets, and create ECI
The following modules are related to the PCI module and use the same credentialling and permissioning regime.
Many of the functions and actions in the PCI module require an argument that is called an "pico ID." This can be satisfied in one of two ways:
Kynetx will issue the developer credentials which should be included in the ruleset meta function
meta { keys "system_credentials" { "developer_eci" : <string>, "developer_secret" : <string> } } |
Create a new account (requires system permissions)
Parameter | Datatype | Required |
---|---|---|
<ECI> | Event Channel Identifier | |
<map> | key-value hash |
<map>:
On success
key | value |
---|---|
nid | <userid> |
eci | <eci> |
If the developer provides an ECI, the new pico will be created with a link to the ECI as the <parent> pico. Linked picos may include password optionally. Authorization for linked picos without passwords will default to the <parent>'s pico credentials. Failure to provide a password for a top level pico will result in an unusable/defunct pico so don't do that.
The default ECI that is created via new_pico
has a label of _LOGIN
for a unlinked pico and _CHILD
for a linked pico.
response = pci:new_pico({ "username" : "MrFingers34", "firstname" : "Bill", "lastname" : "Last", "password" : "teledoomrefract"}) response = pci:new_pico("eci_string_long_UUID"); |
Deletes an pico (requires system permissions)
Parameter | Datatype | Required |
---|---|---|
<ECI> | Event Channel Identifier | √ |
<map> | key-value hash |
<map>:
On success
key | value |
---|---|
No return value specified |
An ECI is required. The pico, configuration and associated ECIs are deleted. By specifying the {"cascade" : 1} option, all of the linked/dependent picos will also be deleted. Deleting a dependent pico will NOT delete the linked parent pico
undef = pci:delete_pico("eci_string_long_UUID",{"cascade" : 1}) undef = pci:delete_pico("eci_string_long_UUID"); |
Lists the primary ECI associated with any dependent personal clouds
Parameter | Datatype | Required |
---|---|---|
<pico id> | string | hash |
<pico id> : <user_id> | <ECI>
<pico id> :
On success (Array of Arrays)
3-tuple |
---|
<ECI> |
<username> |
<ECI name/label> |
myChildren = pci:list_children(); // Defaults to current session's pico myChildren = pci:list_children({"user_id" : 41305}); // Children for user 41305 myChildren = pci:list_children(41305); // Children for user 41305 |
Lists the primary ECI associated with any dependent personal clouds
Parameter | Datatype | Required |
---|---|---|
<ECI> | string |
3-tuple |
---|
<ECI> |
<username> |
<ECI name/label> |
myParent = pci:list_parent(); // Defaults to current session's pico myParent = pci:list_parent({"user_id" : 41305}); // Parent for user 41305 myParent = pci:list_parent(41305); // Parent for user 41305 |
Changes 'owner' of child ECI to that of the target
Parameter | Datatype | Required |
---|---|---|
<ECI child> | string | √ |
<ECI target> | string | √ |
On success
ECI | |
---|---|
string |
myParent = pci:set_parent("eci_child_UUID","eci_newOwner_UUID"); // Defaults to current session's pico |
Adds one or more rulesets to the cloud specified by <pico id> (requires developer [ "ruleset", 'create" ] permissions)
Parameter | Datatype | Required |
---|---|---|
<pico id> | <string> | |
<rid list> | string | array | √ |
<pico id> :
<rid list> :
On success
key | value |
---|---|
nid | <user id> |
rids | [rid0,..,ridn] |
response = pci:new_ruleset(41305,"a144x101"); response = pci:new_ruleset("eci_string_long_UUID",["a144x101","a169x843","a16x61"]); |
Does this mean that '.' can't be used in a <rid>? Yes.
Deletes one or more rulesets from the cloud specified by <pico id> (requires developer [ "ruleset", "destroy" ] permissions)
Parameter | Datatype | Required |
---|---|---|
<pico id> | <string> | |
<rid list> | string | array | √ |
<pico id> :
<rid list> :
On success
key | value |
---|---|
nid | <user id> |
rids | [rid0,..,ridn] |
response = pci:destroy_ruleset(41305,"a144x101"); response = pci:destroy_ruleset("eci_string_long_UUID",["a144x101","a169x843","a16x61"]); |
Developer credential protected methods to create picos, manage rulesets, and create ECI
lists the rids installed to the pico specified by <pico id> (requires developer [ "ruleset", "show" ] permissions)
Parameter | Datatype | Required |
---|---|---|
<pico id> | <string> | √ |
<pico id> :
On success
key | value |
---|---|
nid | <user id> |
rids | [rid0,..,ridn] |
response = pci:list_ruleset("eci_string_long_UUID"); |
Create a new ECI for the pico specified by <pico id> (requires developer [ "eci", "create" ] permissions)
Parameter | Datatype | Required |
---|---|---|
<pico id> | <string> | |
<eci options> | key-value hash |
<pico id> :
<eci options>
On success
key | value |
---|---|
nid | <user id> |
name | <string> |
cid | <eci> |
response = pci:new_eci(); // creates an ECI for the session user response = pci:new_eci(41305,{"name" : "general foo's token exchange"); // creates an ECI for userid/NID 41305 |
Deletes the ECI specified (requires developer [ "eci", "destroy" ] permissions)
Parameter | Datatype | Required |
---|---|---|
<pico id> | <eci> | √ |
<pico id> :
On success
key | value |
---|---|
nid | <user id> |
cid | <eci> |
response = pci:delete_eci("eci_string_long_UUID"); |
Lists the ECIs assigned to <user id> (requires developer [ "eci", "show" ] permissions)
Parameter | Datatype | Required |
---|---|---|
<pico id> | <string> |
<pico id> :
On success
key | value |
---|---|
nid | <user id> |
channels | [<eci>,..<ecin>] |
response = pci:list_eci("43567"); response = pci:list_eci(); |
Get the type of the ECI.
Parameter | Datatype | Required |
---|---|---|
eci | <string> | √ |
Set new type for the ECI.
Parameter | Datatype | Required |
---|---|---|
eci | <string> | √ |
type | <string> | √ |
Get any attributes stored with the ECI.
Parameter | Datatype | Required |
---|---|---|
eci | <string> | √ |
Set new attributes to be stored with the ECI.
Parameter | Datatype | Required |
---|---|---|
eci | <string> | √ |
attributes | <array> | √ |
To update attributes, you must retrieve the existing attributes with get_eci_attributes()
, modify the result, and then use set_eci_attributes()
to set it as a new attributes
Get a policy stored with the ECI.
Parameter | Datatype | Required |
---|---|---|
eci | <string> | √ |
Set new policy to be stored with the ECI.
Parameter | Datatype | Required |
---|---|---|
eci | <string> | √ |
policy | <map> | √ |
To update a policy, you must retrieve the existing policy with get_eci_policy()
, modify the result, and then use set_eci_policy()
to set it as a new policy.
Get the primary or "login" eci associated with an ECI or <user id> (requires developer [ "eci", "show" ] permissions)
Parameter | Datatype | Required |
---|---|---|
<pico id> | <string> |
<pico id> :
On success
value | |
---|---|
<eci> |
primary = pci:session_token("43567"); primary = pci:session_token("eci_string_long_UUID"); |
Application Lifecycle
The regsister_app() action registers a new OAuth application. It takes the following parameters:
Parameter | Datatype | Required |
---|---|---|
<pico id> | <string> | √ |
The action also accepts the following optional parameters (declared using the with
syntax):
Key | Datatype | Description |
---|---|---|
name | <string> | Human-readable name of the application |
description | <string> | Description of the application |
icon | <url> | URL to 100x100px image file representing the icon for the application |
info_url | <url> | URL to page giving more information about the application |
declined_url | <url> | URL for page to show user if they decline to authorize the application |
callback | <url> | URL for the OAuth callback page |
bootstrap | <array> | Array of ruleset IDs that will be installed when the user authorizes the application |
All of the options can be set, updated, or deleted separately using other functions in this section.
This action creates a developer token and secret that can be used to call other functions in the PCI module. The developer token is given default permissions (set by the configuration of the KRE instance you're operating on).
The action supports the optional setting
clause that gives the names of the variables in which the the token and secret be stored. The first variable will be the token and the second the secret. This variable is available to any expression executed after the action takes place: expressions in the parameters of later actions or in the postlude of the rule. Exercise care that the secret is not inadvertently exposed.
Example:
pci:register_app(<pico id>) setting(token, secret) with name = "Oauth App 2" and icon = "http://example.com/default.png" and description = "Second Oauth App for Testing" and info_url = "http://example.com/info" and declined_url = "http://example.com/declined" and callbacks = ["http://example.com/callbacks"] and bootstrap = ["b16x876.prod"] |
The delete_app() action deletes the app registration identified by the developer token passed in as the only parameter.
Parameter | Datatype | Required |
---|---|---|
<token> | <string> | √ |
The list_apps() lists all of the registered applications for the identified user.
Parameter | Datatype | Required |
---|---|---|
<pico id> | <string> | √ |
The return result is a map with developer tokens as keys and the value being another map of information stored about the application (see register_oauth_app() above) plus the developer secret.
Parameter | Datatype | Required |
---|---|---|
<developer token> | <string> | √ |
<callback uri> | <array> | √ |
cbs = pci:add_callback("eci_string_long_UUID",["http://www.example.com"]); cbs = pci:add_callback("eci_string_long_UUID",["http://www.example.com", "https://secure.example.com/oauth/"]); |
Parameter | Datatype | Required |
---|---|---|
<developer token> | <string> | √ |
<callback uri> | <string> | √ |
remaining_callbacks = pci:remove_callback("eci_string_long_UUID","https://secure.example.com/oauth/"); |
Parameter | Datatype | Required |
---|---|---|
<developer token> | <string> | √ |
Returns the list of callback URLs authorized for an application
callbacks = pci:list_callback("eci_string_long_UUID"); |
Parameter | Datatype | Required |
---|---|---|
<developer token> | <string> | √ |
<bootstrap rid> | <string> | √ |
Returns an array of RIDs.
cbs = pci:add_bootstrap("eci_string_long_UUID","b144x123.prod"); |
Parameter | Datatype | Required |
---|---|---|
<developer token> | <string> | √ |
<bootstrap rid> | <string> | √ |
Returns the new list of bootstrap RIDs.
remaining_bootstrap = pci:remove_bootstrap("eci_string_long_UUID","b144x123.prod"); |
Parameter | Datatype | Required |
---|---|---|
<developer token> | <string> | √ |
callbacks = pci:list_bootstrap("eci_string_long_UUID"); |
Parameter | Datatype | Required |
---|---|---|
<developer token> | <string> | √ |
<oauth app options> | <map> | √ |
Key | Datatype | Description |
---|---|---|
name | <string> | Human-readable name of the application |
description | <string> | Description of the application |
icon | <url> | URL to 100x100px image file representing the icon for the application |
info_url | <url> | URL to page giving more information about the application |
declined_url | <url> | URL for page to show user if they decline to authorize the application |
The function returns the number of fields added.
num_fields = pci:add_appinfo("eci_string_long_UUID", { 'icon' : 'https://squaretag.com/assets/img/st_logo_white_trans.png', 'name' : "Burt's Magic Fingers", 'description' : "Application requests access to: profile information", 'info_page' : 'http://www.exampley.com' } ); |
Parameter | Datatype | Required |
---|---|---|
<developer token> | <string> | √ |
Returns the configured options as a map.
appinfo = pci:get_appinfo("eci_string_long_UUID"); |
Parameter | Datatype | Required |
---|---|---|
<developer token> | <string> | √ |
appinfo = pci:remove_appinfo("eci_string_long_UUID"); |
Compares the supplied password with the hash stored in the database (requires developer ["cloud", "auth"] permissions)
Parameter | Datatype | Required |
---|---|---|
<pico id> | string | hash | |
<password> | string | √ |
<pico id> : <string>
<pico id> :
On success
value | |
---|---|
0 | 1 |
authed = pci:auth("MrFingers34","teledoomrefract"); // default <username>,<password> authed = pci:auth("teledoomrefract"); // uses current session user for authorization target authed = pci:auth({"user_id" : 41305},"teledoomrefract"); |
Checks the KRE database to see if the supplied username is already in use (requires system permissions)
Parameter | Datatype | Required |
---|---|---|
<username> | string | √ |
<pico id> : <string>
<pico id> :
On success
value | |
---|---|
0 | 1 |
is_taken = pci:exists("MrFingers34"); // default <username>,<password> |
Sets the password to the new value (requires developer ["cloud", "auth"] permissions)
Parameter | Datatype | Required |
---|---|---|
<pico id> | string | hash | |
<password> | string | √ |
<password> | string | √ |
<pico id> : <username>
<pico id> :
On success
value | |
---|---|
0 | 1 |
is_set = pci:set_password("teledoomrefract","myN3wpasswOrd"); // sets a new password for session user is_set = pci:set_password("MrFingers34","teledoomrefract","myN3wpasswOrd"); // sets a new password for user "MrFingers34" is_set = pci:set_password({"user_id" : 41305},"teledoomrefract","myN3wpasswOrd"); // new password for user_id/NID 41305 |
Sets the password to the new value (requires system permissions)
Parameter | Datatype | Required |
---|---|---|
<pico id> | string | hash | |
<password> | string | √ |
<pico id> : <username>
<pico id> :
On success
value | |
---|---|
0 | 1 |
is_set = pci:set_password("myN3wpasswOrd"); // sets a new password for session user is_set = pci:set_password("MrFingers34","myN3wpasswOrd"); // sets a new password for user "MrFingers34" is_set = pci:set_password({"user_id" : 41305},"myN3wpasswOrd"); // new password for user_id/NID 41305 |
Returns the username for the supplied credentials
Parameter | Datatype | Required |
---|---|---|
<pico id> | string | hash |
<pico id> : <user_id> | <ECI>
<pico id> :
On success
value | |
---|---|
<username> |
username = pci:get_username({"user_id" : 41305}); |
Returns the email address for the supplied credentials
Parameter | Datatype | Required |
---|---|---|
<pico id> | string | hash |
<pico id> : <user_id> | <ECI>
<pico id> :
On success
value | |
---|---|
<email> |
user_email = pci:get_email({"user_id" : 41305}); |
Create developer credentials (requires system permissions)
Parameter | Datatype | Required |
---|---|---|
<pico id> | <eci> | √ |
<pico id> :
On success
value | |
---|---|
<developer_secret> |
secret = pci:create_developer_key(); secret = pci:create_developer_key("eci_string_long_UUID"); |
Authorize a developer pico for a particular operation (requires system permissions)
Parameter | Datatype | Required |
---|---|---|
<pico id> | <string> | √ |
<developer secret> | <string> | √ |
<permission path> | <array> | √ |
<pico id> :
On success
value | |
---|---|
1 |
isset = pci:set_permissions("eci_string_long_UUID","secret_UUID",["ruleset", "create"]); |
De-authorize a developer pico for a particular operation (requires system permissions)
Parameter | Datatype | Required |
---|---|---|
<pico id> | <string> | √ |
<developer secret> | <string> | √ |
<permission path> | <array> | √ |
<pico id> :
On success
value | |
---|---|
0 |
isset = pci:clear_permissions("eci_string_long_UUID","secret_UUID",["ruleset", "destroy"]); |
List permissions for an pico (requires system permissions)
Parameter | Datatype | Required |
---|---|---|
<pico id> | <string> | √ |
<developer secret> | <string> | √ |
<permission path> | <array> | √ |
<pico id> :
On success
value | |
---|---|
0 | 1 |
isset = pci:get_permissions("eci_string_long_UUID","secret_UUID",["eci", "destroy"]); |