DEV Community: Ken Fukuyama

Demystifying Playwright Test Agents' seed.spec.ts: What I Learned from Reading the MCP Code

Ken Fukuyama — Fri, 05 Dec 2025 05:14:20 +0000

Introduction

I recently had a chance to try out Playwright Test Agents, and I'm impressed—this feels like a powerful new tool that could genuinely change how we approach E2E test creation and maintenance.

In this article, I'll dig into something that tripped me up when using Playwright Test Agents: the role of seed.spec.ts. The official documentation didn't make it immediately clear to me, so I ended up reading the MCP source code to understand how it actually works. I'll walk you through what I learned.

Note: This article assumes you have some familiarity with Playwright Test Agents. If you haven't tried it yet, you can still follow along and understand what seed.spec.ts does, but I'd recommend watching the video above first for deeper context. It's mainly in Japanese, but you can get the idea from the English auto dubs.

Where the Official Docs Left Me Confused

The first thing that confused me when starting with Playwright Test Agents was seed.spec.ts.

Looking at the official documentation (as of December 4, 2025), there's just this one line:

Seed tests provide a ready-to-use page context to bootstrap execution.

Now that I understand how it works, this makes perfect sense. But when I first read it, I honestly had no idea what it meant.

Specifically, what wasn't clear:

Whose ready-to-use page context?
Who is doing the bootstrap execution?

The missing subjects make this sentence vague. Is this about Playwright's test execution, or something specific to the Agents feature?

Reading the MCP Code

Since staring at the documentation wasn't getting me anywhere, I decided to look at the actual MCP (Model Context Protocol—the standard protocol for AI agents to call tools) code.

Checking the Agent Prompts

The key is in the two agent configuration files generated by the initialization command:

npx playwright init-agents --loop=vscode

Running this command generates:

playwright-test-planner.md
playwright-test-generator.md

Looking at the Planner's prompt, I found this:

1. **Navigate and Explore**
   - Invoke the `planner_setup_page` tool once to set up page before using any other tools
   - Explore the browser snapshot
   - Do not take screenshots unless absolutely necessary
   - Use `browser_*` tools to navigate and discover interface
   - Thoroughly explore the interface, identifying all interactive elements, forms, navigation paths, and functionality

The important part: it instructs the agent to use the planner_setup_page tool.

Checking the Generator similarly:

# For each test you generate
- Obtain the test plan with all the steps and verification specification
- Run the `generator_setup_page` tool to set up page for the scenario

This one uses generator_setup_page.

Looking at the MCP Tool Implementation

So what do these tools actually do? Let's look at the implementation:

https://github.com/microsoft/playwright/blob/f9e1797a0d6025a0cc499692d79bb10a806eadc1/packages/playwright/src/mcp/test/plannerTools.ts#L23C14-L40

export const setupPage = defineTestTool({
  schema: {
    // Tool name from the prompt
    name: 'planner_setup_page',
    title: 'Setup planner page',
    description: 'Setup the page for test planning',
    inputSchema: z.object({
      project: z.string().optional().describe('Project to use for setup. For example: "chromium", if no project is provided uses the first project in the config.'),
      // Uses seed.spec.ts as seedFile by default
      seedFile: z.string().optional().describe('A seed file contains a single test that is used to setup the page for testing, for example: "tests/seed.spec.ts". If no seed file is provided, a default seed file is created.'),
    }),
    type: 'readOnly',
  },

  handle: async (context, params) => {
    const seed = await context.getOrCreateSeedFile(params.seedFile, params.project);
    // It runs seed.spec.ts first
    const { output, status } = await context.runSeedTest(seed.file, seed.projectName);
    return { content: [{ type: 'text', text: output }], isError: status !== 'paused' };
  },
});

The crucial part is context.runSeedTest(). Before the Planner or Generator does its job, it first executes seed.spec.ts.

Mystery Solved: What seed.spec.ts Really Is

With this understanding, the documentation quote becomes crystal clear:

Seed tests provide a ready-to-use page context to bootstrap execution.

In other words:

Whose ready-to-use page context? → For the Planner and Generator (AI agents)
Who does the bootstrap execution? → The Planner and Generator run it

So seed.spec.ts isn't a seed file for Playwright tests—it's a setup file that runs before the Planner or Generator starts navigating and exploring the browser.

What Should Go in seed.spec.ts

Given this mechanism, in most cases your seed.spec.ts should include:

Login procedures for the user you want the Planner/Generator to explore as
Data seeding or environment initialization needed for planning/generation

For example, if you want to generate tests for an admin panel, you can log in as an admin in seed.spec.ts, and the Planner will start exploring from that logged-in state.

Here's a concrete example:

import { test, expect } from '@playwright/test';

const authFile = 'playwright/.auth/user.json';
const testUsername = 'testuser';

test.describe('Test group', () => {
  // request is Playwright's APIRequestContext
  // https://playwright.dev/docs/api/class-apirequestcontext
  test('seed', async ({ page, request }) => {
    // Navigate to login page
    await page.goto('/');

    // Fill in login form
    await page.getByLabel('Username').fill(testUsername);
    await page.getByLabel('Password').fill('password123');
    await page.getByRole('button', { name: 'Login' }).click();

    // Verify successful login
    await expect(page).toHaveURL('/products');

    // Reset user data for testing
    // Note: This assumes your app has a test data reset API
    // In real projects, implement your own initialization logic as needed
    const resetResponse = await request.post('/api/test/reset', {
      data: { username: testUsername },
    });
    expect(resetResponse.ok()).toBeTruthy();

    // Save login state
    await page.context().storageState({ path: authFile });
  });
});

This way, you put any necessary preparation—login procedures, test data resets, etc.—in seed.spec.ts before the agent starts exploring.

How Is This Different from Existing Setup/Fixtures?

At this point, I had a question:

"Wait, doesn't Playwright already have similar mechanisms?"

Global Setup / Teardown

Playwright has documented best practices for setup:

https://playwright.dev/docs/test-global-setup-teardown

Fixtures

There's also the Fixtures concept for writing robust tests:

https://playwright.dev/docs/test-fixtures

The Critical Difference

These mechanisms serve fundamentally different purposes from seed.spec.ts.

Mechanism	For Whom	When It Runs
Global Setup	Test execution	When `npx playwright test` runs
Fixtures	Test execution	When each test runs
seed.spec.ts	AI Agents	When Planner/Generator launches

seed.spec.ts isn't executed by Playwright's test runner—it's executed by AI agents via MCP tools. It runs on a completely separate lifecycle from test execution.

About Comments in Generated Code

Another source of confusion was the comments in test code generated by the Planner/Generator:

// spec: specs/basic-operations.md
// seed: tests/seed.spec.ts  // <-- This comment was misleading

import { test, expect } from '../fixtures';

test.describe('Adding New Todos', () => {
  test('Add Valid Todo', async ({ page }) => {
    // 1. Click in the "What needs to be done?" input field
    const todoInput = page.getByRole('textbox', { name: 'What needs to be done?' });
    // ...
  });
});

Seeing // seed: tests/seed.spec.ts, I wondered: "Does this comment somehow trigger seed.spec.ts to run during Playwright test execution?"

Turns out, this comment is just metadata. It records which seed file was used to generate the test, but doesn't cause any special behavior during test execution.

No magical new features here—it's simply recording "this test was generated using this seed environment."

How This Might Work in Mid-to-Large Scale Projects (Hypothesis)

Warning: This section is speculative. I haven't actually verified this in practice, so take it as food for thought.

With this understanding, I can imagine how this could work in medium to large projects.

Using Multiple Seed Files

Looking at the MCP tool implementation, we saw that a seedFile parameter can be passed. Taking advantage of this, you could create multiple seed files for different actors or use cases:

tests/
├── seeds/
│   ├── admin-seed.spec.ts      # Logged in as admin
│   ├── member-seed.spec.ts     # Logged in as regular member
│   ├── guest-seed.spec.ts      # Not logged in
│   └── checkout-seed.spec.ts   # Cart has items
└── ...

When launching the Planner/Generator, you could specify the appropriate seed file for your purpose, enabling more efficient test planning and generation.

Pros and Cons

Pros

