hnq.me
all concepts
security Updated 2026-07-09 Step 4 of 6

Grant

A beginner-friendly guide to understanding grants and runtime authority.

On this page 2026-07-09
The Simple Idea Why Grants Exist Grant vs Capability Identity And Grant Grant Checking Grants And Capsules Good Grant Design KitJS And Kitwork Notes My Learning Notes Common Misunderstandings Related Concepts

A beginner-friendly guide to grants: explicit permissions given to an identity so a runtime can decide what code is allowed to do.

A grant answers:

who is allowed to do what?

Table of Contents

The Simple Idea

A grant is a set of powers assigned to an identity.

Example:

guest: posts:read
editor: posts:read, posts:write
admin: posts:read, posts:write, posts:delete

The runtime can compare what code needs against what the identity has.

Why Grants Exist

Systems need to make authority explicit.

Without grants, code may rely on vague checks:

is admin?
is logged in?
is owner?

Those checks can work, but they become hard to reason about.

A grant gives the runtime a clearer shape:

identity has these capabilities

Grant vs Capability

A capability is a specific power.

A grant is a collection of capabilities assigned to an identity.

capability: posts:read
grant: user has posts:read and comments:write

Capabilities describe powers.

Grants attach powers to identities.

Identity And Grant

An identity may be:

  • guest,
  • user,
  • admin,
  • tenant owner,
  • service account,
  • API token,
  • session,
  • capsule sender.

The grant should come from trusted server-side authority.

The client should not be allowed to invent its own grant.

Grant Checking

Grant checking asks:

needed capabilities subset of granted capabilities?

Example:

capsule needs: posts:read
identity grant: posts:read, comments:write
result: allowed

If the capsule needs posts:delete, the same grant should reject it.

Grants And Capsules

Capsules make grants important.

If the client sends logic, the server must not trust it.

The runtime should inspect what the capsule needs and compare it with the identity's grant.

capsule needs capability
identity has grant
runtime intersects them

Only then should execution proceed.

Good Grant Design

Good grants are:

  • explicit,
  • narrow,
  • easy to audit,
  • server-owned,
  • tenant-aware,
  • easy to revoke,
  • simple enough to reason about.

Avoid grants that are too broad by default.

The runtime should give code only the powers it needs.

KitJS And Kitwork Notes

Grant is the word that appears when a runtime stops treating authority as a global assumption. In KitJS, most behavior is local to the page and the DOM. In Kitwork, code can live inside a tenant, a route, a server handler, or a future capsule, so the runtime needs a clearer way to say which identity receives which power.

This is why grant belongs near capsule, sandbox, and capability. It is not a UI idea; it is a trust boundary idea.

My Learning Notes

Kitwork's capsule direction made grants feel necessary.

If logic can cross from client to server, the runtime needs a way to decide what that logic is allowed to touch.

The lesson:

identity tells who you are
grant tells what powers you have
runtime enforces the boundary

Common Misunderstandings

"Grant and capability are the same."

They are related. A capability is a power. A grant gives powers to an identity.

"The client can send its grant."

No. The client can send intent. Authority should come from the server.

"Admin checks are enough forever."

Simple apps can start there. Larger runtimes benefit from explicit grants.

Previous: gas

Next: host

Related: capability, capsule, sandbox

Search