Add CLI docs. Update READMEs.

Author: gherman-cs

README.md

@@ -0,0 +1,39 @@
+## ⚠️ Security Warning
+
+**Keep your API credentials secure!**
+
+- The `<API_KEY>` and `<API_SECRET>` are sensitive credentials that grant access to your application’s PulseBeam resources. **Do not expose these credentials** in:
+  - Public repositories.
+  - Client-side code.
+  - Shared or unencrypted environments.
+
+- Treat tokens generated by this CLI as sensitive data. Tokens should only be shared with trusted clients.
+
+### Recommended Practices:
+1. **Environment Variables:** Store your API credentials securely in environment variables instead of hardcoding them in your codebase.
+    ```bash
+    export PULSEBEAM_API_KEY="your_api_key"
+    export PULSEBEAM_API_SECRET="your_api_secret"
+    ```
+
+2. **Access Controls:** Regularly rotate API credentials and limit their scope to only necessary permissions.
+
+3. **Auditing:** Monitor usage of your credentials and investigate any unauthorized activity.
+
+## 💳 Billing and Token Usage
+
+**Be aware:** Generating and using tokens can incur billing charges. Each token enables interactions with PulseBeam's infrastructure, which may contribute to your account’s usage costs.
+
+### Billing Best Practices:
+1. **Understand Your Plan:** Familiarize yourself with the details of your billing plan. For more information, visit our [Billing Page](https://pulsebeam.dev/billing).
+2. **Monitor Usage:** Keep track of token usage to avoid unexpected charges. Utilize PulseBeam’s dashboards and APIs for real-time monitoring.
+3. **Token Expiration:** Set appropriate `duration` values for tokens to limit unnecessary usage. Tokens with a longer duration may result in increased billing if misused.
+4. **Audit Token Distribution:** Ensure tokens are only distributed to trusted clients to avoid misuse that could drive up costs.
+
+### ⚠️ Important Billing Warning
+
+- Tokens allow access to PulseBeam's infrastructure and **may result in charges depending on your usage**.
+- Misuse or unauthorized distribution of tokens can lead to **unexpected billing costs**.
+- **Ensure you monitor your account's activity regularly** and revoke tokens that are no longer needed.
+
+For detailed information on billing and usage policies, visit our [Billing Page](https://pulsebeam.dev/billing).

examples/.gitignore

@@ -0,0 +1 @@
+target

examples/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "pulsebeam-cli"
+version = "0.0.1"
+authors = ["Lukas Herman [email protected]"]
+edition = "2021"
+
+[[bin]]
+name = "pulsebeam-cli"
+path = "pulsebeam.rs"
+
+[dependencies]
+anyhow = "1.0"
+clap = { version = "4", features = ["derive"] }
+pulsebeam-core = { path = ".." }

examples/README.md

@@ -0,0 +1,101 @@
+# PulseBeam CLI
+
+Generates secure tokens for client-side applications. For example, clients using the `@pulsebeam/peer` WebRTC Peer-to-Peer Communication SDK.
+
+These tokens enable secure interaction with PulseBeam signaling servers for peer-to-peer connections.
+
+For a server-side token-generation alternative and more documentation, see [`@pulsebeam/server`](https://jsr.io/@pulsebeam/server).
+
+## Quick Start
+
+```bash
+cargo build
+./target/debug/pulsebeam-cli create-token \
+    --peer-id "peer-1" \
+    --group-id "test" \
+    --allow-policy "test:peer-*" \
+    --api-key "your_api_key" \
+    --api-secret "your_api_secret"
+
+./target/debug/pulsebeam-cli create-token \
+    --peer-id "peer-2" \
+    --group-id "test" \
+    --allow-policy "test:peer-*" \
+    --api-key "your_api_key" \
+    --api-secret "your_api_secret"
+```
+
+Now you should have two tokens. You can use the tokens to connect the two peers together using PulseBeam. They are valid for the next hour.
+
+## Installation
+
+1. Make sure you have Rust and Cargo installed: https://rustup.rs/
+2. Clone this repository.
+3. Navigate to the project directory in your terminal.
+4. Build the project: `cargo build`
+
+## Usage
+
+```bash
+./target/debug/pulsebeam-cli create-token --help
+```
+| Parameter     | Description                                                                                           |
+|---------------|-------------------------------------------------------------------------------------------------------|
+| `peer-id`     | ID for the peer this token is intended to be used by. [More info](https://jsr.io/@pulsebeam/server/doc/~/PeerClaims#constructor_0) |
+| `group-id`    | ID for the group the peer is in, scoped to your application. [More info](https://jsr.io/@pulsebeam/server/doc/~/PeerClaims#constructor_0) |
+| `duration`    | Duration in seconds TTL before token expiration.                                                          |
+| `allow-policy`| Defines which peer(s) this peer is allowed to connect to. Default: `\"*:*\"` (connect to any other peer)[^1]. [More info](https://jsr.io/@pulsebeam/server/doc/~/PeerPolicy) |
+| `create-token`| Generates a token[^2][^3] based on the provided inputs/defaults.                                               |
+
+[^1]: Even with the `\"*:*\"` allow-policy, peers can only connect to other peers within the scope of your `<API_KEY>`.
+
+[^2]: Provide the CLI-generated token to your client's to allow them to talk to PulseBeam signaling servers and make connections with each other.
+
+[^3]: See billing section below.
+
+```bash
+./target/debug/pulsebeam-cli --help
+```
+
+* Set `api-key` and `api-secret` with your credentials obtained from PulseBeam (https://pulsebeam.dev).
+* Warning: be sure to protect your <API_KEY> and <API_SECRET>. See information below 
+
+## ⚠️ Security Warning
+
+**Keep your API credentials secure!**
+
+- The `<API_KEY>` and `<API_SECRET>` are sensitive credentials that grant access to your application’s PulseBeam resources. **Do not expose these credentials** in:
+  - Public repositories.
+  - Client-side code.
+  - Shared or unencrypted environments.
+
+- Treat tokens generated by this CLI as sensitive data. Tokens should only be shared with trusted clients.
+
+### Recommended Practices:
+1. **Environment Variables:** Store your API credentials securely in environment variables instead of hardcoding them in your codebase.
+    ```bash
+    export PULSEBEAM_API_KEY="your_api_key"
+    export PULSEBEAM_API_SECRET="your_api_secret"
+    ```
+
+2. **Access Controls:** Regularly rotate API credentials and limit their scope to only necessary permissions.
+
+3. **Auditing:** Monitor usage of your credentials and investigate any unauthorized activity.
+
+## 💳 Billing and Token Usage
+
+**Be aware:** Generating and using tokens can incur billing charges. Each token enables interactions with PulseBeam's infrastructure, which may contribute to your account’s usage costs.
+
+### Billing Best Practices:
+1. **Understand Your Plan:** Familiarize yourself with the details of your billing plan. For more information, visit our [Billing Page](https://pulsebeam.dev/billing).
+2. **Monitor Usage:** Keep track of token usage to avoid unexpected charges. Utilize PulseBeam’s dashboards and APIs for real-time monitoring.
+3. **Token Expiration:** Set appropriate `duration` values for tokens to limit unnecessary usage. Tokens with a longer duration may result in increased billing if misused.
+4. **Audit Token Distribution:** Ensure tokens are only distributed to trusted clients to avoid misuse that could drive up costs.
+
+### ⚠️ Important Billing Warning
+
+- Tokens allow access to PulseBeam's infrastructure and **may result in charges depending on your usage**.
+- Misuse or unauthorized distribution of tokens can lead to **unexpected billing costs**.
+- **Ensure you monitor your account's activity regularly** and revoke tokens that are no longer needed.
+
+For detailed information on billing and usage policies, visit our [Billing Page](https://pulsebeam.dev/billing).

examples/pulsebeam.rs

@@ -8,24 +8,24 @@ struct Cli {
     #[command(subcommand)]
     command: Commands,
 
-    /// Application ID (optional, can also be set with the PULSEBEAM_APP_ID environment variable)
+    /// API KEY (required, can also be set with the PULSEBEAM_API_KEY environment variable)
     #[arg(long)]
-    app_id: Option<String>,
+    api_key: Option<String>,
 
-    /// Application secret (optional, can also be set with the PULSEBEAM_APP_SECRET environment variable)
+    /// API SECRET (required, can also be set with the PULSEBEAM_API_SECRET environment variable)
     #[arg(long)]
-    app_secret: Option<String>,
+    api_secret: Option<String>,
 }
 
 #[derive(Subcommand)]
 enum Commands {
     /// Create a new token
     CreateToken {
-        /// Peer ID for the token
+        /// (required) Peer ID for the token
         #[arg(long)]
         peer_id: String,
 
-        /// Group ID for the token
+        /// (required) Group ID for the token
         #[arg(long)]
         group_id: String,
 
@@ -34,27 +34,27 @@ enum Commands {
         duration: u32,
 
         /// Allow connections from group ID and peer ID (format: "group_id:peer_id")
-        #[arg(long, value_name = "GROUP_ID:PEER_ID")]
-        allow_policy: Option<String>,
+        #[arg(long, value_name = "GROUP_ID:PEER_ID", default_value = "*:*")]
+        allow_policy: String,
     },
 }
 
 fn main() -> anyhow::Result<()> {
     let cli = Cli::parse();
 
-    // Get app_id and app_secret, prioritizing CLI arguments over environment variables
-    let app_id = cli
-        .app_id
-        .or_else(|| std::env::var("PULSEBEAM_APP_ID").ok())
+    // Get api_key and api_secret, prioritizing CLI arguments over environment variables
+    let api_key = cli
+        .api_key
+        .or_else(|| std::env::var("PULSEBEAM_API_KEY").ok())
         .context(
-            "PULSEBEAM_APP_ID must be provided either as a CLI argument or an environment variable",
+            "PULSEBEAM_API_KEY must be provided either as a CLI argument or an environment variable",
         )?;
-    let app_secret = cli
-        .app_secret
-        .or_else(|| std::env::var("PULSEBEAM_APP_SECRET").ok())
-        .context("PULSEBEAM_APP_SECRET must be provided either as a CLI argument or an environment variable")?;
+    let api_secret = cli
+        .api_secret
+        .or_else(|| std::env::var("PULSEBEAM_API_SECRET").ok())
+        .context("PULSEBEAM_API_SECRET must be provided either as a CLI argument or an environment variable")?;
 
-    let app = App::new(&app_id, &app_secret);
+    let app = App::new(&api_key, &api_secret);
 
     match &cli.command {
         Commands::CreateToken {
@@ -63,7 +63,7 @@ fn main() -> anyhow::Result<()> {
             duration,
             allow_policy,
         } => {
-            let mut claims = PeerClaims::new(group_id, peer_id);
+            let mut claims: PeerClaims = PeerClaims::new(group_id, peer_id);
 
             // Helper function to parse "group_id:peer_id" strings
             let parse_peer_policy = |s: &String| -> Option<PeerPolicy> {
@@ -78,7 +78,7 @@ fn main() -> anyhow::Result<()> {
                 }
             };
 
-            claims.allow_policy = allow_policy.as_ref().and_then(parse_peer_policy);
+            claims.allow_policy = parse_peer_policy(allow_policy);
 
             let token = app.create_token(&claims, *duration)?;
             println!("{}", token);

js/README.md

@@ -106,3 +106,43 @@ For a deeper understanding of JWT (JSON web token) concepts, consult the RFC: ht
 ### WebRTC Resources
 
 For a deeper understanding of WebRTC concepts, consult the official WebRTC documentation: https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API
+
+## ⚠️ Security Warning
+
+**Keep your API credentials secure!**
+
+- The `<API_KEY>` and `<API_SECRET>` are sensitive credentials that grant access to your application’s PulseBeam resources. **Do not expose these credentials** in:
+  - Public repositories.
+  - Client-side code.
+  - Shared or unencrypted environments.
+
+- Treat tokens generated by this CLI as sensitive data. Tokens should only be shared with trusted clients.
+
+### Recommended Practices:
+1. **Environment Variables:** Store your API credentials securely in environment variables instead of hardcoding them in your codebase.
+    ```bash
+    export PULSEBEAM_API_KEY="your_api_key"
+    export PULSEBEAM_API_SECRET="your_api_secret"
+    ```
+
+2. **Access Controls:** Regularly rotate API credentials and limit their scope to only necessary permissions.
+
+3. **Auditing:** Monitor usage of your credentials and investigate any unauthorized activity.
+
+## 💳 Billing and Token Usage
+
+**Be aware:** Generating and using tokens can incur billing charges. Each token enables interactions with PulseBeam's infrastructure, which may contribute to your account’s usage costs.
+
+### Billing Best Practices:
+1. **Understand Your Plan:** Familiarize yourself with the details of your billing plan. For more information, visit our [Billing Page](https://pulsebeam.dev/billing).
+2. **Monitor Usage:** Keep track of token usage to avoid unexpected charges. Utilize PulseBeam’s dashboards and APIs for real-time monitoring.
+3. **Token Expiration:** Set appropriate `duration` values for tokens to limit unnecessary usage. Tokens with a longer duration may result in increased billing if misused.
+4. **Audit Token Distribution:** Ensure tokens are only distributed to trusted clients to avoid misuse that could drive up costs.
+
+### ⚠️ Important Billing Warning
+
+- Tokens allow access to PulseBeam's infrastructure and **may result in charges depending on your usage**.
+- Misuse or unauthorized distribution of tokens can lead to **unexpected billing costs**.
+- **Ensure you monitor your account's activity regularly** and revoke tokens that are no longer needed.
+
+For detailed information on billing and usage policies, visit our [Billing Page](https://pulsebeam.dev/billing).