Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: surface the diff doc #9

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: surface the diff doc #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions astro.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ export default defineConfig({
link: '/guides/webpack',
},
{ label: 'Policy files', link: '/guides/policy' },
{ label: 'Policy review', link: '/guides/policy-diff' },
{
label: 'Troubleshooting Common Problems',
link: '/guides/troubleshooting',
Expand Down
8 changes: 6 additions & 2 deletions src/content/docs/guides/policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,15 @@ This guide will help you understand what a LavaMoat Policy is and how to use it.

## What's a Policy?

A Policy is an object that describes which _resources_ any given dependency can access. These "resources" include globals, builtins (e.g., `node:fs`), native modules, and other packages. _All direct and transitive dependencies_ in your application's dependency tree are subject to a Policy.
A Policy is an object that describes which _powers_ any given dependency can access. These "powers" include globals, builtins (e.g., `node:fs`), native modules, and other packages. _All direct and transitive dependencies_ in your application's dependency tree are subject to a Policy.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A Policy is an object that describes which _powers_ any given dependency can access. These "powers" include globals, builtins (e.g., `node:fs`), native modules, and other packages. _All direct and transitive dependencies_ in your application's dependency tree are subject to a Policy.
A Policy is an object that describes which _capabilities_ any given dependency can access. These capabilities include globals, builtins (e.g., `node:fs`), native modules, and other packages. _All direct and transitive dependencies_ in your application's dependency tree are subject to a Policy.

Why "powers"? Is this an existing concept from elsewhere or minted here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a concept from Object Capability programming and I also defined iit in the glossary now.
You can't frequent Endo meetings to become more familiar with the terminology, but they're recorded and you can catch up on them on Agoric's youtube.
Here's an archive https://www.youtube.com/watch?v=tM5NyB7xxYM&list=PLzDw4TTug5O0eUj81Vnkp-mFuI4O0rBnc
Not sure if the latest ones were being added to the playlist. Check main channel.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll shave the yak on the difference between capabilities and powers internally


**The behavior of _your application_ is not restricted by the Policy.** A Policy _only_ applies to direct and transitive dependencies of your application.

Policies are fundamental to LavaMoat's operation.

## Policy Files: `policy.json` and `policy-override.json`

When getting stared with LavaMoat, you'll first generate a Policy file using the LavaMoat CLI. To do this, LavaMoat crawls your application's dependency tree and determines which resources each dependency is _currently_ using. In other words, auto-generating a Policy takes a _snapshot_ of the permissions at a point in time. LavaMoat writes this policy to `policy.json`.
When getting stared with LavaMoat, you'll first generate a Policy file using the LavaMoat CLI. To do this, LavaMoat crawls your application's dependency tree and determines which powers each dependency is _currently_ using. In other words, auto-generating a Policy takes a _snapshot_ of the permissions at a point in time. LavaMoat writes this policy to `policy.json`.
naugtur marked this conversation as resolved.
Show resolved Hide resolved

At some point, you'll want to add, update, or remove dependencies. When you do, you'll want to have LavaMoat _re-generate_ `policy.json`—another snapshot.

Expand All @@ -38,6 +38,10 @@ Both `policy.json` and `policy-override.json` should be under version control. T

:::

:::note[Reviewing Policy]
[Learn how to review your policy and policy diffs](./policy-diff)
:::

## Policy, By Example

Say we generate a Policy file for an application with the following dependency tree, where `app.js` is the entry point:
Expand Down
Loading