From 6eaeaee12ce8a56d700ae9e5c90f3869c9c13350 Mon Sep 17 00:00:00 2001 From: pfvatterott Date: Wed, 26 Mar 2025 14:19:33 -0600 Subject: [PATCH 1/2] Update READMEs --- packages/cloudflare-worker/README.md | 152 +++++++++++++++++++++++++++ packages/node/README.md | 133 ++++++++++++++++++++++- 2 files changed, 282 insertions(+), 3 deletions(-) create mode 100644 packages/cloudflare-worker/README.md diff --git a/packages/cloudflare-worker/README.md b/packages/cloudflare-worker/README.md new file mode 100644 index 0000000..85abc22 --- /dev/null +++ b/packages/cloudflare-worker/README.md @@ -0,0 +1,152 @@ +

+ + + +

+ +# PropelAuth Cloudflare Library + +A Javascript library for managing authentication, backed by [PropelAuth](https://www.propelauth.com?ref=github). + +[PropelAuth](https://www.propelauth.com?ref=github) makes it easy to add authentication and authorization to your B2B/multi-tenant application. + +Your frontend gets a beautiful, safe, and customizable login screen. Your backend gets easy authorization with just a few lines of code. You get an easy-to-use dashboard to config and manage everything. + +## Documentation + +- Full reference this library is [here](https://docs.propelauth.com/reference/backend-apis/cloudflare-workers) +- Getting started guides for PropelAuth are [here](https://docs.propelauth.com/) + +## Installation + +```shell +npm install @propelauth/cloudflare-worker +``` + +## Initialize + +`initAuth` performs a one-time initialization of the library. +It will verify your `apiKey` is correct and fetch the metadata needed to verify access tokens in [validateAccessTokenAndGetUserClass](#protect-api-routes). + +You can find the `authUrl`, `apiKey`, and `verifierKey` in the **Backend Integration** section in your PropelAuth dashboard. + +```typescript +import { initAuth } from '@propelauth/cloudflare-worker' + +const { + validateAccessTokenAndGetUserClass, + // ... +} = initAuth({ + authUrl: 'REPLACE_ME', + apiKey: 'REPLACE_ME', + verifierKey: 'REPLACE_ME', +}) +``` + +## Protect API Routes + +After initializing auth, you can verify access tokens by passing it in the Authorization header (formatted `Bearer TOKEN`) to `validateAccessTokenAndGetUserClass`. +You can see more information about the User Class [here](https://docs.propelauth.com/reference/backend-apis/cloudflare-workers#user-class). + +```ts +const authorizationHeader = // Get the Authorization header from an HTTP request +try { + const user = await validateAccessTokenAndGetUserClass(authorizationHeader) + console.log(`Got request from user ${user.userId}`); +} catch (err) { + // You can return a 401, or continue the request knowing it wasn't sent from a logged-in user + console.log(`Unauthorized request ${err}`); +} +``` + +## Authorization / Organizations + +You can also verify which organizations the user is in, and which roles and permissions they have in each organization all through the [User Class](https://docs.propelauth.com/reference/backend-apis/cloudflare-workers#user-class). + +### Check Org Membership + +Verify that the request was made by a valid user **and** that the user is a member of the specified organization. + +```ts +const authorizationHeader = // Get the Authorization header from an HTTP request +const orgId = // get the orgId from somewhere, such as the request URL +try { + const user = await validateAccessTokenAndGetUserClass(authorizationHeader) + const org = user.getOrg(orgId) + if (!org) { + // return a 403 + } + console.log(`Got request from user ${user.userId} for org ${org.orgName}`); +} catch (err) { + // You can return a 401, or continue the request knowing it wasn't sent from a logged-in user + console.log(`Unauthorized request ${err}`); +} +``` + +### Check Org Membership and Role + +Similar to checking org membership, but will also verify that the user has a specific Role in the organization. + +A user has a Role within an organization. By default, the available roles are Owner, Admin, or Member, but these can be configured. These roles are also hierarchical, so Owner > Admin > Member. + +```ts +const authorizationHeader = // Get the Authorization header from an HTTP request +const orgId = // get the orgId from somewhere, such as the request URL +try { + const user = await validateAccessTokenAndGetUserClass(authorizationHeader) + const org = user.getOrg(orgId) + if (!org || !org.isRole("Admin")) { + // return a 403 + } + console.log(`Got request from Admin user ${user.userId} for org ${org.orgName}`); +} catch (err) { + // You can return a 401, or continue the request knowing it wasn't sent from a logged-in user + console.log(`Unauthorized request ${err}`); +} +``` + +### Check Org Membership and Permission + +Similar to checking org membership, but will also verify that the user has the specified permission in the organization. + +Permissions are arbitrary strings associated with a role. For example, `can_view_billing`, `ProductA::CanCreate`, and `ReadOnly` are all valid permissions. You can create these permissions in the PropelAuth dashboard. + +```ts +const authorizationHeader = // Get the Authorization header from an HTTP request +const orgId = // get the orgId from somewhere, such as the request URL +try { + const user = await validateAccessTokenAndGetUserClass(authorizationHeader) + const org = user.getOrg(orgId) + if (!org || !org.hasPermission("can_view_billing")) { + // return a 403 + } + console.log(`User ${user.userId} has 'can_view_billing' permissions for org ${org.orgName}`); +} catch (err) { + // You can return a 401, or continue the request knowing it wasn't sent from a logged-in user + console.log(`Unauthorized request ${err}`); +} +``` + +## Calling Backend APIs + +You can also use the library to call the PropelAuth APIs directly, allowing you to fetch users, create orgs, and a lot more. + +```ts +const auth = initAuth({ + authUrl: 'REPLACE_ME', + apiKey: 'REPLACE_ME', + verifierKey: 'REPLACE_ME', +}) + +const magicLink = await auth.createMagicLink({ + email: 'user@customer.com', +}) +``` + +See the [API Reference](https://docs.propelauth.com/reference) for more information. + + +## Questions? + +Feel free to reach out at support@propelauth.com + diff --git a/packages/node/README.md b/packages/node/README.md index c656969..670cf8d 100644 --- a/packages/node/README.md +++ b/packages/node/README.md @@ -1,12 +1,12 @@