Skip repetitive operations like login procedures in each exploration session
Start test generation from specific states (e.g., items in cart)
Separate test generation starting points by actor (admin/regular user/guest)

Cons

Need to manage seed files (must keep them in sync with app changes)
Maintenance cost for seed files themselves (this is unavoidable)
With multiple seed files, you need to decide which one to use (also unavoidable for complex apps)

It's not a silver bullet, but used appropriately, it could significantly improve test generation efficiency.

Summary

In this article, I've explored the role of seed.spec.ts in Playwright Test Agents.

Key Points

seed.spec.ts is for the AI agents (Planner/Generator), not for Playwright tests
It runs when agents launch via MCP tools, not during Playwright test execution
It serves a different purpose and lifecycle from existing Global Setup and Fixtures
The // seed: ... comment in generated tests is just metadata

The feature is still new, so documentation hasn't fully caught up yet. But by reading the MCP code, I was able to understand how it works, and now I can use it confidently.

Either way, Playwright Test Agents has the potential to make working with E2E tests more enjoyable if used well. I'm excited to see how it evolves!

Deciphering GraphQL: A Deep Dive into Type Merging and Schema Stitching

Ken Fukuyama — Wed, 27 Sep 2023 02:30:07 +0000

Recently, I've been studying GraphQL Stitching, and no matter how many times I read about Type Merging, it didn't quite click. So, I made an effort to fully understand it.

The official documentation for Type Merging can be found here:

https://the-guild.dev/graphql/stitching/docs/approaches/type-merging

Assumptions for this article

In this article, I won't be explaining what GraphQL Gateway or GraphQL Stitching are. 🙏 There are plenty of good articles explaining those aspects, so I recommend checking them out first.

For reference, the official documentation can be found here:

https://the-guild.dev/graphql/stitching

Type Merging in GraphQL Stitching

What is Type Merging?

To put it succinctly, Type Merging is a mechanism that allows us to treat multiple schemas defining the same type as if they were just one type.

For example, let's say there's a GraphQL Gateway, and behind it, there are GraphQL servers handling manufacturers, products, and storefronts.

Although the servers are separate, you'll notice that types like Product and Manufacturer are defined on each. These can be merged, and the Gateway can provide the following schema:

type Query {
  manufacturer(id: ID!): Manufacturer
  product(upc: ID!): Product
  _manufacturer(id: ID!): Manufacturer
  storefront(id: ID!): Storefront
}

type Manufacturer {
  id: ID!
  name: String!  # From the manufacturers schema
  products: [Product]!  # From the products schema
}

type Product {  # Mainly from the products schema
  upc: ID!
  name: String!
  price: Float!
  manufacturer: Manufacturer
}

type Storefront {  # From the storefronts schema
  id: ID!
  name: String!
  products: [Product]!
}

Up to this point, it's relatively intuitive, but the "How do we merge?" part felt somewhat elusive when I read the documentation. I kept reading and forgetting, so I decided to take a closer look at the official sample's inner workings.

https://github.com/ardatan/schema-stitching/tree/master/examples/type-merging-single-records

Verifying the Merging Flow in practice

When you check the official documentation's MergingFlow, there's a diagram and a description of each step, explaining how the merging happens.

The diagram slightly omits certain explanations, making it somewhat challenging to grasp at a glance.

Thus, I visualized the flow in more detail using the Storefront, Product, and Manufacturer examples. (For a fullscreen view, click here).

Let's go through the steps.

1. Client request

The client sends a request.

Since the Gateway schema matches the one mentioned above, this is a regular GraphQL query, simply requesting the desired data.

2. The original request goes to the storefront server

Next, since the request is intended for the storefront, it's sent there via the gateway. At this point, the gateway filters the query, sending only the parts relevant to the storefront. The storefront only understands the Product type with just the upc, so the original query's name and manufacturer are omitted.

However, if we only had this, we'd lose the information we want to retrieve from the products, and we wouldn't be able to fetch data from the other servers. This is where selectionSet comes in. Citing the official documentation:

selectionSet specifies one or more key fields required from other services to perform this query. Query planning will automatically resolve these fields from other subschemas in dependency order.

In essence, it's declaring, "To get data for type ○○, we at least need △△ information." In this case, the products server has a configuration like:

merge: {
  Product: {
    // This service provides _all_ unique fields for the `Product` type.
    // Again, there's unique data here so the gateway needs a query configured to fetch it.
    // This config delegates to `product(upc: $upc)`.
    selectionSet: '{ upc }',
    fieldName: 'product',
    args: ({ upc }) => ({ upc }),
  },
},

You can see a selectionSet of { upc }. It's declaring, "When merging data for the Product type, we need the upc." Having this information, the gateway implicitly adds upc when sending a request to the storefront server. Checking the actual query log confirms the presence of upc.

3. Response from storefront

From the previous request, the response from the storefront is as follows:

4. Creation of the merger query

