We are excited to announce the release of Exograph 0.4! This release introduces several new features and enhancements, many in response to our users' feedback (thank you!). While we will explore some of these features in future blogs, here is a quick summary of what's new since the 0.3 version.

NPM modules support​

Exograph offers a Deno integration to write custom business logic in TypeScript or JavaScript. Until now, you could only use Deno modules. While Deno modules ecosystem continues to expand, it is not as rich as the Node ecosystem. Recognizing this, Deno added support for NPM modules to tap into the vast range of NPM packages, and Exograph 0.4 extends this support through our integration. You can now harness NPM modules to checkout with Stripe, send messages with Slack, interact with AWS, and so on.

As an illustration, here is how you would send emails using Resend. First, you would define a mutation:

@deno("email.ts")
module Email {
  @access(true)
  mutation sendAnnouncement(): Boolean
}

And implement it using the resend NPM module:

import { Resend } from "npm:resend";

const resend = new Resend("re_...");

export async function sendAnnouncement(): Promise<boolean> {
  await resend.emails.send({
    from: "...",
    to: "...",
    subject: "Exograph 0.4 is out!",
    html: "<p>Exograph <strong>0.4</strong> is out with support for npm modules, playground mode, and more!</p>",
  });

  return true;
}

Compared to the example shown on the Resend site, the difference is the npm: prefix in the import statement. This prefix tells Exograph to look for the module in the npm registry.

Railway integration​

Exograph's deployment has always been easy since the server is just a simple binary with everything needed to run. However, we strive to make it easier for specific platforms. Exograph 0.4 now supports Railway as a deployment target! Here is a quick video where we create an Exograph project from scratch and deploy it to Railway in under three minutes.

To support this kind of integration, where the cloud platform can also run the build step, we now publish two Docker images: cli with the exo binary and server with the exo-server binary.

exo playground​

A recommended practice for GraphQL deployments is to turn off introspection in production, which is the default in Exograph. However, exploring the GraphQL API with such a server becomes difficult without code completion and other goodies. Exograph 0.4 introduces a new exo playground command that uses the schema from the local server and executes GraphQL operations against the specified remote endpoint.

exo playground --endpoint https://<server-url>/graphql
Starting playground server connected to the endpoint at: https://<server-url>/graphql
- Playground hosted at:
	http://localhost:9876/playground

You will see a UI element in the playground showing the specified endpoint. Besides this difference, the playground will behave identically to the local playground, including autocomplete, schema documentation, query history, and integrated authentication.

See the video with the Railway integration above for a quick demo of the exo playground command.

Access control improvements​

Exograph offers to express access control rules precisely. In version 0.4, we enhanced this expressive power through higher-order functions. Consider a document management system where users can read documents if they have read permissions and mutate if they have written permissions. The following access control rules express this requirement.

context AuthContext {
  @jwt("sub") id: Int
}

@postgres
module DocsDatabase {
  @access(
    query = self.permissions.some(permission => permission.user.id == AuthContext.id && permission.read),
    mutation = self.permissions.some(permission => permission.user.id == AuthContext.id && permission.write)
  )
  type Document {
    @pk id: Int = autoIncrement()
    ...
    permissions: Set<Permission>
  }

  @access(...)
  type Permission {
    @pk id: Int = autoIncrement()
    document: Document
    user: User
    read: Boolean
    write: Boolean
  }

  @access(...)
  type User {
    @pk id: Int = autoIncrement()
    ...
    permissions: Set<Permission>
  }
}

With this setup, no user can read or write a document without the appropriate permission. The some function allows you to express this requirement in a single line. Internally, it lowers it down to an SQL predicate for efficient execution.

Currently, we support the some higher-order function, which matches the Array.prototype.some function in Javascript. This function takes a predicate function and returns true if the predicate function returns true for any element in the array.

Other improvements​

Besides these major features, we continue to improve Exograph to fit more use cases and simplify the developer experience.

For the Postgres plugin, for example, you can now specify that the tables could be in a non-public schema and specify deeply nested creating and updates in a single mutation. It also allows clients to supply the primary key value for UUID fields when creating an entity.