- +

-# PropelAuth Node Middleware +# PropelAuth Node Library -A javascript library for managing authentication, backed by [PropelAuth](https://www.propelauth.com?ref=github). +A Javascript library for managing authentication, backed by [PropelAuth](https://www.propelauth.com?ref=github). [PropelAuth](https://www.propelauth.com?ref=github) makes it easy to add authentication and authorization to your B2B/multi-tenant application. @@ -17,6 +17,133 @@ Your frontend gets a beautiful, safe, and customizable login screen. Your backen - Full reference this library is [here](https://docs.propelauth.com/reference/backend-apis/node) - Getting started guides for PropelAuth are [here](https://docs.propelauth.com/) +## Installation + +```shell +npm install @propelauth/node +``` + +## Initialize + +`initBaseAuth` performs a one-time initialization of the library. +It will verify your `apiKey` is correct and fetch the metadata needed to verify access tokens in [validateAccessTokenAndGetUserClass](#protect-api-routes). + + +```typescript +import { initBaseAuth } from '@propelauth/node'; + +const { + validateAccessTokenAndGetUserClass, + fetchUserMetadataByUserId, + // ... +} = initBaseAuth({ + authUrl: "REPLACE_ME", + apiKey: "REPLACE_ME", +}); +``` + +## Protect API Routes + +After initializing auth, you can verify access tokens by passing it in the Authorization header (formatted `Bearer TOKEN`) to `validateAccessTokenAndGetUserClass`. +You can see more information about the User Class [here](https://docs.propelauth.com/reference/backend-apis/node#user-class). + +```ts +const authorizationHeader = // Get the Authorization header from an HTTP request +try { + const user = await validateAccessTokenAndGetUserClass(authorizationHeader) + console.log(`Got request from user ${user.userId}`); +} catch (err) { + // You can return a 401, or continue the request knowing it wasn't sent from a logged-in user + console.log(`Unauthorized request ${err}`); +} +``` + +## Authorization / Organizations + +You can also verify which organizations the user is in, and which roles and permissions they have in each organization all through the [User Class](https://docs.propelauth.com/reference/backend-apis/node#user-class) + +### Check Org Membership + +Verify that the request was made by a valid user **and** that the user is a member of the specified organization. + +```ts +const authorizationHeader = // Get the Authorization header from an HTTP request +const orgId = // get the orgId from somewhere, such as the request URL +try { + const user = await validateAccessTokenAndGetUserClass(authorizationHeader) + const org = user.getOrg(orgId) + if (!org) { + // return a 403 + } + console.log(`Got request from user ${user.userId} for org ${org.orgName}`); +} catch (err) { + // You can return a 401, or continue the request knowing it wasn't sent from a logged-in user + console.log(`Unauthorized request ${err}`); +} +``` + +### Check Org Membership and Role + +Similar to checking org membership, but will also verify that the user has a specific Role in the organization. + +A user has a Role within an organization. By default, the available roles are Owner, Admin, or Member, but these can be configured. These roles are also hierarchical, so Owner > Admin > Member. + +```ts +const authorizationHeader = // Get the Authorization header from an HTTP request +const orgId = // get the orgId from somewhere, such as the request URL +try { + const user = await validateAccessTokenAndGetUserClass(authorizationHeader) + const org = user.getOrg(orgId) + if (!org || !org.isRole("Admin")) { + // return a 403 + } + console.log(`Got request from Admin user ${user.userId} for org ${org.orgName}`); +} catch (err) { + // You can return a 401, or continue the request knowing it wasn't sent from a logged-in user + console.log(`Unauthorized request ${err}`); +} +``` + +### Check Org Membership and Permission + +Similar to checking org membership, but will also verify that the user has the specified permission in the organization. + +Permissions are arbitrary strings associated with a role. For example, `can_view_billing`, `ProductA::CanCreate`, and `ReadOnly` are all valid permissions. You can create these permissions in the PropelAuth dashboard. + +```ts +const authorizationHeader = // Get the Authorization header from an HTTP request +const orgId = // get the orgId from somewhere, such as the request URL +try { + const user = await validateAccessTokenAndGetUserClass(authorizationHeader) + const org = user.getOrg(orgId) + if (!org || !org.hasPermission("can_view_billing")) { + // return a 403 + } + console.log(`User ${user.userId} has 'can_view_billing' permissions for org ${org.orgName}`); +} catch (err) { + // You can return a 401, or continue the request knowing it wasn't sent from a logged-in user + console.log(`Unauthorized request ${err}`); +} +``` +--- + +## Calling Backend APIs + +You can also use the library to call the PropelAuth APIs directly, allowing you to fetch users, create orgs, and a lot more. + +```ts +const auth = initAuth({ + authUrl: 'REPLACE_ME', + apiKey: 'REPLACE_ME', +}) + +const magicLink = await auth.createMagicLink({ + email: 'user@customer.com', +}) +``` + +--- + ## Questions? Feel free to reach out at support@propelauth.com From 44a6177c5f547772abd3f837163d5983c3585eb0 Mon Sep 17 00:00:00 2001 From: pfvatterott Date: Thu, 27 Mar 2025 13:49:49 -0600 Subject: [PATCH 2/2] Added parent README --- README.md | 21 +++++++++++++++++++++ packages/cloudflare-worker/README.md | 2 +- 2 files changed, 22 insertions(+), 1 deletion(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e7e55cb --- /dev/null +++ b/README.md @@ -0,0 +1,21 @@ +