Once the storefront responds, the next step is to send a request to the products server. Someone responsible for merging (let's call them the "merger") sends the query, utilizing the merge setting.

Here, the products server's merge setting specified for the gateway is in focus. Particularly, note the fieldName and args. This means that when merging the Product type, the server uses its product query, and for the argument, it uses the originating object's upc property.

It's a bit tricky, but the relationship is as shown below:

Using this information, the query for step 5 is generated.

5. Request to the products

server

Based on the information from step 4, a query is generated for the products server, which looks like this:

Thanks to the args definition, the upc is injected with the value 6.

From here on, it becomes repetitive, but only the query aspects that the products server can handle are filtered. The original query requested the manufacturer's name and products, but the products server isn't aware of the name property.

Thus, name is omitted.

For the Manufacturer type, there's a selectionSet of { id } set for the manufacturer server, as seen below:

merge: {
  // This schema provides one unique field of data for the `Manufacturer` type (`name`).
  // The gateway needs a query configured so it can fetch this data...
  // this config delegates to `manufacturer(id: $id)`.
  Manufacturer: {
    selectionSet: '{ id }',
    fieldName: 'manufacturer',
    args: ({ id }) => ({ id }),
  },
},

This is implicitly injected into the query, as can be seen from the actual request below:

6. Response from products

From the previous request, the response from the products is as follows:

7,8,9. Similar requests are sent to the manufacturer server

I'll skip the details for the manufacturer server request, as it's repetitive. It looks like this (for a full view, click here):

10,11. All results are merged into the appropriate type and returned

Finally, all the results are merged, and the client receives the response they requested.

Conclusion

After delving deeper than the official documentation, I feel like I've come to grasp Type Merging much better. I particularly had a hard time understanding selectionSet, but seeing the actual requests helped me understand its implicit injection.

While I only touched on a small part about GraphQL Gateway, I believe others might also struggle to understand Type Merging, so I hope this article helps someone out there.

Upgrading from graphql-yoga v2 to v4

Ken Fukuyama — Wed, 13 Sep 2023 04:59:25 +0000

Key Points on Upgrading from graphql-yoga v2 to v4

This article outlines a tricky point when upgrading graphql-yoga v2 to v4. For a comprehensive migration guide, please refer to the official migration guide.

1. Removal of `endpoint` and `graphiql.endpoint` options

One of the significant changes in v4 is the removal of the endpoint and graphiql.endpoint options. This can have implications, especially for those using express alongside.

2. Changes in the Configuration Approach

The configuration method in v2 was as follows:

const graphQLServer = createServer({
  //... previous configuration details
})

In v4, the new configuration method is:

const graphQLServer = createYoga({
  schema: createSchema({
    //... new configuration details
  }),
});

3. Changes regarding the Endpoint

In v4, the default endpoint is set to /graphql. If you want to use an alternate endpoint, you'll need to explicitly specify it using the graphqlEndpoint option.

For instance, in v2, setting the endpoint to /graphql-other worked seamlessly:

//... 
app.use('/graphql-other', graphQLOtherServer);

However, with the same setup in v4, you would encounter a NOT FOUND error.

The solution is:

const graphQLOtherServer = createYoga({
  graphqlEndpoint: '/graphql-other', // explicitly setting the endpoint
  //... other configurations
});

app.use('/graphql-other', graphQLOtherServer);

This change can be a bit tricky, so it's crucial to be aware to avoid potential pitfalls during the upgrade.

I hope this sheds light on some nuances of the upgrade process and helps you navigate any challenges smoothly.

Cross Module Transaction with Prisma

Ken Fukuyama — Tue, 14 Jun 2022 13:14:22 +0000

TL;DR

It's possible to write transactions in the application layer using Prisma with the help of cls-hooked
- Here's some sample codes
The PoC code: https://github.com/kenfdev/prisma-auto-transaction-poc

Prisma and Interactive Transaction

There's no doubt that Prisma boosts your productivity when dealing with Databases in Node.js + TypeScript. But as you start creating complex software, there are some cases you can't use Prisma the way you'd like to out of the box. One of them is when you want to use the interactive transaction across modules.

What I mean by cross module is a bit obscure. Let's look at how you can write interactive transactions in Prisma. The following code is from the official docs.



await prisma.$transaction(async (prisma) => {
  // 1. Decrement amount from the sender.
  const sender = await prisma.account.update({
    data: {
      balance: {
        decrement: amount,
      },
    },
    where: {
      email: from,
    },
  })
  // 2. Verify that the sender's balance didn't go below zero.
  if (sender.balance < 0) {
    throw new Error(`${from} doesn't have enough to send ${amount}`)
  }
  // 3. Increment the recipient's balance by amount
  const recipient = prisma.account.update({
    data: {
      balance: {
        increment: amount,
      },
    },
    where: {
      email: to,
    },
  })
  return recipient
})

The point is that you call prisma.$transaction and you pass a callback to it with the parameter prisma. Inside the transaction, you use the prisma instance passed as the callback to use it as the transaction prisma client. It's simple and easy to use. But what if you don't want to show the prisma interface inside the transaction code? Perhaps you're working with a enterprise-ish app and have a layered architecture and you are not allowed to use the prisma client in say, the application layer.

It's probably easier to look at it in code. Suppose you would like to write some transaction code like this:



await $transaction(async () => {
  // call multiple repository methods inside the transaction
  // if either fails, the transaction will rollback
  await this.orderRepo.create(order);
  await this.notificationRepo.send(
    `Successfully created order: ${order.id}`
  );
});

There are multiple Repositories that hide the implementation details(e.g. Prisma, SNS, etc.). You would not want to show prisma inside this code because it is an implementation detail. So how can you deal with this using Prisma? It's actually not that easy because you'll somehow have to pass the Transaction Prisma Client to the Repository across modules without explicitly passing it.

Creating a custom TransactionScope

This is when I came across this issue comment. It says you can use cls-hooked to create a thread-like local storage to temporarily store the Transaction Prisma Client, and then get the client from somewhere else via CLS (Continuation-Local Storage) afterwards.

After looking at how I can use cls-hooked, here is a TransactionScope class I've created to create a transaction which can be used from any layer:



export class PrismaTransactionScope implements TransactionScope {
  private readonly prisma: PrismaClient;
  private readonly transactionContext: cls.Namespace;

  constructor(prisma: PrismaClient, transactionContext: cls.Namespace) {
    // inject the original Prisma Client to use when you actually create a transaction
    this.prisma = prisma;
    // A CLS namespace to temporarily save the Transaction Prisma Client
    this.transactionContext = transactionContext;
  }

  async run(fn: () => Promise<void>): Promise<void> {
    // attempt to get the Transaction Client
    const prisma = this.transactionContext.get(
      PRISMA_CLIENT_KEY
    ) as Prisma.TransactionClient;

    // if the Transaction Client
    if (prisma) {
      // exists, there is no need to create a transaction and you just execute the callback
      await fn();
    } else {
      // does not exist, create a Prisma transaction 
      await this.prisma.$transaction(async (prisma) => {
        await this.transactionContext.runPromise(async () => {
          // and save the Transaction Client inside the CLS namespace to be retrieved later on
          this.transactionContext.set(PRISMA_CLIENT_KEY, prisma);

          try {
            // execute the transaction callback
            await fn();
          } catch (err) {
            // unset the transaction client when something goes wrong
            this.transactionContext.set(PRISMA_CLIENT_KEY, null);
            throw err;
          }
        });
      });
    }
  }
}

You can see that the Transaction Client is created inside this class and is saved inside the CLS namespace. Hence, the repositories who want to use the Prisma Client can retrieve it from the CLS indirectly.

Is this it? Actually, no. There's one more point you have to be careful when using transactions in Prisma. It's that the prisma instance inside the transaction callback has different types than the original prisma instance. You can see this in the type definitions:



export type TransactionClient = Omit<PrismaClient, '$connect' | '$disconnect' | '$on' | '$transaction' | '$use'>

Be aware that the $transaction method is being Omitted. So, you can see that at this moment you cannot create nested transactions using Prisma.

To deal with this, I've created a PrismaClientManager which returns a Transaction Prisma Client if it exists, and if not, returns the original Prisma Client. Here's the implementation:



export class PrismaClientManager {
  private prisma: PrismaClient;
  private transactionContext: cls.Namespace;

  constructor(prisma: PrismaClient, transactionContext: cls.Namespace) {
    this.prisma = prisma;
    this.transactionContext = transactionContext;
  }

  getClient(): Prisma.TransactionClient {
    const prisma = this.transactionContext.get(
      PRISMA_CLIENT_KEY
    ) as Prisma.TransactionClient;
    if (prisma) {
      return prisma;
    } else {
      return this.prisma;
    }
  }
}

It's simple, but notice that the return type is Prisma.TransactionClient. This means that the Prisma Client returned from this PrismaClientManager always returns the Prisma.TransactionClient type. Therefore, this client cannot create a transaction.

This is the constraint I made in order to achieve this cross module transaction using Prisma. In other words, you cannot call prisma.$transaction from within repositories. Instead, you always use the TransactionScope class I mentioned above.

It will create transactions if needed, and won't if it isn't necessary. So, from repositories, you can write code like this:



export class PrismaOrderRepository implements OrderRepository {
  private readonly clientManager: PrismaClientManager;
  private readonly transactionScope: TransactionScope;

  constructor(
    clientManager: PrismaClientManager,
    transactionScope: TransactionScope
  ) {
    this.clientManager = clientManager;
    this.transactionScope = transactionScope;
  }

  async create(order: Order): Promise<void> {
    // you don't need to care if you're inside a transaction or not
    // just use the TransactionScope
    await this.transactionScope.run(async () => {
      const prisma = this.clientManager.getClient();
      const newOrder = await prisma.order.create({
        data: {
          id: order.id,
        },
      });

      for (const productId of order.productIds) {
        await prisma.orderProduct.create({
          data: {
            id: uuid(),
            orderId: newOrder.id,
            productId,
          },
        });
      }
    });
  }
}

If the repository is used inside a transaction, no transaction will be created again (thanks to the PrismaClientManager). If the repository is used outside a transaction, a transaction will be created and consistency will be kept between the Order and OrderProduct data.

Finally, with the power of the TransactionScope class, you can create a transaction from the application layer as follows:



export class CreateOrder {
  private readonly orderRepo: OrderRepository;
  private readonly notificationRepo: NotificationRepository;
  private readonly transactionScope: TransactionScope;
  constructor(
    orderRepo: OrderRepository,
    notificationRepo: NotificationRepository,
    transactionScope: TransactionScope
  ) {
    this.orderRepo = orderRepo;
    this.notificationRepo = notificationRepo;
    this.transactionScope = transactionScope;
  }

  async execute({ productIds }: CreateOrderInput) {
    const order = Order.create(productIds);

    // create a transaction scope inside the Application layer
    await this.transactionScope.run(async () => {
      // call multiple repository methods inside the transaction
      // if either fails, the transaction will rollback
      await this.orderRepo.create(order);
      await this.notificationRepo.send(
        `Successfully created order: ${order.id}`
      );
    });
  }
}

Notice that the OrderRepository and NotificationRepository are inside the same transaction and therefore, if the Notification fails, you can rollback the data which was saved from the OrderRepository (leave the architecture decision for now 😂. you get the point.). Therefore, you don't have to mix the database responsibilities with the notification responsibilities.

Wrap up

I've shown how you can create a TransactionScope using Prisma in Node.js. It's not ideal, but looks like it's working as expected. I've seen people struggling about this architecture and hope this post comes in some kind of help.

Feedbacks are extremely welcome!

kenfdev / prisma-auto-transaction-poc

Prisma cross module transaction PoC

This is a PoC to see if cross module transaction is possible with Prisma.

Despite Prisma being able to use interactive transaction, it forces you to use a newly created Prisma.TransactionClient as follows:

// copied from official docs https://www.prisma.io/docs/concepts/components/prisma-client/transactions#batchbulk-operations
await prisma.$transaction(async (prisma) => {
  // 1. Decrement amount from the sender.
  const sender = await prisma.account.update({
    data: {
      balance: {
        decrement: amount,
      },
    },
    where: {
      email: from,
    },
  });
  // 2. Verify that the sender's balance didn't go below zero.
  if (sender.balance < 0) {
    throw new Error(`${from} doesn't have enough to send ${amount}`);
  }
  // 3. Increment the recipient's balance by amount
  const recipient =

…

View on GitHub

Policy enforcement with Vue.js and OPA WebAssembly

Ken Fukuyama — Mon, 16 Dec 2019 08:24:05 +0000

Recently, there was an exciting announcement from OPA about "Rego on WebAssembly".

OPA v0.15.1: Rego on WebAssembly. We’re excited to announce that with OPA… | by Torin Sandall | Open Policy Agent

Torin Sandall ・ Nov 19, 2019 ・ 5 min read
blog.openpolicyagent.org

As explained in the post above, this will open lots of possibilities to enforce policies to all kinds of places. One out of many I wanted to try was in the Front-end world, especially with a SPA like Vue.js. This post describes how I integrated OPA WebAssembly with Vue.js.

TL;DR

If you want to jump right to a working example, here's the repo for the Proof of Concept.

kenfdev / vue-opa-wasm

PoC OPA WASM integration with Vue.js

Prerequisites

Basic knowledge about Open Policy Agent and the Rego Language
Basic knowledge about Vue.js

Overview

What I did for this PoC is listed below:

Create a Rego file and declare rules
Create a wasm file from Rego files with the OPA CLI
Prepare Vue.js to use wasm files
Create and inject a policy instance inside Vue.js
Use the policy instance inside Vue.js templates

Let's dig into details.

Details

For simplicity, I've followed the nodejs-app example to create the wasm but I'm going to briefly explain about it anyway.

Create a Rego file and declare rules

The Rego for this example is extremely simple. The following is the code:

# example.rego
package example

default hello = false

hello {
    x := input.message
    x == data.world
}

It means the hello rule will be true if "The message key's value of the input equals the value of data.world".

Create a `wasm` file from Rego files with the OPA CLI

After the Rego file has been created, the Wasm needs to be built using the OPA CLI. Compiling Rego files to Wasm is added in v0.15.1 of the OPA CLI so you need to download the version newer than that:

https://github.com/open-policy-agent/opa/releases

The actual command to build the Wasm file is as follows:

opa build -d example.rego 'data.example = x'

One thing to note is that, as explained in the docs, you need to specify a query to be used for the Wasm at compile time. In this example, I have queried the entire data.example package.

If the compile succeeds, you will see a policy.wasm file in the path you executed the command.

Preparing the Wasm to be used in the front-end completes here. Next, we'll dive into how this can be integrated in Vue.js.

Prepare Vue.js to use `wasm` files

At the moment, OPA provides a light-weight sdk to use Wasm wih JavaScript called @open-policy-agent/opa-wasm. In this library, you can pass a Wasm ArrayBuffer to load Rego policies to be used by JavaScript.

For simplicity, I decided to load the Wasm at build time of the Vue.js app, and have chosen to use the arraybuffer-loader to load the wasm with the import syntax via webpack.

To add a loader for the Vue.js app, you'll need to create and modify a vue.config.js file as follows:

// vue.config.js
module.exports = {
  chainWebpack: config => {
    config.module
      .rule('arraybuffer')
      .type('javascript/auto')
      .test(/\.wasm$/)
      .use('arraybuffer-loader')
      .loader('arraybuffer-loader');
  },
};

With this configuration, you can load the wasm like this in your JavaScript files:

import wasm from './assets/policy.wasm'

Note: Be sure to add the type('javascript/auto') line or else loading the wasm file will fail. This issue helped me solve it.

Create and inject a `policy` instance inside Vue.js

Now that we have everything prepared, let's load the Wasm before we instantiate the Vue application.

// ...

import Rego from '@open-policy-agent/opa-wasm';
import wasm from './assets/policy.wasm';

// ...

const rego = new Rego();
rego.load_policy(wasm).then(policy => {
  // add the policy instance to the Vue.prototype
  Vue.prototype.$policy = policy;

  new Vue({
    router,
    render: h => h(App),
  }).$mount('#app');
});

Fortunately, the opa-wasm SDK let's us easily load the Wasm as a policy instance by calling the rego.load_policy method. The promise returns a policy instance so I've added this instance to the Vue.prototype in order for it to be used in the Vue templates.

Use the `policy` instance inside Vue.js templates

Here's an example on how we can use the $policy instance inside the Vue templates.

<template>
  <div class="hello">
    <h1>{{ msg }}</h1>
    <pre>{{ $policy.evaluate({ message: "world" }) }}</pre>
  </div>
</template>

<script>
export default {
  name: "HelloWorld",
  props: {
    msg: String
  },
  created() {
    // set the data.world to "world"
    this.$policy.set_data({ world: "world" });
  }
};
</script>

I've set the data.world to "world" at the created life cycle of the component. And in the template itself, I'm calling $policy.evaluate with input.message set to "world". Since both data.world and input.world have the same value "world", the hello rule evaluates to true. You can check it out in the following screen capture.

Wrap up

In this post, I've shown you how to build an OPA Wasm from a Rego file and use it inside a Vue application. I used Vue.js in this post but anything JavaScript should be able to use the policy instance in the same way.

Being able to use the policy instance in the front-end is going to be extremely powerful. I can enforce policies nearly the same way in the front-end as I would in the back-end using the OPA server.

The application above is just a PoC to show you that using Rego policies in the front-end is possible. I can think of few things to improve at the moment such as:

Dynamically fetch wasm

I've imported the Wasm using the import statement but this won't scale. Perhaps one would like to prepare a Wasm per logged in user. It would probably be better to fetch the Wasm dynamically on the fly, and then load and convert it to a policy instance to be used.

Built-ins

At the time of writing, built-ins cannot be used in the Rego files unless you implement them by yourself. built-ins are extremely powerful and makes your Rego files more readable and performant. It would be nice to implement these in JavaScript to be used.

Stay tuned!

The OPA Wasm is still in its early stages but is actively being developed. Let's keep an eye on the official docs and the Slack community!

Continuously enforce policies on your configs with Conftest and CircleCI

Ken Fukuyama — Mon, 21 Oct 2019 15:12:10 +0000

I'm assuming many engineers have struggled to enforce some kind of policy (e.g. style guides, best practices) on their structured data (especially configuration data). Code linting tools do a really good job in this area (e.g. eslint, golangci-lint, etc.) and I can't imagine working with colleagues without linters any more. What I wanted was to have a similar experience with my configurations such as YAML files and remembered watching a very interesting presentation at KubeCon called "Unit Testing Your Kubernetes Configuration with Open Policy Agent" by @garethr:

Conftest and Open Policy Agent are the key points here.

open-policy-agent / conftest

Write tests against structured configuration data using the Open Policy Agent Rego query language

open-policy-agent / opa

An open source, general-purpose policy engine.

If you are new to Conftest and Open Policy Agent, here is an interesting read written by @LennardNL:

I'm not digging into details about Conftest and Open Policy Agent in this post, so I definitely recommend reading the posts above (otherwise, this post might not make any sense to you).

What I wanted to do is continuously enforce my policies in CircleCI. Also, since I use CircleCI in vast amounts of projects, I wanted to easily be able to use it inside my CI and without polluting my circleci/config.yml. As a result, I made a CircleCI Orbs for conftest called, without surprise, conftest-orb.

Let me show how you can use this in the further sections of this post.

Overview

The simplest CircleCI config YAML for conftest-orb would look like this:

version: 2.1
orbs:
  conftest: kenfdev/conftest-orb@x.y
workflows:
  build:
    jobs:
      - conftest/test:
          pre-steps:
            - checkout
          file: config_to_test.yaml

Note that there are some prerequisites in order for this pipeline to work such as the following:

config_to_test.yaml is in the root of your repository
You have the Rego policies in a directory called policy

With the above in mind, this CircleCI workflow will enforce your policy on config_to_test.yaml. Simple isn't it?

Example with serverless.yaml

I've created an example with the Serverless Framework YAML which I just copied from the conftest examples and integrated with CircleCI:

kenfdev / conftest-serverless-circleci

Let's take a look at the .circleci/config.yml:

version: 2.1
orbs:
  conftest: kenfdev/conftest-orb@0.0.8
workflows:
  build:
    jobs:
      - conftest/test:
          pre-steps:
            - checkout
          file: serverless.yaml

You can see how the prerequisites explained above are satisfied with the following file structure:

kenfdev/conftest-serverless-circleci
├── policy
│   ├── base.rego
│   └── util.rego
└── serverless.yaml

The serverless.yaml which will be under test looks like this:

service: aws-python-scheduled-cron

frameworkVersion: '>=1.2.0 <2.0.0'

provider:
  name: aws
  runtime: python2.7
  tags:
    author: 'this field is required'

functions:
  cron:
    handler: handler.run
    runtime: python2.7
    events:
      - schedule: cron(0/2 * ? * MON-FRI *)

I'm not going into details about the rego files but the policies which are going to be enforced are as follows:

Should set provider tags for author
Python 2.7 cannot be the default provider runtime
Python 2.7 cannot be used as the runtime for functions

You can see how the first policy is satisfied, but the latter two aren't. Hence, when the CircleCI runs it will fail and you'll see something like the following screen:

Centralizing your Rego policies

Looking good! But wait a minute. Keeping the policies inside every single repository doesn't seem like a good idea (I can smell something DRY...). But fear not, this is also an area where conftest shines. With the power of push and pull, conftest can save and load external policies from OCI registries. I'm no expert in OCI registries, but I know that the Docker Registry is OCI compatible.

Since I don't want to pay for a self-hosted Docker Registry (at least for now), I've came up with a hack to embed the policies inside the container image via CircleCI. Here's the repository where I save policies for the CircleCI orb YAML in order to enforce best practices mentioned in the docs:

kenfdev / conftest-circleci-orb-policies

I'm not digging into details here either but the following diagram is a rough picture of how the Docker Registry Image gets built in the CI (and here's the config):

Now that I have an OCI registry which includes policies out of the box, I can use them from the CircleCI orbs. The cool thing about conftest-orb development is that in each CI, I'm running integration tests to test the features of the orb, and at the same time I'm enforcing the CircleCI best practices on the orb.yml! It's a pretty cool developer experience to be able to dogfood your project inside the CI.

The following is how the orbs' integration test looks like (full code here):

jobs:
  general_usecase_test:
    executor: machine
    steps:
      - checkout
      - circleci-cli/install
      - run:
          name: Pack the orb.yml
          command: circleci config pack src > orb.yml
      - conftest/install
      # start the OCI registry(this command is declared in a different place)
      - start_oci_registry:
          image: kenfdev/circleci-orbs-policies
      # pull the policies from the OCI registry
      - conftest/pull:
          policy_path: policy
          repository: 127.0.0.1:5000/policies:latest
      # test with minimum options
      - conftest/test:
          policy_path: policy
          file: orb.yml

It looks a bit verbose but that is because I need to spin up the Docker Registry in the CI. If you already have an OCI registry running outside, all you have to write is something like this:

version: 2.1
orbs:
  conftest: kenfdev/conftest-orb@0.0.8
workflows:
  build:
    jobs:
      - conftest/test:
          pre-steps:
            - checkout
          repository: <path-to-your-oci-registry>
          file: serverless.yaml

This will pull your policies from <path-to-your-oci-registry> and run conftest to on the file.

Thanks to the OCI registry feature, I can now create several CircleCI orbs and enforce the same policy to all of them via this conftest-orb. Isn't this pretty awesome? Let's wrap up!

Wrap up

In this post I showed how you can enforce policies in your CircleCI pipeline using conftest orbs. By using the orbs you can easily start enforcing policies to your structured data. IMHO, sharing policies is still a bit tricky but there is an interesting PR waiting to be merged here:

Supporting one-liner policy pulls + http/https/s3/gcs/git/etc via Go-getter integration into conftest #107

Blokje5 posted on Oct 11, 2019

Related issues: #102 #101

As suggested by #nicolasbernard using go-getter can be a good way to get support for multiple sources of Rego files. I did a small PoC to check if it was possible to integrate OCI registry pulling with go-getter, which worked well. Now the question is: should we use it or not.

pros: Support for http, https, s3, gcs, git out of the box. Checksumming. Support for decompression. cons: Assymetrical, so no pull support, which could lead to a bad Ux for conftest push/pull. Might lead to unexpected bugs. Not backwards competable (now you need to specify oci://localhost:5000/policies:tag when using a non-azure registry).

Please let me know what you think. Should we move forward with go-getter? It does over a lot to the project as we could immediately support pulling policies from blob-storage, git and http.

View on GitHub

If this gets merged, conftest will be able to fetch policies via http/https/s3/gcs/git/etc, which will open a wide range of possibilities to centralize your Rego policies! This is going to be REALLY exciting!

Open Policy Agent

Another important thing I haven't mentioned much in this post is Open Policy Agent, the policy engine which Conftest uses under the hood. I really recommend taking a look at this project and getting your hands dirty with the Rego language. It's a bit tricky at first but after you get used to it, the flexibility is extremely powerful.

You can join the super supportive community here. Also, there is a #conftest channel specific to Conftest.

Try it yourself!

If you find this post interesting, please give conftest-orb a try! Feedbacks will be greatly appreciated :)

Merge 2 Objects in Rego

Ken Fukuyama — Tue, 15 Oct 2019 21:25:36 +0000

This is the final post of "Object Merging in Rego" series.

If you are not comfortable with Rego yet, I'd recommend you read the previous posts before continuing.

When the keys collide with the merging objects, let's say the latter object's value wins. With that in mind, in order to merge objects, we need to:

Gather the keys of the 2 objects
Pick the values of the objects and if the keys collide, pick the latter object's value

In order to implement this, "Set Comprehensions" and "Object Comprehensions" come in handy.

Gather keys of 2 objects

Suppose we have 2 objects like the following:

object1

{
  "a": "value1",
  "b": "value2"
}

object2

{
  "b": "value3",
  "c": "value4"
}

If we're merging these 2 objects, what we first want is the keys a, b, c. How can we gather these? With Set comprehensions.

This is how it will look like in Rego:

collect_keys = ks {
  ks := {k | some k; _ = input.a[k]} | {k | some k; _ = input.b[k]}
}

Maybe it looks a bit difficult for beginners but you'll get used to it sooner or later.

Let's look at one part of it:

{k | some k; _ = input.a[k]}

This is like saying

Iterate over input.a's keys
Put it inside the local variable k
Collect it

So if input.a is { "a": "value1", "b": "value2" }, the result will be { "a", "b" }. In addition, when the input.b is { "b": "value3", "c": "value4" }, the result will be { "b", "c" } and the rule above will look like this:

collect_keys = ks {
  ks := { "a", "b" } | { "b", "c" }
}

Which evaluates to ks == { "a", "b", "c" } because it is evaluating an OR with 2 sets.

You can check this out in the following playground:

https://play.openpolicyagent.org/p/bw0aM0bRHM

Pick values from 2 objects

Now that we have the keys of the final merged object, we need to gather the values of the 2 objects. What we'd want to do is:

Iterate over the keys we gathered above
Pick the value corresponding with the key. Be sure to prioritize the latter object's value over the former one.

This is where the pick_first function comes in handy from the 2nd post of this series.

Picking the first value you find from 2 objects in Rego

Ken Fukuyama ・ Sep 30 '19 ・ 2 min read

#rego #opa #openpolicyagent

Assuming that pick_first has already been declared, the following Rego function shows how 2 objects get merged.

merge_objects(a, b) = c {
    ks := {k | some k; _ = a[k]} | {k | some k; _ = b[k]}
    c := {k: v | some k; ks[k]; v := pick_first(k, b, a)}
}

Note that the object b comes first and object a next in the pick_first function which means that the values of object b are prioritized.

Wrap up

The final version of merging 2 objects in Rego looks like this (which you can find here in the official docs):

has_key(x, k) { _ = x[k] }

pick_first(k, a, b) = a[k]
pick_first(k, a, b) = b[k] { not has_key(a, k) }

merge_objects(a, b) = c {
    ks := {k | some k; _ = a[k]} | {k | some k; _ = b[k]}
    c := {k: v | some k; ks[k]; v := pick_first(k, b, a)}
}

merged = o {
  o := merge_objects(input.x, input.y)
}

If the input is as follows:

{
  "x": {
    "a": true,
    "b": false
  },
  "y": {
    "b": "foo",
    "c": 4
  }
}

The merged output becomes like this:

{
  "merged": {
    "a": true,
    "b": "foo",
    "c": 4
  }
}

Note that object y's key/value "b": "foo" is chosen because it is the latter object when merging.

For those who want to play around, here is the playground code:

https://play.openpolicyagent.org/p/LzJDiUQQFY

Reference

Picking the first value you find from 2 objects in Rego

Ken Fukuyama — Mon, 30 Sep 2019 13:13:15 +0000

This post is about "how you can pick the first value you find from 2 objects" in Rego, a query language used in OPA (Open Policy Agent).

This use case is a little confusing and you'll probably think "When is this necessary?". One example is shared in "Merge Objects" in the official docs.

When merging multiple objects, you'll definitely need to think about colliding keys and how to decide which key, value to choose. This is where you'll want to use "Pick the first value you find from 2 objects".

Let's dive into details.

Logical OR in Rego

The function which "Picks the first value it finds from 2 objects" will be called pick_first. Here's how the implementation will look like.

has_key(x, k) { 
    _ := x[k]
}

pick_first(k, a, b) = a[k]
pick_first(k, a, b) = b[k] { not has_key(a, k) }

See how there are 2 definitions of pick_first(k, a, b). This is how you express a Logical OR in Rego. So the expression above is like saying:

"For key k, choose the value from object a, OR, choose the value from object b if object a DOES NOT HAVE key k."

If you feel uncomfortable with the has_key function, look at my previous post specifically explaining about it here:

Check if key exists in object in Rego

Ken Fukuyama ・ Sep 28 '19 ・ 2 min read

#openpolicyagent #opa #rego

Example

Here's a complete example demonstrating the usage of pick_first.

has_key(x, k) { 
    _ := x[k]
}

pick_first(k, a, b) = a[k]
pick_first(k, a, b) = b[k] { not has_key(a, k) }

x := {"a": true, "b": false}
y := {"b": "foo", "c": 4}

first_values = fv {
    a := pick_first("a", x, y)
    b := pick_first("b", x, y)
    c := pick_first("c", x, y)
    fv := {
        "a": a,
        "b": b,
        "c": c
    }
}

If you evaluate first_values, the result would be:

{
  "a": true,
  "b": false,
  "c": 4
}

Notice how key false was chosen from object x's key b. The only time the values of object y are selected are when the key doesn't exist in object x (e.g. key c).

You can check this out for yourself in the following playground:

https://play.openpolicyagent.org/p/puwMTreKjD

Reference

Check if key exists in object in Rego

Ken Fukuyama — Sat, 28 Sep 2019 04:41:41 +0000

Recently, I'm writing Rego(a query language to use in Open Policy Agent) every day and have decided to post some tricky syntaxes that took me a little time to understand.

In this post, I'm going to look at how to check if a key exists in an object in Rego.

I've pulled the sample code from the Policy Cheatsheet in the official docs.

has_key(x, k) { _ = x[k] }

Looks simple, but has a bit of a gotcha (at least for me) despite consuming the function is pretty intuitive (here's the playground):

has_key({"foo": "bar"}, "foo") # true
has_key({"foo": "bar"}, "baz") # undefined

It's checking if key k exists in object x. What confused me at first is _ = x[k]. Why do we need the _ = part?

Without the "_ ="

Let's see what happens if the function becomes like this:

has_key(x, k) { x[k] }

At first, this looks like it's working. But you have to think about the case where the value of x[k] is actually false.

The return value of the function is true whenever the function body is satisfied. That is the case when x[k] unifies to anything that is not false -- if x[k] unifies to false, the function body is not satisfied... (functions are not very different from rules). Here's an example(and the playground):

has_key(x, k) { x[k] }

default foo_exists = false
foo_exists = has_key({"foo": false}, "foo") # false!!!

To avoid this unexpected behavior, the assigning(or union) part (_ =) is mandatory.

With the "_ ="

Let's put the _ = back inside the function.

has_key(x, k) { _ = x[k] }

With this, the function body is satisfied if it unifies -- i.e. there's an x[k], not undefined -- but it doesn't matter if it's true or false, because the x[k] is put into a context where its value doesn't matter: _ = y never fails, regardless of the value of y, as long as y is not undefined.

Any other construct that doesn't regard the value would work as well. Here are some alternatives (which are not better, just different):

https://play.openpolicyagent.org/p/eed4f2wVGS

https://play.openpolicyagent.org/p/LgJo6T0tUz

Wrap up

Again, you can check the correct version in this playground.

If you're still uncomfortable with the Rego syntax used inside the function, check out the Policy Language#Variable Keys section in the official docs. Also, you can check the Policy Cheatsheet#Objects section.

Happy Rego coding!

P.S. I'd like to greatly appreciate @srenatus from the OPA community for reviewing my post and giving me accurate advice!

Digging into API Authorization with OPA

Ken Fukuyama — Tue, 02 Jul 2019 00:51:49 +0000

I've recently been getting my hands on with Open Policy Agent to find a way to gain a fine-grained permission control feature for my custom API service.

In this post I'm assuming you have at least heard what Open Policy Agent is. If you haven't, I definitely recommend watching the following presentations from Torin Sandal.

Intro: Open Policy Agent

OPA is extremely powerful and flexible. You should take a look at some of the tutorials in the official docs starting from the, well, "Get Started".

One tutorial I found very interesting is the HTTP API Authorization. I think many people have experienced API Authorization and have struggled all the if statements to allow or deny a user doing something. With OPA, you can delegate the decision outside of your code.

"Delegate the decision outside?", at first, this was hard for me to imagine so I've decided to migrate an API from a non-OPA version to an OPA version.

TL;DR

You can look at the full code in the repository.

kenfdev / opa-api-auth-go

A sample API using OPA as the Policy Decision Point.

OPA API Authorization

A sample to show the difference between using OPA as the Policy Decision Point.

How to

The master branch does not include OPA as the Policy Decision Point. OPA is added in the add-opa branch.

You can compare the difference in this PR

If you want to spin up the OPA version, do the following steps:

git checkout add-opa

docker-compose up

Requesting the API

The API is available in the GET /finance/salary/:username endpoint. You can GET to this endpoint but a JWT is needed to properly make a request.

You can easily create an JWT at jwt.io. This application assumes that the algorithm is HS256 and the secret is simply secret. Also, the payload should look something like this:

{
  "sub": "1234567890"
  "iat": 1516239022,
  "user": "bob",
  "subordinates": ["alice"],
  "hr"

…

View on GitHub

You can run the OPA authorized API from this branch of the repository
The diff of non-OPA version and OPA version can be found here

The API

The API we are going to use is based on the tutorial in the OPA official docs. The tutorial uses python but I've decided to build it with Go and with labstack's echo framework.

Here is the overview of the application (including the policies).

Members are as follows:
- Alice
- Bob
- Charlie
- Betty
- David
Bob is Alice's manager and Betty is Charlie's manager. David belongs to the HR department.
Users can view their own salary
Managers can view their subordinates' salary
HRs can view everybody's salary

Here is an overview diagram.

Let's get started with the non-OPA version.

The Policy Decision without OPA

I've created a Policy Enforcement middleware to enforce the policy on every request made to the API endpoint. In the middleware, I'm simply asking a PolicyGateway to check if the requester is allowed to call the API. The code below shows the overview.(GitHub)

...
logrus.Info("Enforcing policy with middleware")

allow := gateway.Ask(c)

if allow {
    logrus.Info("Action is allowed, continuing process")
    return next(c)
} else {
    logrus.Info("Action was not allowed, cancelling process")
    return c.String(http.StatusForbidden, "Action not allowed")
}
...

The interface for PolicyGateway is just 1 method Ask which returns a bool meaning Allow or Deny.

type PolicyGateway interface {
    Ask(echo.Context) bool
}

I've called the implementation for the gateway the PolicyLocalGateway and basically the following code is what it does.(GitHub.

func (gw *PolicyLocalGateway) checkGETSalary(c echo.Context, claims *entity.TokenClaims) bool {
    userID := c.Param("id")

    if yes := gw.checkIfOwner(userID, claims); yes {
        logrus.Info("Allowing because requester is the owner")
        return true
    }

    if yes := gw.checkIfSubordinate(userID, claims); yes {
        logrus.Info("Allowing because target is a subordinate of requester")
        return true
    }

    if yes := gw.checkIfHR(claims); yes {
        logrus.Info("Allowing because requester is a member of HR")
        return true
    }

    logrus.Info("Denying request")
    return false
}

You can see lots of if statements and can assume this will easily increase the amount of code in the long run. Also, it is a little hard to understand what is going on with all these if statements and indentation (well... that might be my fault, but you get the point).

Let's check some HTTP requests to see what happens.

First, let's start with Alice. Since Alice is a normal staff, she can only view her own salary.

$ curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaWF0IjoxNTE2MjM5MDIyLCJ1c2VyIjoiYWxpY2UiLCJzdWJvcmRpbmF0ZXMiOltdLCJociI6ZmFsc2V9.WTR-Or-vS1yFBFHk7UyqZxsNhtTNSWeazJ57SJ7V4qY" \
  http://localhost:1323/finance/salary/alice

100

You can see that the value 100 came back with no errors. Let's see if Alice can view Bob's salary.

$ curl -H "Authorization: Bearer <Alice's JWT>" \
  http://localhost:1323/finance/salary/bob

Action not allowed

It is now forbidden because Alice is a normal staff and cannot view other employee's salary. The logs show the request has been denied as well.

app_1  | msg="Enforcing policy with middleware"
app_1  | msg="Checking GET salary policies" claims="&{alice [] false { 0  1516239022  0 1234567890}}" userID=bob
app_1  | msg="Denying request"
app_1  | msg="Action was not allowed, cancelling process"

On the other hand, let's see if Bob can view Alice's salary.

Bob's JWT payload looks like the following:

{
  "sub": "1234567890",
  "iat": 1516239022,
  "user": "bob",
  "subordinates": ["alice"],
  "hr": false
}

He has alice as his subordinate which means he is Alice's manager.

$ curl -H "Authorization: Bearer <Bob's JWT>" \
  http://localhost:1323/finance/salary/alice

100

You can confirm that Bob is allowed to view Alice's salary. This is checked in the logic gw.checkIfSubordinate in the code above. Now how about Bob viewing David's salary?

$ curl -H "Authorization: Bearer <Bob's JWT>" \
  http://localhost:1323/finance/salary/david

Action not allowed

Of course, Bob is not allowed to view David's salary because he has no permission to do so.

Now, let's see what David as a member of HR can do?

David's JWT payload is as follows.

{
  "sub": "1234567890",
  "iat": 1516239022,
  "user": "david",
  "subordinates": [],
  "hr": true
}

Since he is a member of HR, he has hr: true in his JWT payload.

$ curl -H "Authorization: Bearer <David's JWT>" \
  http://localhost:1323/finance/salary/bob

200

Success! And he can also see Betty, Alice, Charlie's salary as well. This is because he passes the check gw.checkIfHR in the code above.

This should have been pretty straight forward. Now, let's see what happens when OPA comes into the game.

The Policy Decision with OPA

Adding OPA is pretty simple. The implementation of the PolicyGateway will change. I've called it the PolicyOpaGateway and this time, I didn't implement anything related to policy rules (none of those if statements anymore) because I wanted to delegate them to OPA.

The main changes are:

I wrote policies in Rego to *.rego files
I added the OPA server next to the main app
I have implemented the PolicyGateway to make an external HTTP request to the OPA server with enough payloads in order for OPA to make decisions

Writing the policy in Rego

The policy written in Rego is as below.

package httpapi.authz

# io.jwt.decode_verify
# https://www.openpolicyagent.org/docs/latest/language-reference/#tokens
token = t {
  [valid, _, payload] = io.jwt.decode_verify(input.token, { "secret": "secret" })
  t := {
    "valid": valid,
    "payload": payload
  }
}

default allow = false

# Allow users to get their own salaries.
allow {
  token.valid

  some username
  input.method == "GET"
  input.path = ["finance", "salary", username]
  token.payload.user == username
}

# Allow managers to get their subordinate's salaries.
allow {
  token.valid

  some username
  input.method == "GET"
  input.path = ["finance", "salary", username]
  token.payload.subordinates[_] == username
}

# Allow HR members to get anyone's salary.
allow {
  token.valid

  input.method == "GET"
  input.path = ["finance", "salary", _]
  token.payload.hr == true
}

It is nearly identical with the tutorial version. A slight difference is that it is verifying the JWT token with io.jwt.decode_verify using the key secret.

Side Note: The Rego Playground

One awesome feature I want to point out about OPA is the Rego Playground.

You can write policies and quickly evaluate them on the browser! In addition, you can share the policy via a link for others to look at (e.g. they can debug your policies). Here's the link for the policy above. The Input is set to Alice's JWT and the path to her own salary.

https://play.openpolicyagent.org/p/ww8qdEHdn0

You can check the OUTPUT to see that the result is allowed.

Adding the OPA server

After creating a policy with Rego, I've set the OPA service next to the main app by adding the following lines in the docker-compose.yml.

  pdp:
    image: openpolicyagent/opa:0.12.0
    ports:
      - 8181:8181
    volumes:
      - ./opa:/etc/opt/opa
    command: ["run", "--server", "/etc/opt/opa/authz.rego"]

FYI, PDP stands for Policy Decision Point. I just wanted to give it a generic name.

Requesting OPA for decisions

Now that OPA is ready, I have implemented the PolicyGateway so it makes an external HTTP request to OPA server for decisions.

Preparing the input

OPA needs enough information in order to make decisions. For this simple app, I needed to tell OPA:

Who the requester is - including attributes (JWT token)
What endpoint was requested (request path and HTTP method)

And the code looks like this. I have used echo's JWT middleware to easily extract the JWT data.

...
token := c.Get("token").(*jwt.Token)
// After splitting, the first element isn't necessary
// "/finance/salary/alice" -> ["", "finance", "salary", "alice"]
paths := strings.Split(c.Request().RequestURI, "/")[1:]
method := c.Request().Method

// create input to send to OPA
input := &opaInput{
    Token:  token.Raw,
    Path:   paths,
    Method: method,
}
// don't forget to wrap it with `input`
opaRequest := &opaRequest{
    Input: input,
}
...

A slight gotcha is that the HTTP request payload needs to be wrapped with an input key as shown in the code above. Of course, this is mentioned in the docs.

HTTP Request

I have injected OPA's endpoint to the PolicyGateway through an environment variable (here and here). Therefore, it is accessible by calling gw.endpoint. So the request will be like the following code.(GitHub)

type opaResponse struct {
    Result bool `json:"result"`
}

...

// request OPA
resp, err := http.Post(gw.endpoint, "application/json", bytes.NewBuffer(requestBody))
...
body, err := ioutil.ReadAll(resp.Body)
...
var opaResponse opaResponse
err = json.Unmarshal(body, &opaResponse)

It's simply asking OPA and returning the result back to the caller. Now that the code is prepared, let's give it a shot again!

# David (a member of HR) viewing Betty's salary
$ curl -H "Authorization: Bearer <David's JWT>" http://localhost:1323/finance/salary/betty

200

Looks good. Let's look at the logs.

app_1  | msg="Enforcing policy with middleware"
app_1  | msg="Requesting PDP for decision" method=GET path="[finance salary betty]" token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaWF0IjoxNTE2MjM5MDIyLCJ1c2VyIjoiZGF2aWQiLCJzdWJvcmRpbmF0ZXMiOltdLCJociI6dHJ1ZX0.TBXtM_p-VIlgx9NSLn4An6hELr2UB3CrqHUJmofQorM
pdp_1  | l":"info","msg":"Sent response.","req_id":2,"req_method":"POST","req_path":"/v1/data/httpapi/authz/allow","resp_bytes":15,"resp_duration":4.1901,"resp_status":200,"time":"2019-06-30T14:29:52Z"}
app_1  | msg=Decision result=true
app_1  | msg="Action is allowed, continuing process"
app_1  | msg="Processing salary request" id=betty
app_1  | msg="Fetched salary" id=betty salary=200

The app is requesting OPA and receiving true as the result. You can see the same result in the following playground.

https://play.openpolicyagent.org/p/w0kohf47we

Let's also see if Alice's request to Bob (to her manager) will fail.

$ curl -H "Authorization: Bearer <Alice's JWT>" \
  http://localhost:1323/finance/salary/bob

Action not allowed

Awesome! And the logs?

app_1  | msg="Enforcing policy with middleware"
app_1  | msg="Requesting PDP for decision" method=GET path="[finance salary bob]" token=<Alice's JWT>
pdp_1  | l":"info","msg":"Received request.","req_id":1,"req_method":"POST","req_path":"/v1/data/httpapi/authz/allow","time":"2019-06-30T21:29:59Z"}
app_1  | msg=Decision result=false
app_1  | msg="Action was not allowed, cancelling process"

Everything is working as expected! (Here's the playground)

We have successfully replaced the local policy engine to OPA. You can see how the separation of concerns are met by delegating the policy decisions to OPA.

You can view the full changes to the code in my PR here.

Wrap up

This was a very simple example to show how you can leverage the power of OPA with an HTTP API server.

Some Pros and Cons I can think of from this simple example is:

Pros
Separation of concerns. In my main app, I can concentrate on the business logic I need to implement. I don't have to write all those if statements and change my code each time a policy changes. If I change my code, that means I have to deploy it again. As for OPA, you can dynamically change your policies on the run. No redeploying is necessary when you change policies.

In addition, I was not able to mention it in this post, but Rego can be tested with Rego, too. You should have a look at "How Do I Test Policies?".

Some additional Pros I've heard in the slack channel are as follows:

Security/Compliance can audit policy separate from auditing the code.
Consistent logging of decisions; helpful for SIEM integration (Decision Logs)
Consistent policy language (Rego) across different microservices; helps people trying to understand what is actually authorized across a chain of services
When building a UI, it also needs to implement the same policies; easier if decoupled and consistent across services (e.g. take a look at Chef Automate's Introspection)
Start with a solution purpose-built where you can start simple but that grows with you as your authz needs evolve.
Avoid a series of one-off extensions to an authz system that in the end looks like a frankenstein. You can see how the monolith app I built above will become like in the long run.

Cons
I don't see a major downside in using OPA, but as this post has shown, a standard monolithic service turned into a microservice approach. Which means it will add complexity than not using OPA. But this is more about microservices than OPA itself. Also, Rego is an additional learning curve for newbies. I'd say it's worth the effort and I'm assuming Rego is going to become more and more popular as OPA grows.

Finally, some questions that may arise are:

Do I have to pass all information to OPA for decisions?
AFAIK, the simplest approach is to pass everything, but that may not be easy or performant in many situations. One way is to use the http.send built-in function to make external request from within OPA. You can also use Bundles for OPA to fetch data periodically from external services. Further information can be found in the official docs "Guides: Identity and User Attributes". It has really good detail in it.

Can I use OPA as a library?
Maybe you don't want an extra container for various reasons. Yes, OPA can be used as a Go library and you can look at some awesome OSS projects that use OPA as a library. Some that I know are:

Can I create something like an AWS IAM with OPA?
I have heard this question several times (including myself) in the OPA slack and if you have the same question, you should definitely look at the Chef Automate authorization service documentation. This document is amazing. I really mean it. There are definitely many ways to implement something like an AWS IAM with OPA but this one is surely a great live example.

I'm assuming there are many more questions, but the best way to get support is to join the OPA slack channel. The people there are super supportive and I've gained a lot of knowledge there.

Thank you for reading this long post!!! I'd like to greatly appreciate Ash(@ashtalk) and Tim(@tlhinrichs) for reviewing this post upfront! I'm hoping I can contribute and give back with what I have to the OPA community!

Reference

Deep Dive: Open Policy Agent

DEV Community: Ken Fukuyama

Demystifying Playwright Test Agents' seed.spec.ts: What I Learned from Reading the MCP Code

Introduction

Where the Official Docs Left Me Confused

Reading the MCP Code

Checking the Agent Prompts

Looking at the MCP Tool Implementation

Mystery Solved: What seed.spec.ts Really Is

What Should Go in seed.spec.ts

How Is This Different from Existing Setup/Fixtures?

Global Setup / Teardown

Fixtures

The Critical Difference

About Comments in Generated Code

How This Might Work in Mid-to-Large Scale Projects (Hypothesis)

Using Multiple Seed Files

Pros and Cons

Summary

Deciphering GraphQL: A Deep Dive into Type Merging and Schema Stitching

Assumptions for this article

Type Merging in GraphQL Stitching

What is Type Merging?

Verifying the Merging Flow in practice

1. Client request

2. The original request goes to the storefront server

3. Response from storefront

4. Creation of the merger query

5. Request to the products

6. Response from products

7,8,9. Similar requests are sent to the manufacturer server

10,11. All results are merged into the appropriate type and returned

Conclusion

Upgrading from graphql-yoga v2 to v4

Key Points on Upgrading from graphql-yoga v2 to v4

1. Removal of endpoint and graphiql.endpoint options

2. Changes in the Configuration Approach

3. Changes regarding the Endpoint

Cross Module Transaction with Prisma

TL;DR

Prisma and Interactive Transaction

Creating a custom TransactionScope

Wrap up

kenfdev / prisma-auto-transaction-poc

Prisma cross module transaction PoC

Policy enforcement with Vue.js and OPA WebAssembly

OPA v0.15.1: Rego on WebAssembly. We’re excited to announce that with OPA… | by Torin Sandall | Open Policy Agent

Torin Sandall ・ Nov 19, 2019 ・ 5 min read blog.openpolicyagent.org

TL;DR

kenfdev / vue-opa-wasm

PoC OPA WASM integration with Vue.js

Prerequisites

Overview

Details

Create a Rego file and declare rules

Create a wasm file from Rego files with the OPA CLI

Prepare Vue.js to use wasm files

Create and inject a policy instance inside Vue.js

Use the policy instance inside Vue.js templates

Wrap up

Dynamically fetch wasm

Built-ins

Stay tuned!

Continuously enforce policies on your configs with Conftest and CircleCI

open-policy-agent / conftest

Write tests against structured configuration data using the Open Policy Agent Rego query language

open-policy-agent / opa

An open source, general-purpose policy engine.

Overview

Example with serverless.yaml

kenfdev / conftest-serverless-circleci

Centralizing your Rego policies

kenfdev / conftest-circleci-orb-policies

Wrap up

Supporting one-liner policy pulls + http/https/s3/gcs/git/etc via Go-getter integration into conftest #107

Open Policy Agent

Try it yourself!

Merge 2 Objects in Rego

Gather keys of 2 objects

object1

object2

1. Removal of `endpoint` and `graphiql.endpoint` options

Torin Sandall ・ Nov 19, 2019 ・ 5 min read
blog.openpolicyagent.org

Create a `wasm` file from Rego files with the OPA CLI

Prepare Vue.js to use `wasm` files

Create and inject a `policy` instance inside Vue.js

Use the `policy` instance inside Vue.js templates