cpclient

cpclient is a simplified ffi api interface to a cypherpost server.

It handles all the complex cryptographic tasks and post segregation for clients.

API

Stringified JSON is used as IO.

Common Error Output

struct S5Error{
    code: u32, // HTTP STATUS CODES
    message: String
}

Genesis Filter

genesis_filter is a common field among calls that return large vector of objects. They can be filtered by providing this field, which will only return entries made after a certain timestamp. Default is set to 0 if no value is passed.

socks5

Use a socks5 port to a local tor instance. Use 0 if communicating over clearnet.

FUNCTIONS

create_social_root (COMPLETED)

Input

    master_root: String,
    account: int,

Output

struct SocialRoot {
    social_root: String,
}

server_identity (COMPLETED)

Input

    hostname: String,
    socks5: int,
    social_root: String,

Output

struct ServerIdentity{
    kind: String, 
    name: String,
}

get_members (COMPLETED)

Input

    hostname: String,
    socks5: int,
    social_root: String,

Output

struct Members{
    identities:Vec<Member>,
}

Member {
    username: String,
    pubkey: String,
}

admin_invite (COMPLETED)

Only applicable for an admin with a secret.

kind must be either "priv/privileged", all other string values will default to "standard".

count sets how many users a privileged user can invite. Use 0 for standard invitations.

Input

    hostname: String,
    socks5: int,
    admin_secret: String,
    kind: String,
    count: int,

Output

struct Invitation{
    invite_code: String,
}

priv_user_invite (COMPLETED)

Only applicable to privileged users created by the admin.

Input

    hostname: String,
    socks5: int,
    social_root: String,
    invite_code: String,

The resulting invite_code will be a standard kind, which cannot be used to invite other users.

Output

struct Invitation{
    invite_code: String,
}

join (COMPLETED)

Input

    hostname: String,
    socks5: int,
    social_root: String,
    username: String,

Output

struct ServerStatusResponse{
    status: bool
}

get_badges

Input

    hostname: String,
    socks5: int,
    social_root: String,
    genesis_filter: int,

Output

struct AllBadges{
    badges: Vec<Badge>,
}

struct Badge{
    genesis: String,
    kind: AnnouncementKind,
    by: String,
    to : String,
    nonce: String,
    signature: String,
    hash: String,
}

AnnouncementKind{
    "Trust",
    "Scam",
}

give_badge

Input

    hostname: String,
    socks5: int,
    social_root: String, 
    to: String,
    kind: AnnouncementKind,

Output

struct ServerResponseStatus {
    status: bool,
}

send_post (COMPLETED)

Users must keep track of the last used index to maintain forward secrecy. The server also keeps track of it, but this should only be used in case of recovery.

to semi-colon separated kind:value where kind is either "direct" where value is a pubkey OR "group" where value is a group id.

payload semi-colon separated kind:value where kind is either "message" where value is a message OR "secret" where value is a hash.

Input

    hostname: String,
    socks5: int,
    social_root: String,
    index: int,
    to: String,
    payload: String,
}

Output

struct PostId{
    id: String,
}

send_keys (COMPLETED)

Use the same index used when sending the related post.

recipients comma separated list of pubkeys who can view the post (for whome to make keys).

Input

    hostname: String,
    socks5: int,
    social_root: String,
    index: int,
    recipients: String,
}

Output

struct ServerResponseStatus{
    status: bool,
}

get_one_post (COMPLETED)

Get a single post by id. To be used as notification stream provides post_ids.

Input

    hostname: String,
    socks5: int,
    social_root: String,
    post_id: int,

Output

struct LocalPostModel{
    id: String,
    genesis: u64,
    expiry: u64,
    owner: String,
    post: Post,
}

struct Post{
    to: Recipient,
    payload: Payload,
    checksum: String,
    signature: String,
}

struct Recipient{
    kind: RecipientKind,
    value: String, //pubkey for direct, gid for group
}

enum RecipientKind{
    Direct,
    Group,
}

struct Payload{
    kind: PayloadKind,
    value: String,
}

enum PayloadKind{
    Message,
    Secret,
}

get_all_posts (COMPLETED)

Returns all posts for a user, organized as ChatHistory

Input

    hostname: String,
    socks5: int,
    social_root: String,
    genesis_filter: int,

Output

struct SortedPosts{
    verified: Vec<PostsAsChat>,
    corrupted: Vec<String>, // list of post_ids (where checksum verify invalid <soon + decryption failed>)
    latest_genesis: u64, // use as genesis filter and index with every new added single post
}

struct PostsAsChat{
    counter_party: String,
    posts: Vec<LocalPostModel>
}

last_index

Input

    hostname: String,
    socks5: int,
    social_root: String,

Output

struct LastIndex {
    last_index: u32,
}

leave (COMPLETED)

Removes an identity and all associated badges and posts.

{
    hostname: String,
    socks5: int,
    social_root: String,
}

Output

struct ServerStatusResponse{
    status: bool,
}

NOTIFICATION STREAM

The notification stream api must be handled by the client. To help with this use the following helper functions:

create_stream_headers

{
    social_root: String,
}

Output

{
    pubkey: String,
    nonce: String,
    signature: String
}

Testing

Ensure that dto.rs tests and lib.rs use #[ignore] unless you have a local cypherpost server running or tests will fail.

Run tests on a single thread or you will face errors because dto test entries will effects lib.rs test entries.

cargo test -- --test-threads=1