Policy#

What decides whether a request goes through?

On this page

A request that passed the binding meets the item's policy, which says allow, approve (wait for a human, see Approvals) or deny.

The shape#

type Policy = {
  default: "allow" | "approve" | "deny"
  rules: {
    action: "allow" | "approve" | "deny"
    methods?: string[]
    paths?: string[]
    body?: BodyMatcher
    note?: string
  }[]
}

Rules combine as deny over approve over allow, never first match wins, so adding a rule cannot silently open something. If no rule matches, default applies. A rule may name a body matcher for requests whose meaning is in the body rather than the path, such as GraphQL. Matchers fail closed: a body they cannot read in full (empty, not UTF-8, invalid JSON, a repeated JSON key, a batch) is treated as the risky case, so it is held or refused, never let through.

Policy, not intent, decides. Some reads and narrowly allowed writes run without asking, and a human may change a credential's policy from its page with a passkey. Requests in protected environments also need an approval (Projects, environments and runs).

What templates allow, hold and refuse#

Provider templates fail closed. For an item made from a template:

Reads are allowed (GET, HEAD), except a read that hands back another secret: a database password or connection string, a decrypted environment variable, a stored secret, a mail server's details. Those need an approval.
Every other method needs a human's approval by default, except a few narrow everyday writes the template allows explicitly: model calls for an AI provider, searches and scrapes for a search API, read-only queries.
Sends and money movements are pinned to an approval, so no later allow rule can open them: email and messages, payouts and refunds, anything billed, and root access to a server.
The worst routes are denied outright: anything that sends mail or data elsewhere for good (forwarding, filters, mailbox rules, delegates, webhooks, destinations, log drains), gives someone else access (SSH and deploy keys, collaborators, members, invitations, roles, app registrations), mints or revokes tokens, or cannot be shown honestly on an approval card; and deleting a whole project, team or organisation.

mehen templates <id> prints a template's rules as three lines (without a human, needs approval, refused), and mehen show <item> shows an item's policy. Providers and templates lists every template's three lines. Do not look for a way round a denied route; use the alternative:

You try to	The vault	Do this instead
Send a saved Gmail draft by id (`drafts/send`)	Denies it (`policy_denied`)	A draft can change after the send is approved, so the approval could not show what is sent. Send the whole message with `POST .../messages/send` and a `raw` body; the approval shows it.
Send a stored Microsoft Graph message by id, or forward or reply to a stored message	Denies it	The same reason. Send the whole message with `sendMail`.
Use Microsoft Graph `$batch`	Denies it	A batch carries requests the vault cannot check one by one. Send each request on its own.
Change mail forwarding, delegates, filters, mailbox rules or settings; add SSH or deploy keys, webhooks, collaborators or app registrations	Denies it	These give lasting access to someone else. Ask the human to do it themselves, outside the vault.
Mint or revoke an API token, invite a member, add a webhook, log drain or event destination, or delete a whole project or organisation	Denies it	The same reason, and a deleted project does not come back. Ask the human to do it in the provider's own console.
Read a Fathom recording's summary or transcript	Holds it for approval	That route can post the text to any URL named in its query, which no rule can see. List meetings with `GET /meetings?include_transcript=true` instead.
Call Notion	Needs a `Notion-Version` header	The vault adds only the secret; send `Notion-Version` yourself on every request.
Reach a scoped npm package (`@scope/name`)	Refuses it as an ambiguous path	Its name travels as `@scope%2fname`, an encoded slash. Unscoped packages work; ask the human to publish a scoped one.
Run a GitHub GraphQL request	Allows a read-only query that a strict matcher can read in full; holds anything else for approval	Prefer a plain query, or the REST endpoint.

Credentials without a template#

A credential stored without a template (an agent proposed its binding) fails closed as well: its policy is approve by default with no rules, so every request waits for a human. The intake page offers one tick, unticked, to let reads (GET, HEAD, OPTIONS) through without asking; the passkey signs that choice with the rest of the form. A rotation keeps the item's policy, and a template's intake takes the template's. Only a human can widen a policy afterwards, from the item's page with a passkey.

How the summaries are written#

The three policy lines (without a human, needs approval, refused) for a built-in template use the template's reviewed notes ("reads; creates a draft; changes labels"). For an item, they describe each rule from what it matches (method and paths), never from its note, because nothing proves an item's policy is a template's. "anything else" always lands on the line of the policy's default. mehen check runs the same matcher locally to say what a request would get; it is advisory (Find a credential and call an API).

Policy proposals#

mehen policy preview and propose exist in the command line, but the vault refuses them in this release with forbidden ("Policy widening is not available yet"). Do not retry them; a policy window never stands in for a protected context. mehen policy show, cancel and stop work.