@magek/mcp-server 0.0.8

package/docs/index.md

@@ -0,0 +1,62 @@
+---
+title: "Documentation"
+children:
+  - ./introduction.md
+  - ./getting-started/installation.md
+  - ./getting-started/coding.md
+  - ./architecture/event-driven.md
+  - ./architecture/command.md
+  - ./architecture/event.md
+  - ./architecture/event-handler.md
+  - ./architecture/entity.md
+  - ./architecture/read-model.md
+  - ./architecture/notifications.md
+  - ./architecture/queries.md
+  - ./features/event-stream.md
+  - ./features/schedule-actions.md
+  - ./features/logging.md
+  - ./features/error-handling.md
+  - ./security/security.md
+  - ./security/authentication.md
+  - ./security/authorization.md
+  - ./magek-cli.md
+  - ./graphql.md
+  - ./advanced/custom-templates.md
+  - ./advanced/data-migrations.md
+  - ./advanced/environment-configuration.md
+  - ./advanced/framework-packages.md
+  - ./advanced/instrumentation.md
+  - ./advanced/register.md
+  - ./advanced/sensor.md
+  - ./advanced/testing.md
+  - ./advanced/touch-entities.md
+  - ./advanced/health/sensor-health.md
+  - ./contributing.md
+---
+
+# Magek Framework Documentation
+
+Welcome to the Magek documentation! Use the navigation on the left to browse guides and API reference.
+
+## Quick Links
+
+- **[Introduction](./introduction.md)** - Learn what Magek is
+- **[Installation](./getting-started/installation.md)** - Get started quickly
+- **[Coding Tutorial](./getting-started/coding.md)** - Build your first app
+
+## Sections
+
+### Getting Started
+Set up your environment and build your first Magek application.
+
+### Architecture
+Understand Commands, Events, Entities, Read Models, and other core concepts.
+
+### Features
+Learn about Event Streams, Scheduled Actions, Logging, and Error Handling.
+
+### Security
+Implement Authentication and Authorization in your applications.
+
+### Advanced Topics
+Dive deeper into Providers, Migrations, Testing, and more.

package/docs/introduction.md