In version 0.3, we introduced a friction-free integration with Clerk for authentication. Since then, we have extended this support to Auth0 as an authentication provider! While Exograph generically supports all compliant OIDC providers, the playground integration for Clerk and Auth0 makes it easy to try out APIs that require authentication. Along the way, we updated key rotation for the OIDC authentication mechanism.

Let us know what you think of these new features and what you would like to see in the future. You can reach us on Twitter or Discord.

On the heels of Clerk integration, we are excited to announce that Exograph now supports Auth0 as an authentication provider! Exograph's JWT support seamlessly works with Auth0 out of the box. Additionally, Exograph's playground integrates Auth0's authentication UI to simplify the exploration of access control rules.

Our code will be the same as in the previous blog. Since both Clerk and Auth0 support OpenID Connect (OIDC), everything can stay the same.

context AuthContext {
  @jwt("sub") id: String
}

@postgres
module TodoDatabase {
  @access(self.userId == AuthContext.id)
  type Todo {
    @pk id: Int = autoIncrement()
    title: String
    completed: Boolean
    userId: String = AuthContext.id
  }
}

This is all the code you need for a multi-user todo app! With the rule specified in the @access annotation, each user can only query or mutate their todos.

To try it out, create an Auth0 project following their instructions. Pay particular attention to configuring "Allowed Callback URLs" (for this blog, you may set it to http://localhost:9876/playground, http://localhost:3000).

Then you can start the server using exo yolo with the EXO_OIDC_URL environment variable set to your Auth0 URL:

EXO_OIDC_URL=https://<your-auth0-host>.auth0.com exo yolo

This will start the server with Auth0 as the authentication provider.

Auth0 integration with Exograph Playground

A typical workflow for building an app uses the GraphQL API in the playground to try out queries and mutations needed for the frontend and copy those into the frontend code. However, in the presence of authentication, grabbing a JWT token (typically from a partially built UI) and passing it in the Authorization header can be cumbersome. Exograph Playground makes it easy to try out APIs that require authentication by integrating Auth0's UI in the playground.

Try it out. For example, you can execute the following query to get all todos:

query {
  todos {
    id
    title
    completed
  }
}

If you do so without logging in, you will get an error:

{
  "errors": [
    {
      "message": "Not authorized"
    }
  ]
}

You can log in by clicking the "Authenticate" button in the playground. This will open Auth0's login page in the playground. You can log in using any configured provider (such as Google or Facebook). Once logged in, you can try the query again, and you will see the todos.

Similarly, you can execute mutations. For example, the following mutation will create a new todo:

mutation {
  createTodo(data: { title: "Buy milk", completed: false }) {
    id
  }
}

Due to access control rules, you can create a todo only for the logged-in user.

Lastly, try out the query above by logging in as another user. You will see that the todos created by the first user are not visible to the second user.

Using the frontend

With the confidence that the API works as expected, building a frontend using the same queries and mutations is easy. The accompanying source code is a Next.js app that allows creating todos, marking them as completed, and updating or deleting them.

Clone the examples repository and try it out!

Summary​

Combining the declarative backend of Exograph with the authentication of Auth0 is a simple matter of setting the EXO_OIDC_URL environment variable. The playground support makes it a breeze to try out various authentication scenarios to ensure that users access only the data they are supposed to.

We would love to hear your feedback on this integration on our Discord.

In a previous blog, our code used Google Identity for authentication. While such a solution is possible, taking care of details, such as supporting multiple social providers or password-less authentication, verifying emails, and refreshing/revoking tokens, can get tedious. This is where external authentication providers such as Clerk make life easier.

Exograph now supports Clerk as an authentication provider! Our integration goes beyond supporting JWKS authentication; it also makes it easy and fun to explore APIs by integrating Clerk's UI in Exograph's playground.

This blog will transform a todo app without authentication into a multi-user todo app by adding just four lines and modifying a single line of code! The accompanying source code includes a web frontend written in Next.js, Tailwind, Apollo GraphQL Client, and TypeScript.

A taste of Clerk integration​

Let's start with the same first step as the previous blog, with the code generated by the exo new command for a single-user todo project:

@postgres
module TodoDatabase {
  @access(true)
  type Todo {
    @pk id: Int = autoIncrement()
    title: String
    completed: Boolean
  }
}

If you start the server using exo yolo, you can explore the API in the playground to query, create, update, and delete todos.

To make this a multi-user app, we associate each Todo with a user and ensure that a user can only access their todos through the following changes:

context AuthContext {
  @jwt("sub") id: String
}

@postgres
module TodoDatabase {
  @access(self.userId == AuthContext.id)
  type Todo {
    @pk id: Int = autoIncrement()
    title: String
    completed: Boolean
    userId: String = AuthContext.id
  }
}

That's all we need to change! Compare this to other approaches where you would have to change most SQL statements or update invocation methods of an underlying framework besides including boilerplate code to deal with JWT verification.

Let's see what we did:

• A new AuthContext sources the user id from the JWT token's sub claim (which will be the same as Clerk's user id). The client will send the JWT token in the Authorization header, and Exograph will verify it using the API URL provided by Clerk.
• The Todo type adds a userId field. This field defaults to AuthContext's id value to let the client skip the user id when creating a todo.
• The access control rule enforces that users may query and mutate Todos only if their userId matches AuthContext's id.

