Secure, advanced, and flexible access management stack for web3.

🌐 Website • 📚 Documentation

What's the Armory?

The Armory Stack is an open-source access management system tailored for uses-case that need strong authentication and fine-grained authorization. It is designed to secure the usage of private keys, wallets, and web3 applications.

It's a web3-native policy engine combined with a highly customizable next-gen auth system, able to be deployed in a variety of secure configurations.

Requirements

Node.js 21+

Docker

OPA CLI (if not running in Docker) link

Getting started

To setup the project, run the following command:

git clone git@github.com:narval-xyz/narval.git
cd narval
make setup

At the end, you must have a working environment ready to run any application.

Alternatively, if you want to set up each application individually, you can check Armory, Policy Engine, and Vault "Getting started" sections.

Docker

We use Docker & docker-compose to run the application's dependencies.

make docker/up
make docker/stop

Alternatively, you can run the entire development stack in Docker containers.

Important

This builds a local dev image that mounts your filesystem into the container. Only db schema, dependency, or config changes require re-building. Do not use this build for production.

# Build the application's image.
make docker/stack/build

make docker/stack/up
make docker/stop

Testing

To run tests across all existing projects, you can use the following commands:

# Run all tests
make test

make test/type
make test/unit
make test/integration
make test/e2e

These commands utilize the NX CLI's run-many feature to execute the specified targets (test or test:type) across all projects in the monorepo.

Formatting

We use Prettier and ESLint to ensure code consistency. You can run the following commands to format and lint the whole code base.

# Format and lint all the code.
make format
make lint

# Check for formatting and linting errors without fixing them.
make format/check
make lint/check

NPM

The .npmrc file is needed to access a private registry for the optional dependency @narval-xyz/armory-mpc-module.

Important

This file is NOT in git, but it's necessary for the build if you're using MPC to sign decisions in the Policy Engine.

1. Create a .npmrc file in the root of this project.
2. Get the values from someone who has them.
3. Now npm install should work.

Generating a new project

NX provides two types of projects: applications and libraries. Run the commands below to generate a project of your choice.

# Generate an standard JavaScript library.
npx nx g @nrwl/js:lib
# Generate an NestJS library.
npx nx g @nx/nest:library
# Generate an NestJS application.
npx nx g @nx/nest:application --tags type:application

For more information about code generation, please refer to the NX documentation.

Publishing packages

This section describes the process to release a new version of publishable packages to NPM.

1. Run make packages/release and follow the prompts to bump the projects' versions.
2. Run npm install to update package-lock.json.
3. Commit and push the changes to your branch.
4. After your branch is merged, manually trigger the packages pipeline to publish the new version to NPM.

You can find the publishable packages listed in the release.projects value in the nx.json.

OpenTelemetry

The Armory Stack uses OpenTelemetry (OTEL) for observability through traces and metrics.

For details on how OTEL is instrumented, head over @narval/open-telemetry.

Setup

1. Start local dependencies:

make docker/otel/up

2. Set environment variables:

OTEL_SDK_DISABLED=false
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Note

OTEL is disabled by default in development.

3. Restart the application.

4. Access Jaeger UI: http://localhost:16686

Naming Conventions

• Traces: operation.entity.action (e.g., policyStore.policies.update)
• Metrics: system_entity_unit_state (e.g., policy_store_updates_total)

See Metric Naming and Trace/Span Name adopted conventions.

Debugging

If you want to debug traces, the best way is to run make docker/otel/up and check the Jaeger UI at http://localhost:16686.

In contrast, if you want to debug application instrumentation, open the .env file and set OTEL_LOG_LEVEL=debug to have a better view of what the SDK is doing.

Troubleshooting

DB URL in env variable fails when using docker run, but works when running outside docker

If using docker run --env-file .env ..., the env file cannot include quotes around values. The quotes will be included in the value.

localhost PSQL URL cannot connect

Inside docker, localhost points to the container not your computer (host). Change localhost to host.docker.internal to reference to the host IP address in the local network.

License

Armory is MPL 2.0 licensed.

You can find an exhaustive list of licenses of third-party software dependencies used by the Armory at LICENSES_DISCLOSURE.md.

To generate the list, run ./tools/licenses-disclosure/main.sh > LICENSES_DISCLOSURE.md.