+ + + +

+ +# PropelAuth Node Libraries + +Javascript libraries for managing authentication, backed by [PropelAuth](https://www.propelauth.com?ref=github). + +[PropelAuth](https://www.propelauth.com?ref=github) makes it easy to add authentication and authorization to your B2B/multi-tenant application. + +Your frontend gets a beautiful, safe, and customizable login screen. Your backend gets easy authorization with just a few lines of code. You get an easy-to-use dashboard to config and manage everything. + +## [PropelAuth Node Library](https://github.com/PropelAuth/node/tree/main/packages/node) + +PropelAuth's Node library provides all the building blocks you need to add authentication to your Node projects. You should prefer the [Cloudflare Workers](https://docs.propelauth.com/reference/backend-apis/cloudflare-workers), [Express](https://docs.propelauth.com/reference/backend-apis/express), or [Next.js libraries](https://docs.propelauth.com/reference/fullstack-apis/nextjsapp/automatic-installation) if you are using those frameworks, as they provide a more first-class experience, however, this library can be used in any Node project. + +## [PropelAuth Cloudflare Worker Library](https://github.com/PropelAuth/node/tree/main/packages/cloudflare-worker) + +PropelAuth's Cloudflare Workers library makes it easy to add authentication and authorization to your [Cloudflare Workers](https://workers.cloudflare.com). \ No newline at end of file diff --git a/packages/cloudflare-worker/README.md b/packages/cloudflare-worker/README.md index 85abc22..0640b30 100644 --- a/packages/cloudflare-worker/README.md +++ b/packages/cloudflare-worker/README.md @@ -6,7 +6,7 @@ # PropelAuth Cloudflare Library -A Javascript library for managing authentication, backed by [PropelAuth](https://www.propelauth.com?ref=github). +A Javascript library for managing authentication, backed by [PropelAuth](https://www.propelauth.com?ref=github). While this library was built specifically with Cloudflare Workers in mind, it can also be used in edge/serverless contexts. [PropelAuth](https://www.propelauth.com?ref=github) makes it easy to add authentication and authorization to your B2B/multi-tenant application.