Now that the backend is ready, let's explore the API.

Using the playground​

In a typical setup, the client will authenticate and send the Authorization token with each request. But how can you explore the API in the playground? How can you get a JWT token to put in the Authorization header? Developers often copy and paste the JWT token from the frontend app into the playground, which is a tedious process, to say the least (and requires building at least some frontend). It becomes even more challenging with providers such as Clerk, where the token expires quickly (by default, in 60 seconds).

Exograph integrates its playground with Clerk authentication (as well as roll-your-own, but that is not the focus of this blog). The playground includes the signing-in mechanism and automatically sends the Authorization header with the JWT for the signed-in user for each GraphQL request. In other words, the playground acts as an alternative frontend. You can now easily explore the API by, for example, signing in as different users and seeing how the access control rules work.

Let's try it out:

• Set up a Clerk project by following the instructions and note down the value for "Publishable key" and "JWT public key/JWKS URL" from the Clerk dashboard under the "API Keys" section.
• Start the Exograph server by specifying the OIDC URL as an environment variable. We will use the yolo command to start the server (you can also use the dev or production mode. See Exograph's documentation for more details).

EXO_OIDC_URL=https://<your-clerk-host>.clerk.accounts.dev exo yolo

• In the playground, click on the key icon in the middle of the screen. The first time you open it, it will ask for the "Publishable key" you noted earlier. You may specify the template id but don't need it for this application. If you want to change this information, you can do it through the "Configure Clerk" link in the sign-in dialog.
• You will see the sign-in dialog once you specify the publishable key.
• Once you sign in, you will see the user's profile picture near the key icon to indicate the currently signed-in user.

Try various queries and mutations. For example, create a todo:

mutation {
  createTodo(data: { title: "Buy milk", completed: true }) {
    id
    title
    completed
  }
}

Or query the todos:

query {
  todos {
    id
    title
    completed
  }
}

Please see the earlier blog for a list of queries and mutations to try.

Now log out and try the same queries and mutations. You will get an error when you try to create a todo (unauthenticated users can't create todos). You will also see that you don't see any todos when you query them (users can see only their todos). Login as another user; as you would expect, you won't see the todos created by the first user.

Using the frontend​

Once you have explored the API, building a frontend using the same queries and mutations is easy. The accompanying source code is a Next.js app that allows creating todos, marking them as completed, and updating or deleting them.

You can sign in as different users and see how the access control rule works (one user will not be able to see or change another user's todos).

Summary​

Combining the declarative backend of Exograph with the authentication of Clerk was a breeze. It took us just four lines of code and a single-line modification to the model to make the todo app multi-user. The integration with Clerk's UI in the playground makes it easy to explore the API without building a frontend.

There is more that we didn't explore here, such as using custom templates. For example, we could use these to implement role-based access control to allow admins to see all todos. All we would have to change is add one line to the context (@jwt role: String) and modify another to add || AuthContext.role == "admin" to the access control rule! Such is the power of Exograph's declarative modeling and access control expressions. Please see the documentation for more details.

We would love to hear your feedback on this integration on our Discord.

Mercury going retrograde is a serious affair, at least according to Reddit discussions. Mercury being the God of communication, supposedly, its (apparent) retrograde movement causes communication breakdowns leading to network outages, server crashes, data loss, and so on. Some take it quite seriously. There is even a Zapier integration to notify you in Slack when Mercury is about to retrograde. Well, it is about to happen tomorrow! So let me hurry up and publish this post before it is too late 😄.

In the previous blog, we dealt with access control to express the ownership relation: a todo must be accessible to only those who own it, with some role-based exceptions. However, sometimes you need to go beyond role-based and ownership-based rules. Rather than supporting specific authorization policies that eventually prove too limiting, Exograph takes a different approach through its context mechanism. This mechanism opens the door to implementing even esoteric rules, such as "no deployment when Mercury is retrograde".

Setting up the context​

Implementing such a rule in Exograph requires introducing a new context whose field represents Mercury's retrograde status. In Exograph, a context represents information extracted from the incoming request (headers, cookies, IP address) and the environment variables. Exograph includes a general mechanism where users can write custom code to populate the context. That is what we will use to implement the Mercury retrograde rule.

To implement custom context extraction logic, you need to:

• Write a GraphQL query to return the computed value of interest (in our case, whether Mercury is retrograde)
• Use the @query annotation to bind the value of the query to a context field (in our case, a boolean field)

Let's start by writing TypeScript code to determine if Mercury is retrograde. We will use https://mercuryretrogradeapi.com/ for that (quite an interesting service deployed to 5+ geographically distributed servers!).

export function isMercuryRetrograde(): bool {
  let result = await fetch("https://mercuryretrogradeapi.com");
  let json = await result.json();
  return json.is_retrograde;
}

Then, we need to bind this query to a context field. We will use the @query annotation to do that.

@deno("astro.ts")
module AstroModule {
  query isMercuryRetrograde(): bool
}

context AstroContext {
  @query("isMercuryRetrograde") mercuryRetrograde: bool
}

Here, the AstroModule exposes a single isMercuryRetrograde query that returns a boolean value. We use this query to populate the mercuryRetrograde context variable.

Expressing access control rules​

Finally, let's write an example resource—Deployment—that we want to protect against mercury's shenanigans. We do now want any mutations to Deployment when Mercury is retrograde.

@postgres
module DeploymentModule {
  @access(query = true, mutation = !AstroContext.mercuryRetrograde)
  type Deployment {
    @pk id: Int = autoIncrement()
    version: String
  }
}

Here, we allow anyone to query the deployment. But we disallow mutations when Mercury is retrograde (you could combine this with other rules, for example, to restrict mutations to admin users only).

Testing the rule​

Let's start the server:

exo yolo

You will see output similar to this:

...
Started server on localhost:9876 in 5.35 ms
- Playground hosted at:
        http://localhost:9876/playground
- Endpoint hosted at:
        http://localhost:9876/graphql

Visit the playground URL and try to create a new deployment:

mutation {
  createDeployment(data: { version: "1" }) {
    id
  }
}

If you try it while Mercury is not retrograde, it will succeed.

{
  "data": {
    "createDeployment": {
      "id": 1
    }
  }
}

But if you try it while Mercury is retrograde (the next such thing will happen between August 23, 2023 and September 14, 2023), you will get an error:

{
  "errors": [
    {
      "message": "Not authorized"
    }
  ]
}

The same thing will happen if you try to update or delete the deployment:

mutation {
  updateDeployment(id: 1, data: { version: "2" }) {
    id
    version
  }
}

mutation {
  deleteDeployment(id: 1) {
    id
  }
}

There is no escaping the access rule!

Conclusion​

This fun little exercise shows how Exograph can be used to implement flexible access control rules. Besides built-in context sources, such as the JWT token, header, cookie, and environment variable, Exograph allows sourcing rules from a query implemented using Typescript/JavaScript running in Deno. This separation of context extraction logic from access control expressions enables easy implementation of even weird rules in Exograph.

What's next? Does someone want to implement "No Friday the 13th" rule? Or "No full moon" rule? Or "No deployment on the day of the week that ends with 'y'" rule? Exograph got you covered!

Applications, like ideas, begin small and grow over time. Initially, an app might be a single-user demo for your next unicorn startup. If it resonates with your user base, the natural progression involves scaling it to accommodate multiple users. At this point, you need authentication, access control, and administrative functionality.

Adapting your domain model to new requirements is essential and Exograph provides robust support for this process. As your domain evolves, you can easily update the Exograph model to match it. As the model changes, the GraphQL API is automatically synchronized with the model. Exograph also helps manage database migrations. As changes in access control demands arise, you can easily represent them in your model. Additionally, Exograph enables declarative testing, minimizing the risk of regressions as adaptations unfold.

In this blog, we will focus on how Exograph streamlines the evolution of access control rules. We will develop a todo app from scratch starting with a single-user application with no authentication. We will then migrate it into a multi-user platform—complete with authentication and access control. We will see how Exograph makes this transition seamless.

The accompanying code (simple, with authentication) includes a frontend implemented with Next.js, Tailwind, Apollo GraphQL Client, and TypeScript.

Building the single-user version​

Let's create an app with no authentication and wide-open access control. Running the following commands is all we need to create the backend:

Creating the project​

mkdir todo-app
cd todo-app
exo new api

The starter code defines a single type Todo with a permissive @access(true) policy that allows anyone to query or mutate todos. This access control rule may be acceptable for a local single-user todo app, but not much beyond that. We will fix that in the next section.

@postgres
module TodoDatabase {
  @access(true)
  type Todo {
    @pk id: Int = autoIncrement()
    title: String
    completed: Boolean
  }
}

Now let's start the backend to explore the GraphQL API:

cd api
exo yolo

The server is now ready 🚀.

Exploring the API​

Our goal is to build a frontend that allows us to create, update, and delete todos. It also shows todos by their completion status. Let's see how we can achieve this with the GraphQL API.

Open http://localhost:9876/graphql to try the GraphQL playground.

Creating todos​

Let's create a todo. We can do that with the following mutation:

mutation createTodo($title: String!, $completed: Boolean!) {
  createTodo(data: { title: $title, completed: $completed }) {
    id
    title
    completed
  }
}

Paste the above code in the playground. In the Variables tab, add the following JSON:

{
  "title": "Buy milk",
  "completed": false
}

Now, execute the mutation by clicking on the Play button. You should see the following response:

{
  "data": {
    "createTodo": {
      "id": "1",
      "title": "Buy milk",
      "completed": false
    }
  }
}

Create a couple more todos with different titles and completion status.

Updating todos​

The frontend will also need to update todos. We can achieve this through the following mutation:

mutation updateTodo($id: Int!, $title: String, $completed: Boolean) {
  updateTodo(id: $id, data: { title: $title, completed: $completed }) {
    id
    title
    completed
  }
}

Note that the id is required, but title and completed are optional (since we may want to update either). Try updating the title and completion status of a few todos.

Deleting todos​

Deleting a todo is easy with the following mutation:

mutation deleteTodo($id: Int!) {
  deleteTodo(id: $id) {
    id
  }
}

Listing todos​

Getting all todos is trivial:

query allTodos {
  todos {
    id
    title
    completed
  }
}

Getting todos by their completion status isn't much harder:

query todosByCompletionStatus($completed: Boolean!) {
  todos(where: { completed: { eq: $completed } }) {
    id
    title
    completed
  }
}

This is the complete set of GraphQL operations we need to build the frontend. At this point, you may want to check out the repository and run the frontend to see how it works.

Let's move on to the next section to see how to evolve this app to support multiple users.

The multi-user version​

The declarative nature of Exograph makes it easy to evolve the model and access control rules as the application grows. In our application, we need to:

• Add a User type and introduce a relationship between Todo and User. Adding a relationship in Exograph is as easy as adding a field.
• Add access control such that:
  • Users can only query or mutate todos that they own. However, we will make an exception for the omnipotent admins to do anything.
  • Only admins can query or mutate users.

Updating the model​

We can express the above requirements by updating the model as follows:

context AuthContext {
  @jwt("sub") id: Int
  @jwt("role") role: String
}

@postgres
module TodoDatabase {
  @access(self.user.id == AuthContext.id || AuthContext.role == "admin")
  type Todo {
    @pk id: Int = autoIncrement()
    title: String
    completed: Boolean
    user: User = AuthContext.id
  }

  @access(AuthContext.role == "admin")
  type User {
    @pk id: Int = autoIncrement()
    @unique email: String
    firstName: String
    lastName: String
    profileImageUrl: String
    role: String = "user"
    todos: Set<Todo>?
  }
}

Let's unpack the changes we have made:

1. Introduce the User type: We introduce a User type to represent the owner of todos (#17).
2. Establishing relationships: User needs to own Todos, so we set up a one-to-many relationship with Todo by adding a todos field (#24). We also add a user field to Todo to establish the reverse relationship (#13).
3. Establishing context: We need to know who is accessing the APIs. Therefore, we introduce AuthContext with the id and role fields sourced from the incoming JWT token (#1-#4).
4. Securing todos: Since we want each Todo to be accessed only by its owner, we express this using self.user.id == AuthContext.id. Here self refers to the current object, which is a Todo. We also added || AuthContext.role == "admin" to allow admins to do anything (#8).
5. Securing users: The rule for User is even simpler: only admins can query or mutate users (#16).
6. Setting defaults: Notice the default value of the user is set to AuthContext.id (#13). This allows the user to create a todo without explicitly specifying the user argument to the createTodo mutation (Exograph will automatically associate the current user with the created todo).This also ensures that the queries and mutations used in the single-user version will continue to work unchanged (where specifying the user wasn't even an option). We also set the role field to "user" by default (#23).

Exploring the API​

Let's try it out. Exograph's playground makes it easy to create authorization tokens for various users to test scenarios with various users.

1. Open the playground at http://localhost:9876/graphql.
2. Click on the Authentication sidebar on the left.
3. Fill in the JWT secret and the payload and hit the "Update Authorization Token" button.

{
  "role": "admin"
}

This will update the Authorization header with a JWT token. Let's create two users:

mutation {
  u1: createUser(
    data: {
      email: "[email protected]"
      firstName: "F1"
      lastName: "L1"
      profileImageUrl: "https://example.com/1.jpg"
    }
  ) {
    id
  }
  u2: createUser(
    data: {
      email: "[email protected]"
      firstName: "F2"
      lastName: "L2"
      profileImageUrl: "https://example.com/2.jpg"
    }
  ) {
    id
  }
}

Since we are running this as an admin, Exograph allows it. (Try updating the role field in the payload to user and see what happens.)

Now go back to the Authentication sidebar and update the payload:

{
  "sub": 1,
  "role": "user"
}

Now create a few todos for this user. Try to query all the todos (or completed/incomplete todos). You will see only the todos that you created.

Let's repeat the process for another user. Update the sub field in the payload to 2 and try the same operations, but buy items for a different breakfast to tell them apart. Maybe "Buy cereal", "Buy orange juice", and "Buy coffee"?

You can already see that the access control rules are working. Let's try to have one user update another user's todo. Still as user 2, try to update an todo created by user 1:

mutation updateTodo {
  updateTodo(id: 1, data: { title: "Don't buy", completed: true }) {
    id
    title
    completed
  }
}

Since the access control rule for Todo won't allow this operation, you will get back an empty response.

Play around with the playground to see how the access control rules work. You will see that no one can query or mutate users except the admin. Users can query or mutate only their todos (admins can do anything). And all we needed to express this was a few lines of declarative code.

Conclusion

In this blog, we've explored the ease with which Exograph allows refining our application's access control rules as it scales. By adjusting a few lines, we can seamlessly adapt to new demands. Experimenting with these changes within the playground gives you confidence in your rules. Notably, the rules are clear and simple expressions. This makes it easy to reason about them and to communicate them with others.