@@ -0,0 +1,58 @@
+---
+title: "Introduction"
+group: "Guides"
+---
+
+# Introduction
+
+> _Progress isn't made by early risers. It's made by lazy men trying to find easier ways to do something._ — [Robert A. Heinlein](https://en.wikipedia.org/wiki/Robert_A._Heinlein)
+
+## What is Magek?
+
+Magek is the fastest way to create a scalable application. It is a new kind of framework to build scalable and reliable systems easier, reimagining the software development experience to maximize your team's speed and reduce friction on every level.
+
+Magek follows an Event-Driven and a Domain-Driven Design approach in which you define your application in terms that are understandable by anyone in your company. From a bird’s eye view, your project is organized into:
+
+- **Commands**: Define what a user can request from the system (i.e: Add an item to the cart)
+- **Queries**: Define what a user can get from the system (i.e: Get cart items)
+- **Events**: Simple records of facts (i.e: User X added item Y to the cart Z)
+- **Entities**: Data about the things that the people in your company talk about (i.e: Orders, Customers, etc.)
+- **Handlers**: Code that processes commands, reacts to events to trigger other actions, or update the entities after new events happen.
+
+Events are the cornerstone of a Magek application, and that’s why we say that Magek is an event-driven framework. Events bring us many of the differentiating characteristics of Magek:
+
+- **Real-time**: Events can trigger other actions when they’re created, and updates can be pushed to connected clients without extra requests.
+- **High data resiliency**: Events are stored by default in an append-only database, so the data is never lost and it’s possible to recover any previous state of the system.
+- **Scalable by nature**: Dependencies only happen at data level, so Magek apps can ingest more data without waiting for other operatons to complete. Low coupling also makes it easier to evolve the code without affecting other parts of the system.
+- **Asynchronous**: Your users won't need to wait for your system to process the whole operation before continuing using it.
+
+Before Magek, building an event-driven system with the mentioned characteristics required huge investments in hiring engineers with the needed expertise. Magek packs this expertise, acquired from real-case scenarios in high-scale companies, into a very simple tool that handles the hard parts for you!
+
+We have redesigned the whole developer experience from scratch, taking advantage of the advanced TypeScript type system to go from project generation to a production-ready application which provides a real-time GraphQL API that can ingest thousands of concurrent users in a matter of minutes.
+
+Magek's ultimate goal is making developer's lives easier, fulfilling the dream of writing code in a domain-driven way that eases communications for the whole team, without caring about how anything else is done at the infrastructure level!
+
+## Magek Principles
+
+Magek enhances developers' productivity by focusing only on business logic. Write your code, provide your credentials and let Magek do the rest. Magek takes a holistic and highly-opinionated approach at many levels:
+
+- **Focus on business value**: The only code that makes sense is the code that makes your application different from any other.
+- **Convention over configuration**: All the supporting code and configuration that is similar in all applications should be out of programmers’ sight.
+- **Simple deployment**: Run your application as a standalone server or export handlers for serverless deployment.
+- **Scale smoothly**: The code you write to handle your first 100 users will still work to handle your first million. You won't need to rewrite your application when it succeeds.
+- **Event-source and CQRS**: Our world is event-driven, businesses are event-driven, and modern software maps better to reality when it’s event-driven.
+- **Principle of Abstraction**: Building an application is hard enough to have to deal with recurring low-level details like SQL, API design, or authentication mechanisms, so we tend to build more semantic abstractions on top of them.
+- **Real-time first**: Client applications must be able to react to events happening in the backend and notice data changes.
+
+## Why use Magek
+
+What does _Magek_ boost? Your team's productivity. Not just because it helps you work faster, but because it makes you worry about fewer buttons and switches. We aim to solve major productivity sinks for developers like designing the right infrastructure, writing APIs or dealing with ORMs.
+
+Magek will fit like a glove in applications that are naturally event-driven like commerce applications (retail, e-commerce, omnichannel applications, warehouse management, etc.), business applications or communication systems, but it's a general-purpose framework that has several advantages over other solutions:
+
+- **Faster time-to-market**: Magek can run your application from minute one, without complicated configurations. In addition to that, it features a set of code generators to help developers build the project scaffolding faster and focus on actual business code in a matter of seconds instead of dealing with complicated framework folklore.
+- **Write less code**: Magek conventions and abstractions require less code to implement the same features. This not only speeds up development but combined with clear architecture guidelines also makes Magek projects easier to understand, iterate, and maintain.
+- **Benefit from Typescript's advantages**: Typescript's type system provides an important security layer that helps developers make sure the code they write is the code they meant to write, making Magek apps more reliable and less error-prone.
+- **All the advantages of Microservices, none of its cons**: Microservices are a great way to deal with code complexity, at least on paper. Services are isolated and can scale independently, and different teams can work independently, but that usually comes with a con: interfaces between services introduce huge challenges like delays, hard to solve cyclic dependencies, or deployment errors. In Magek, every handler function works independently, there are no direct dependencies between them, all communication happens asynchronously via events, and everything is compiled and type-checked atomically to avoid issues.
+- **Event-sourcing by default**: Magek keeps all incremental data changes as events, indefinitely. This means that any previous state of the system can be recreated and replayed at any moment, enabling a whole world of possibilities for troubleshooting and auditing, syncing environments or performing tests and simulations.
+- **Magek makes it easy to build enterprise-grade applications**: Implementing an event-sourcing system from scratch is a challenging exercise that usually requires highly specialized experts. There are some technical challenges like eventual consistency, message ordering, and snapshot building. Magek takes care of all of that and more for you, lowering the curve for people that are starting and making expert lives easier.

package/docs/magek-cli.md

@@ -0,0 +1,67 @@
+---
+title: "Magek CLI"
+group: "Guides"
+---
+
+# Magek CLI
+
+The Magek CLI is a command line interface that helps you develop your Magek applications. It is built with Node.js and published to NPM through the package `@magek/cli`. It's automatically included as a dependency in every Magek project - no global installation required!
+
+## No Installation Required
+
+When you create a Magek project using `npm create magek@latest`, the CLI is automatically included as a dependency. Simply use `npx magek` to run any CLI command within your project directory.
+
+```bash
+# Create a new project (CLI automatically included)
+npm create magek@latest my-project
+
+# Navigate to your project and start using the CLI
+cd my-project
+npx magek --help
+```
+
+## Usage
+
+Once you're in your Magek project directory, you can use the `npx magek` command to see the help message.
+
+> **Tip:** You can also run `npx magek --help` to get the same output.
+
+## Command Overview
+
+| Command | Description |
+|---------|-------------|
+| [`new:command`](/architecture/command#creating-a-command) | Creates a new command in the project |
+| [`new:entity`](/architecture/entity#creating-an-entity) | Creates a new entity in the project |
+| [`new:event`](/architecture/event#creating-an-event) | Creates a new event in the project |
+| [`new:event-handler`](/architecture/event-handler#creating-an-event-handler) | Creates a new event handler in the project |
+| [`new:read-model`](/architecture/read-model#creating-a-read-model) | Creates a new read model in the project |
+| [`new:scheduled-command`](/features/schedule-actions#creating-a-scheduled-command) | Creates a new scheduled command in the project |
+
+> **Tip:** To create a new Magek project, use the modern npm create pattern:
+>
+> ```bash
+> npm create magek@latest my-project
+> ```
+>
+> All CLI commands should be run with `npx magek` within your project directory.
+
+```bash
+npm create magek@latest my-project
+```
+
+## Adapter CLI plugins
+
+Magek CLI automatically discovers adapter packages named `@magek/adapter-*` that export a `magekCli` object. Any commands listed there are registered at startup and appear in `npx magek --help`.
+
+```ts
+export const magekCli = {
+  commands: {
+    'migrate:status': MigrateStatusCommand,
+    'migrate:apply': MigrateApplyCommand,
+  },
+}
+```
+
+> **Note:** Plugin discovery executes code from installed adapter packages. Only install trusted adapters in your project.
+
+See the [Getting Started guide](/getting-started/coding#1-create-the-project) for details.

package/docs/magek-logo.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg width="100%" height="100%" viewBox="0 0 2892 715" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;"><rect id="Artboard2" x="0" y="0" width="2891.53" height="714.98" style="fill:none;"/><clipPath id="_clip1"><rect x="0" y="0" width="2891.53" height="714.98"/></clipPath><g clip-path="url(#_clip1)"><g><path d="M1215.33,192.315c40.311,-0 72.818,12.388 97.518,37.166c24.701,24.777 37.051,59.366 37.051,103.767l0,193.264l-82.994,-0l-0,-181.965c-0,-25.769 -6.521,-45.491 -19.563,-59.168c-13.042,-13.678 -30.827,-20.516 -53.354,-20.516c-22.527,-0 -40.41,6.838 -53.65,20.516c-13.239,13.677 -19.859,33.399 -19.859,59.168l-0,181.965l-82.994,-0l-0,-181.965c-0,-25.769 -6.521,-45.491 -19.563,-59.168c-13.042,-13.678 -30.827,-20.516 -53.354,-20.516c-22.922,-0 -41.003,6.838 -54.243,20.516c-13.239,13.677 -19.859,33.399 -19.859,59.168l-0,181.965l-82.995,-0l0,-329.44l82.995,0l-0,39.842c10.67,-13.875 24.404,-24.777 41.201,-32.706c16.796,-7.929 35.272,-11.893 55.428,-11.893c25.689,-0 48.611,5.451 68.767,16.353c20.156,10.902 35.767,26.462 46.832,46.68c10.671,-19.029 26.183,-34.291 46.537,-45.788c20.353,-11.497 42.386,-17.245 66.099,-17.245Z" style="fill:#6545f5;fill-rule:nonzero;"/><path d="M1382.5,360.603c0,-33.301 6.62,-62.836 19.86,-88.604c13.239,-25.769 31.221,-45.591 53.946,-59.466c22.725,-13.875 48.117,-20.813 76.177,-20.813c24.503,0 45.943,4.956 64.321,14.867c18.377,9.91 33.099,22.398 44.165,37.463l-0,-46.978l83.587,0l-0,329.44l-83.587,-0l-0,-48.167c-10.671,15.461 -25.393,28.246 -44.165,38.355c-18.773,10.109 -40.411,15.164 -64.914,15.164c-27.665,-0 -52.859,-7.136 -75.584,-21.408c-22.725,-14.272 -40.707,-34.391 -53.946,-60.358c-13.24,-25.966 -19.86,-55.798 -19.86,-89.495Zm258.469,1.189c-0,-20.218 -3.952,-37.563 -11.857,-52.033c-7.904,-14.469 -18.575,-25.57 -32.012,-33.3c-13.437,-7.731 -27.862,-11.596 -43.275,-11.596c-15.414,-0 -29.641,3.766 -42.683,11.298c-13.042,7.533 -23.614,18.534 -31.716,33.004c-8.102,14.47 -12.153,31.616 -12.153,51.438c0,19.822 4.051,37.166 12.153,52.032c8.102,14.867 18.773,26.264 32.012,34.193c13.24,7.929 27.369,11.893 42.387,11.893c15.413,0 29.838,-3.865 43.275,-11.596c13.437,-7.73 24.108,-18.831 32.012,-33.301c7.905,-14.47 11.857,-31.814 11.857,-52.032Z" style="fill:#6545f5;fill-rule:nonzero;"/><path d="M1909.52,191.72c24.503,0 46.042,4.856 64.617,14.569c18.575,9.713 33.198,22.3 43.869,37.761l-0,-46.978l83.587,0l-0,331.819c-0,30.525 -6.126,57.78 -18.377,81.765c-12.252,23.984 -30.629,43.013 -55.132,57.087c-24.504,14.073 -54.144,21.11 -88.923,21.11c-46.635,0 -84.872,-10.902 -114.71,-32.706c-29.839,-21.804 -45.734,-48.537 -49.686,-86.198l82.401,-0c4.348,15.064 12.734,24.056 27.159,32.976c14.426,8.92 31.914,13.38 52.465,13.38c24.108,0 43.671,-7.235 58.689,-21.705c15.018,-14.47 22.527,-36.373 22.527,-65.709l-0,-51.141c-10.671,15.461 -25.393,28.345 -44.165,38.653c-18.773,10.307 -40.213,15.461 -64.321,15.461c-27.665,-0 -52.958,-7.136 -75.881,-21.408c-22.922,-14.272 -41.003,-34.391 -54.242,-60.358c-13.24,-25.966 -19.86,-55.798 -19.86,-89.495c0,-33.301 6.62,-62.836 19.86,-88.604c13.239,-25.769 31.221,-45.591 53.946,-59.466c22.725,-13.875 48.117,-20.813 76.177,-20.813Zm108.486,170.072c-0,-20.218 -3.952,-37.563 -11.857,-52.033c-7.904,-14.469 -18.575,-25.57 -32.012,-33.3c-13.437,-7.731 -27.862,-11.596 -43.276,-11.596c-15.413,-0 -29.64,3.766 -42.682,11.298c-13.042,7.533 -23.614,18.534 -31.716,33.004c-8.102,14.47 -12.153,31.616 -12.153,51.438c0,19.822 4.051,37.166 12.153,52.032c8.102,14.867 18.772,26.264 32.012,34.193c13.24,7.929 27.368,11.893 42.386,11.893c15.414,0 29.839,-3.865 43.276,-11.596c13.437,-7.73 24.108,-18.831 32.012,-33.301c7.905,-14.47 11.857,-31.814 11.857,-52.032Z" style="fill:#6545f5;fill-rule:nonzero;"/><path d="M2463.21,354.656c-0,11.893 -0.791,22.597 -2.372,32.112l-240.091,-0c1.976,23.786 10.276,42.418 24.899,55.897c14.622,13.479 32.605,20.219 53.946,20.219c30.826,-0 52.761,-13.281 65.803,-39.842l89.515,-0c-9.485,31.715 -27.665,57.78 -54.539,78.197c-26.874,20.417 -59.875,30.625 -99.001,30.625c-31.617,-0 -59.973,-7.037 -85.069,-21.111c-25.096,-14.073 -44.659,-33.994 -58.689,-59.763c-14.03,-25.768 -21.045,-55.501 -21.045,-89.198c0,-34.094 6.916,-64.025 20.749,-89.793c13.832,-25.769 33.198,-45.591 58.096,-59.466c24.898,-13.875 53.551,-20.813 85.958,-20.813c31.222,0 59.183,6.74 83.884,20.218c24.701,13.479 43.869,32.607 57.503,57.385c13.635,24.777 20.453,53.222 20.453,85.333Zm-85.959,-23.786c-0.395,-21.408 -8.102,-38.554 -23.12,-51.438c-15.018,-12.884 -33.395,-19.326 -55.132,-19.326c-20.551,-0 -37.841,6.244 -51.871,18.731c-14.03,12.488 -22.626,29.832 -25.788,52.033l155.911,-0Z" style="fill:#6545f5;fill-rule:nonzero;"/><path d="M2693.22,526.512l-111.45,-140.339l0,140.339l-82.994,-0l-0,-454.046l82.994,-0l0,264.35l110.264,-139.744l107.893,0l-144.648,165.315l145.834,164.125l-107.893,-0Z" style="fill:#6545f5;fill-rule:nonzero;"/></g><path d="M145.419,374.47l0,57.359c0,5.629 2.237,11.027 6.217,15.008c3.98,3.98 9.379,6.216 15.008,6.216l57.359,0l-57.359,0c-5.629,0 -11.028,2.236 -15.008,6.217c-3.98,3.98 -6.217,9.379 -6.217,15.008l0,57.359l0,-57.359c0,-5.629 -2.236,-11.028 -6.216,-15.008c-3.98,-3.981 -9.379,-6.217 -15.008,-6.217l-57.359,0l57.359,0c5.629,0 11.028,-2.236 15.008,-6.216c3.98,-3.981 6.216,-9.379 6.216,-15.008l0,-57.359Z" style="fill:url(#_Linear2);"/><path d="M496.134,490.373l-0,60.715c-0,5.958 2.367,11.673 6.58,15.886c4.213,4.213 9.928,6.58 15.886,6.58l60.715,0l-60.715,0c-5.958,0 -11.673,2.367 -15.886,6.581c-4.213,4.213 -6.58,9.927 -6.58,15.886l-0,60.715l-0,-60.715c-0,-5.959 -2.367,-11.673 -6.581,-15.886c-4.213,-4.214 -9.927,-6.581 -15.886,-6.581l-60.715,0l60.715,0c5.959,0 11.673,-2.367 15.886,-6.58c4.214,-4.213 6.581,-9.928 6.581,-15.886l-0,-60.715Z" style="fill:url(#_Linear3);"/><path d="M214.308,-20.291l0,110.579c0,10.852 4.311,21.259 11.984,28.933c7.674,7.673 18.082,11.984 28.934,11.984l110.578,0l-110.578,0c-10.852,0 -21.26,4.311 -28.934,11.985c-7.673,7.673 -11.984,18.081 -11.984,28.933l0,110.578l0,-110.578c0,-10.852 -4.311,-21.26 -11.984,-28.933c-7.674,-7.674 -18.082,-11.985 -28.934,-11.985l-110.578,0l110.578,0c10.852,0 21.26,-4.311 28.934,-11.984c7.673,-7.674 11.984,-18.081 11.984,-28.933l0,-110.579Z" style="fill:url(#_Linear4);"/><path d="M537.95,34.078l0,68.103c0,6.684 2.655,13.093 7.381,17.819c4.726,4.726 11.136,7.381 17.82,7.381l68.103,0l-68.103,0c-6.684,0 -13.094,2.656 -17.82,7.382c-4.726,4.726 -7.381,11.135 -7.381,17.819l0,68.103l0,-68.103c0,-6.684 -2.655,-13.093 -7.381,-17.819c-4.726,-4.726 -11.136,-7.382 -17.819,-7.382l-68.103,0l68.103,0c6.683,0 13.093,-2.655 17.819,-7.381c4.726,-4.726 7.381,-11.135 7.381,-17.819l0,-68.103Z" style="fill:url(#_Linear5);"/><path d="M605.044,177.724l-0,54.867c-0,5.385 2.139,10.549 5.946,14.356c3.808,3.808 8.972,5.947 14.356,5.947l54.868,-0l-54.868,-0c-5.384,-0 -10.548,2.139 -14.356,5.946c-3.807,3.808 -5.946,8.972 -5.946,14.357l-0,54.867l-0,-54.867c-0,-5.385 -2.139,-10.549 -5.947,-14.357c-3.807,-3.807 -8.972,-5.946 -14.356,-5.946l-54.867,-0l54.867,-0c5.384,-0 10.549,-2.139 14.356,-5.947c3.808,-3.807 5.947,-8.971 5.947,-14.356l-0,-54.867Z" style="fill:url(#_Linear6);"/><path d="M363.922,83.347c2.368,-4.668 7.158,-7.609 12.392,-7.609c5.234,-0 10.024,2.941 12.392,7.609l50.897,100.324c3.157,6.223 10.004,9.66 16.881,8.474l86.27,-14.883c4.45,-0.768 8.995,0.675 12.188,3.867c3.193,3.193 4.635,7.739 3.868,12.188l-14.883,86.271c-1.187,6.877 2.25,13.723 8.474,16.881l100.324,50.897c4.668,2.368 7.609,7.158 7.609,12.392c-0,5.234 -2.941,10.024 -7.609,12.392l-100.324,50.897c-6.224,3.157 -9.661,10.004 -8.474,16.881l14.883,86.27c0.767,4.45 -0.675,8.995 -3.868,12.188c-3.193,3.193 -7.738,4.636 -12.188,3.868l-86.27,-14.883c-6.877,-1.187 -13.724,2.25 -16.881,8.474l-50.897,100.324c-2.368,4.668 -7.158,7.609 -12.392,7.609c-5.234,-0 -10.024,-2.941 -12.392,-7.609l-50.897,-100.324c-3.158,-6.224 -10.005,-9.661 -16.882,-8.474l-86.27,14.883c-4.45,0.768 -8.995,-0.675 -12.188,-3.868c-3.193,-3.193 -4.635,-7.738 -3.867,-12.188l14.883,-86.27c1.186,-6.877 -2.251,-13.724 -8.474,-16.881l-100.325,-50.897c-4.667,-2.368 -7.608,-7.158 -7.608,-12.392c-0,-5.234 2.941,-10.024 7.608,-12.392l100.325,-50.897c6.223,-3.158 9.66,-10.004 8.474,-16.881l-14.883,-86.271c-0.768,-4.449 0.674,-8.995 3.867,-12.188c3.193,-3.192 7.738,-4.635 12.188,-3.867l86.27,14.883c6.877,1.186 13.724,-2.251 16.882,-8.474l50.897,-100.324Zm12.392,124.6c-83.787,0 -151.811,68.024 -151.811,151.811c0,83.786 68.024,151.81 151.811,151.81c83.786,0 151.81,-68.024 151.81,-151.81c0,-83.787 -68.024,-151.811 -151.81,-151.811Zm-0,17.745c73.993,-0 134.066,60.073 134.066,134.066c-0,73.993 -60.073,134.066 -134.066,134.066c-73.994,0 -134.067,-60.073 -134.067,-134.066c0,-73.993 60.073,-134.066 134.067,-134.066Zm-0,53.107c-44.683,0 -80.959,36.277 -80.959,80.959c0,44.682 36.276,80.958 80.959,80.958c44.682,0 80.958,-36.276 80.958,-80.958c0,-44.682 -36.276,-80.959 -80.958,-80.959Zm-0,40.48c22.341,-0 40.479,18.138 40.479,40.479c-0,22.341 -18.138,40.479 -40.479,40.479c-22.341,0 -40.48,-18.138 -40.48,-40.479c0,-22.341 18.139,-40.479 40.48,-40.479Z" style="fill:url(#_Linear7);"/></g><defs><linearGradient id="_Linear2" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(235.239,454.298,-454.298,235.239,235.912,135.951)"><stop offset="0" style="stop-color:#fbd248;stop-opacity:1"/><stop offset="0.5" style="stop-color:#e95a85;stop-opacity:1"/><stop offset="0.72" style="stop-color:#b752b0;stop-opacity:1"/><stop offset="1" style="stop-color:#6545f5;stop-opacity:1"/></linearGradient><linearGradient id="_Linear3" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(235.239,454.298,-454.298,235.239,260.091,123.162)"><stop offset="0" style="stop-color:#fbd248;stop-opacity:1"/><stop offset="0.5" style="stop-color:#e95a85;stop-opacity:1"/><stop offset="0.72" style="stop-color:#b752b0;stop-opacity:1"/><stop offset="1" style="stop-color:#6545f5;stop-opacity:1"/></linearGradient><linearGradient id="_Linear4" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(286.237,539.459,-539.459,286.237,208.073,131.525)"><stop offset="0" style="stop-color:#fbd248;stop-opacity:1"/><stop offset="0.5" style="stop-color:#e95a85;stop-opacity:1"/><stop offset="0.72" style="stop-color:#b752b0;stop-opacity:1"/><stop offset="1" style="stop-color:#6545f5;stop-opacity:1"/></linearGradient><linearGradient id="_Linear5" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(235.239,454.298,-454.298,235.239,294.943,119.974)"><stop offset="0" style="stop-color:#fbd248;stop-opacity:1"/><stop offset="0.5" style="stop-color:#e95a85;stop-opacity:1"/><stop offset="0.72" style="stop-color:#b752b0;stop-opacity:1"/><stop offset="1" style="stop-color:#6545f5;stop-opacity:1"/></linearGradient><linearGradient id="_Linear6" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(235.239,454.298,-454.298,235.239,261.364,141.107)"><stop offset="0" style="stop-color:#fbd248;stop-opacity:1"/><stop offset="0.5" style="stop-color:#e95a85;stop-opacity:1"/><stop offset="0.72" style="stop-color:#b752b0;stop-opacity:1"/><stop offset="1" style="stop-color:#6545f5;stop-opacity:1"/></linearGradient><linearGradient id="_Linear7" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(235.239,454.298,-454.298,235.239,261.364,141.107)"><stop offset="0" style="stop-color:#fbd248;stop-opacity:1"/><stop offset="0.5" style="stop-color:#e95a85;stop-opacity:1"/><stop offset="0.72" style="stop-color:#b752b0;stop-opacity:1"/><stop offset="1" style="stop-color:#6545f5;stop-opacity:1"/></linearGradient></defs></svg>

package/docs/security/authentication.md

@@ -0,0 +1,189 @@
+---
+title: "Authentication"
+group: "Security"
+---
+
+# Authentication
+
+Magek uses the OAuth 2.0 protocol to authenticate users. That means that it uses tokens to identify users and authorize them. These tokens are called _access tokens_ and are issued by an _authentication provider_. The most common authentication provider is [Auth0](https://auth0.com/), but you can use any other provider that supports OAuth 2.0.
+
+## Configuring the authentication provider
+
+The first step to configure authentication in Magek is to configure the authentication provider. The provider must support OAuth 2.0 and must be able to issue _access tokens_. In order to validate incoming tokens and make sure that user requests come from trustable origins, you need to provide one or more `TokenVerifier` instances at config time for each of your environments.
+
+The `TokenVerifier` class is a simple interface that you can implement to define your own token verifiers. Magek provides a `JwksUriTokenVerifier` class that you can use to configure a JWT token verifier. The `JwksUriTokenVerifier` constructor accepts the following parameters:
+
+- `issuer`: The issuer of the tokens. This is a mandatory parameter. This is commonly found in the token payload under the `iss` key.
+- `jwksUri`: The URL of the JSON Web Key Set (JWKS) that contains the public keys used to verify the tokens. This is a mandatory parameter. You can find more information about JWKS [here](https://auth0.com/docs/jwks).
+- `rolesClaim`: The name of the claim that contains the user roles. This is an optional parameter. If not provided, the `roles` claim will be used. This is commonly found in the token payload under the `roles` key.
+
+Here is an example of how to configure a `JwksUriTokenVerifier`:
+
+```typescript title="src/config/config.ts"
+
+Magek.configure('production', (config: MagekConfig): void => {
+  config.appName = 'app-name'
+  config.runtime = ServerRuntime
+  config.eventStoreAdapter = eventStore
+  config.tokenVerifiers = [
+      new JwksUriTokenVerifier(
+        'https://my-auth0-tenant.auth0.com/', // Issuer
+        'https://my-auth0-tenant.auth0.com/.well-known/jwks.json', // JWKS URL
+        'role' // Roles claim
+      ),
+    ])
+})
+```
+
+One common way to validate JWT tokens is by using a issuer-provided well-known URI on which you can find their [JSON Web Key](https://datatracker.ietf.org/doc/html/rfc7517) sets (JWKS). If you use this method, you only need to provide the issuer's name, the JWKS URI and, if you're using role-based authentication, an optional `rolesClaim` option that sets the claim from which Magek will read the role names.
+
+### JWKS URI glossary
+
+Here you can find a list of the most common authentication providers and their corresponding issuer, JWKS URI and roles claim:
+
+The issuer and JWKS URI may change depending on the region you're using. Please check the provider's documentation to find the correct values for your use case.
+
+The following list is not exhaustive and the information may be deprecated. If you want to add a new provider, or update an existing one, please open a PR to have this content up to date.
+
+| Provider    | Issuer                                          | JWKS URI                                                    |
+| ----------- | ----------------------------------------------- | ----------------------------------------------------------- |
+| Auth0       | `https://<your-tenant>.auth0.com/`              | `https://<your-tenant>.auth0.com/.well-known/jwks.json`     |
+| Okta        | `https://<your-tenant>.okta.com/oauth2/default` | `https://<your-tenant>.okta.com/oauth2/default/v1/keys`     |
+| Google      | `https://accounts.google.com`                   | `https://www.googleapis.com/oauth2/v3/certs`                |
+| Firebase    | `https://accounts.google.com`                   | `https://www.googleapis.com/oauth2/v3/certs`                |
+
+## Public key based authentication
+
+The `PublicKeyTokenVerifier` class uses the public key of the issuer to verify the token signature. This means that the issuer must provide a JWKS URI that can be used to verify the token signature. This is the most common way to verify tokens, but it's not the only one. If you want to use a different method, you can implement your own `TokenVerifier` class.
+
+This is useful when the token issuer doesn't provide a JWKS URI, when you're implementing your own authentication mechanism or you're issuing self-signed tokens.
+
+```typescript title="src/config/config.ts"
+
+function publicKeyResolver(): Promise<string> {
+  // Your implementation here
+}
+
+Magek.configure('production', (config: MagekConfig): void => {
+  config.appName = 'app-name'
+  config.runtime = ServerRuntime
+  config.eventStoreAdapter = eventStore
+  config.tokenVerifiers = [
+    new PublicKeyTokenVerifier(
+      'issuer-name', // Issuer name
+      publicKeyResolver(), // Promise that resolves to the public key string
+      'custom:roles' // Name of the claim to read the roles from (if you're using role-based authorization)
+    ),
+  ]
+})
+```
+
+Notice that the `publicKeyResolver` is a promise that resolves to a string, so it can be used to load the public key from a remote location too (i.e. get it from your KMS).
+
+If you need to handle private keys in production, consider using a KMS [(Key Management System)](https://en.wikipedia.org/wiki/Key_management#Key_storage). These systems often provide API endpoints that let you encrypt/sign your JWT tokens without exposing the private keys. The public keys can be set in a `PublicKeyTokenVerifier` to automate verification.
+
+## Custom authentication
+
+If you want to implement your own authentication mechanism, you can implement your own `TokenVerifier` class. This class must implement the following interface:
+
+```typescript
+interface TokenVerifier {
+  /**
+   * Verify asd deserialize a stringified token with this token verifier.
+   * @param token The token to verify
+   */
+  verify(token: string): Promise<DecodedToken>
+
+  /**
+   * Build a valid `UserEnvelope` from a decoded token.
+   * @param decodedToken The decoded token
+   */
+  toUserEnvelope(decodedToken: DecodedToken): UserEnvelope
+}
+```
+
+Here is an example of how to implement a custom `TokenVerifier`:
+
+```typescript title="src/config/config.ts"
+
+class CustomTokenVerifier implements TokenVerifier {
+  public async verify(token: string): Promise<DecodedToken> {
+    // Your custom token verification logic here
+  }
+
+  public toUserEnvelope(decodedToken: DecodedToken): UserEnvelope {
+    // Your custom logic to build a UserEnvelope from a decoded token here
+  }
+}
+
+Magek.configure('production', (config: MagekConfig): void => {
+  config.appName = 'app-name'
+  config.runtime = ServerRuntime
+  config.eventStoreAdapter = eventStore
+  config.tokenVerifiers = [new CustomTokenVerifier()]
+})
+```
+
+Some use cases for this could be to check that the token was generated specifically for your service by inspecting the `aud` claim, or check that the token has not been blacklisted or invalidated by your business logic (i.e. a user logs out before the token's expiration date and is included in an invalidated tokens list to make sure that an attacker that finds the token later can't use it to impersonate the legitimate owner).
+
+### Extend existing token verifiers
+
+If you only need to perform extra validations on top of one of the existing `TokenVerifier`s, you can extend one of the default implementations:
+
+```typescript
+export class CustomValidator extends PrivateKeyValidator {
+  public async verify(token: string): Promise<UserEnvelope> {
+    // Call to the PrivateKeyValidator verify method to check the signature
+    const userEnvelope = await super.verify(token)
+
+    // Do my extra validations here. Throwing an error will reject the token
+    await myExtraValidations(userEnvelope.claims, token)
+
+    return userEnvelope
+  }
+}
+```
+
+### Advanced authentication
+
+If you need to do more advanced checks, you can implement the whole verification algorithm yourself. For example, if you're using non-standard or legacy tokens. Magek exposes for convenience many of the utility functions that it uses in the default `TokenVerifier` implementations:
+
+| Function           | Description                                                                                                                                                                                        |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getJwksClient`    | Initializes a jwksRSA client that can be used to get the public key of a JWKS URI using the `getKeyWithClient` function.                                                                           |
+| `getKeyWithClient` | Initializes a function that can be used to get the public key from a JWKS URI with the signature required by the `verifyJWT` function. You can create a client using the `getJwksClient` function. |
+| `verifyJWT`        | Verifies a JWT token using a key or key resolver function and returns a Magek UserEnvelope.                                                                                                      |
+
+```typescript
+/**
+ * Initializes a jwksRSA client that can be used to get the public key of a JWKS URI using the
+ * `getKeyWithClient` function.
+ */
+export function getJwksClient(jwksUri: string) {
+  ...
+}
+
+/**
+ * Initializes a function that can be used to get the public key from a JWKS URI with the signature
+ * required by the `verifyJWT` function. You can create a client using the `getJwksClient` function.
+ */
+export function getKeyWithClient(
+  client: jwksRSA.JwksClient,
+  header: jwt.JwtHeader,
+  callback: jwt.SigningKeyCallback
+): void {
+  ...
+}
+
+/**
+ * Verifies a JWT token using a key or key resolver function and returns a Magek UserEnvelope.
+ */
+export async function verifyJWT(
+  token: string,
+  issuer: string,
+  key: jwt.Secret | jwt.GetPublicKeyOrSecret,
+  rolesClaim?: string
+): Promise<UserEnvelope> {
+ ...
+}
+```

package/docs/security/authorization.md

@@ -0,0 +1,242 @@
+---
+title: "Authorization"
+group: "Security"
+---
+
+# Authorization
+
+Magek uses a whitelisting approach to authorize users to perform commands and read models. This means that you must explicitly specify which users are allowed to perform each action. In order to do that you must configure the `authorize` policy parameter on every Command or Read Model. This parameter accepts one of the following options:
+
+- `'all'`: The command or read-model is explicitly public, any user can access it.
+- `[Role1, Role2, ...]`: An array of authorized [Roles](#defining-roles), this means that only those authenticated users that have any of the roles listed there are authorized to execute the command.
+- An authorizer function that matches the `CommandAuthorizer` interface for commands or the `ReadModelAuthorizer` interface for read models.
+
+## Making commands and read models public
+
+Setting the option `authorize: 'all'` in a command or read model will make it publicly accessible to anyone that has access to the GraphQL endpoint. For example, the following command can be executed by anyone, even if they don't provide a valid JWT token:
+
+```typescript title="src/commands/create-comment.ts"
+@Command({
+  authorize: 'all',
+})
+export class CreateComment {
+  ...
+}
+```
+
+> **Danger:** Think twice if you really need fully open GraphQL endpoints in your application, this might be useful during development, but we recommend to **avoid exposing your endpoints in this way in production**. Even for public APIs, it might be useful to issue API keys to avoid abuse. Magek is designed to scale to any given demand, but scaling also increases infrastructure costs! (See [Denial of wallet attacks](https://www.sciencedirect.com/science/article/pii/S221421262100079X))
+
+## Simple Role-based authorization
+
+Magek provides a simple role-based authentication mechanism that will work in many standard scenarios. It is based on the concept of roles, which are just a set of permissions. For example, a `User` role might have the permission to `create` and `read` comments, while an `Admin` role might have the permission to `create`, `read`, and `delete` comments. You can define as many roles as you want, and then assign them to users.
+
+### Defining @Roles
+
+As many other Magek artifacts, Magek Roles are defined as simple decorated classes. We recommend them to be defined in the `src/config/roles.ts` file, but it is not limited to that file. To define a role, you only need to decorate an empty class with the `@Role` decorator as follows:
+
+```typescript title="src/config/roles.ts"
+@Role()
+export class User {}
+
+@Role()
+export class Admin {}
+```
+
+### Protecting commands and read models with roles
+
+Once you have defined your roles, you can use them to protect your commands and read models. For example, the following command can only be executed by users that have the role `Admin`:
+
+```typescript title="src/commands/create-comment.ts"
+@Command({
+  authorize: [Admin],
+})
+export class CreateComment {
+  ...
+}
+```
+
+This command will not be available to users with the role `User`.
+
+### Associating users with roles
+
+Magek will read the roles from the JWT token that you provide in the request. The token must include a claim with the key you specidied in the `rolesClaim` field. Magek will read such field and compare it with the declared ones in the `authorize` field of the protected command or read model.
+
+For example, given the following setup:
+
+## Magek Config
+
+```typescript title="src/config/config.ts"
+
+Magek.configure('production', (config: MagekConfig): void => {
+  config.appName = 'my-store'
+  config.runtime = ServerRuntime
+  config.eventStoreAdapter = eventStore
+  config.tokenVerifiers = [
+    new JwksUriTokenVerifier(
+      'https://my-auth0-tenant.auth0.com/', // Issuer
+      'https://my-auth0-tenant.auth0.com/.well-known/jwks.json', // JWKS URL
+      // highlight-next-line
+      'firebase:groups' // <- roles are read from 'firebase:groups' claim from the token
+    ),
+  ]
+})
+```
+
+## Decoded Token
+
+```json
+{
+  // highlight-next-line
+  "firebase:groups": "User", // <- roles are read from 'firebase:groups' claim
+  "iss": "https://securetoken.google.com/demoapp",
+  "aud": "demoapp",
+  "auth_time": 1604676721,
+  "user_id": "xJY5Y6fTbVggNtDjaNh7cNSBd7q1",
+  "sub": "xJY5Y6fTbVggNtDjaNh7cNSBd7q1",
+  "iat": 1604676721,
+  "exp": 1604680321,
+  "phone_number": "+999999999",
+  "firebase": {}
+}
+```
+
+## Magek Command
+
+```typescript title="src/commands/create-comment.ts"
+@Command({
+  authorize: [Admin],
+})
+export class CreateComment {
+  ...
+}
+```
+
+## Magek Roles
+
+```typescript title="src/config/roles.ts"
+@Role()
+export class User {}
+
+@Role()
+export class Admin {}
+```
+
+Magek will check that the token contains the `firebase:groups` claim and that it contains the `Admin` role.
+Also, if the token doesn't contain the `Admin` role, the command will not be executed. As you can see, the decoded token
+has `User` as value of the `firebase:groups` claim, so the command will not be executed.
+
+## Custom authorization functions
+
+Magek also allows you to implement your own authorization functions, in case the role-based authorization model doesn't work for your application. In order to
+apply your own authorization functions, you need to provide them in the `authorize` field of the command or read model. As authorization functions are regular
+JavaScript functions, you can easily reuse them in your project or even in other Magek projects as a library.
+
+### Command Authorizers
+
+As mentioned, the `authorize` parameter of the `@Command` can receive a function. However, this function must match the `CommandAuthorizer` type. This function will receive two parameters and return a `Promise` that will resolve if the user is authorized to execute the command or reject if not:
+
+```typescript
+export type CommandAuthorizer = (currentUser?: UserEnvelope, input?: CommandInput) => Promise<void>
+```
+
+| Parameter   | Type           | Description                               |
+| ----------- | -------------- | ----------------------------------------- |
+| currentUser | `UserEnvelope` | User data decoded from the provided token |
+| input       | `CommandInput` | The input of the command                  |
+
+For instance, if you want to restrict a command to users that have a permission named `Permission-To-Rock` in the `permissions` claim you can do this:
+
+```typescript
+
+const CustomCommandAuthorizer: CommandAuthorizer = async (currentUser) => {
+    if (!currentUser.claims['permissions'].includes('Permission-To-Rock')) {
+      throw new Error(`User ${currentUser.username} should not be rocking!`) // <- This will reject the access to the command
+    }
+  }
+
+@Command({
+  authorize: CustomCommandAuthorizer,
+})
+export class PerformIncredibleGuitarSolo {
+  ...
+}
+```
+
+### Read Model Authorizers
+
+As with commands, the `authorize` parameter of the `@ReadModel` decorator can also receive a function. However, this function must match the `ReadModelAuthorizer` type. This function will receive two parameters and return a `Promise` that will resolve if the user is authorized to execute the command or reject if not:
+
+```typescript
+export type ReadModelAuthorizer<TReadModel extends ReadModelInterface> = (
+  currentUser?: UserEnvelope,
+  readModelRequestEnvelope?: ReadModelRequestEnvelope<TReadModel>
+) => Promise<void>
+```
+
+| Parameter   | Type           | Description                               |
+| ----------- | -------------- | ----------------------------------------- |
+| currentUser | `UserEnvelope` | User data decoded from the provided token |
+| input       | `CommandInput` | The input of the command                  |
+
+For instance, you may want to restrict access to a specific resource only to people that has been granted read permission:
+
+```typescript
+const CustomReadModelAuthorizer: ReadModelAuthorizer = async (currentUser, readModelRequestEnvelope) => {
+    const userPermissions = Magek.entity(UserPermissions, currentUser.username)
+    if (!userPermissions || !userPermissions.accessTo[readModelRequestEnvelope.className].includes(readModelRequestEnvelope.key.id)) {
+      throw new Error(`User ${currentUser.username} should not be looking here`)
+    }
+  }
+
+@ReadModel({
+  authorize: CustomReadModelAuthorizer
+})
+```
+
+### Event Stream Authorizers
+
+You can restrict the access to the [Event Stream](/features/event-stream) of an `Entity` by providing an `authorizeReadEvents` function in the `@Entity` decorator. This function is called every time an event stream is requested. The function must match the `EventStreamAuthorizer` type receives the current user and the event search request as parameters. The function must return a `Promise<void>`. If the promise is rejected, the request will be denied. If the promise is resolved successfully, the request will be allowed.
+
+```typescript
+export type EventStreamAuthorizer = (
+  currentUser?: UserEnvelope,
+  eventSearchRequest?: EventSearchRequest
+) => Promise<void>
+```
+
+For instance, you can restrict access to entities that the current user own.
+
+```typescript
+const CustomEventAuthorizer: EventStreamAuthorizer = async (currentUser, eventSearchRequest) => {
+  const { entityID } = eventSearchRequest.parameters
+  if (!entityID) {
+    throw new Error(`${currentUser.username} cannot list carts`)
+  }
+  const cart = Magek.entity(Cart, entityID)
+  if (cart.ownerUserName !== currentUser.userName) {
+    throw new Error(`${currentUser.username} cannot see events in cart ${entityID}`)
+  }
+}
+
+@Entity({
+  authorizeReadEvents: CustomEventAuthorizer
+})
+export class Cart {
+  @field(type => UUID)
+  readonly id!: UUID
+
+  @field()
+  readonly ownerUserName!: string
+
+  @field()
+  readonly cartItems!: Array<CartItem>
+
+  @field()
+  public shippingAddress?: Address
+
+  @field()
+  public checks: number = 0
+
+  // ... reducers
+}
+```