Skip to main content
Alfiz is scoped permissions for TypeScript applications: declared in code, verified in CI, checked in your own process. It does no authentication. Identity stays with your identity provider and resource data stays in your database, and Alfiz owns what sits between them: who may do what, where, and why. You declare your permission catalog once in the codebase that enforces it, and every runtime check runs in-process against your own database. Nothing Alfiz operates ever sits on your request path. The word scoped is the qualifier that matters. If a role column is enough for your application, admin and user and nothing more, Alfiz is more machinery than you need. It earns its place when access is per-folder, per-document, per-tenant, or otherwise attached to specific objects rather than to the whole application.

​
The three layers

Alfiz is organized into three layers. The first two are open-source packages you install today; the third is Alfiz Cloud, added only when you need it. The Client/Provider split is enforced in code, not convention. The provider contract has three normative artifacts, held in exact correspondence by the type system and the test suite: the AlfizProvider interface a Client attaches to, the AlfizProviderBase abstract class every provider extends, and the Alfiz Provider API, an OpenAPI document fixing the contract’s wire form. Exactly two kinds of implementation exist, both in @alfiz/application: the local provider (AlfizApplication, your database) and the hosted provider (HostedProvider, an API connection to the same contract served elsewhere, which is the seam the Dashboard and Federation ride on). Because the wire form is a language-agnostic document rather than a TypeScript export, a provider can be implemented, and consumed, from any language. See Provider API setup for the wire conventions and what they buy.
Runtime checks never leave your application in any topology. Every can() runs in-process against your catalog, your rows, and your resolver, so nothing Alfiz operates can slow or break your app.

​
Four commitments

These four decisions make up the product, and none of them is configurable.

Declared in code

The catalog declares every permission and every scope type, in the codebase that enforces them. Nothing is inferred from call sites and nothing is dashboard-configured, so there is no second list anywhere that can drift out of sync with this one.

Checked in your own process

Every can() runs in-process against your own database. Nothing Alfiz operates is on your request path, so nothing it does can slow, throttle, or stop a check.

Typed end to end

Keys and patterns are template-literal types derived from your catalog. A typo in a permission key is a compile error rather than a silent false you discover in production.

Verified in CI

alfiz-verify proves both directions match: nothing is enforced that the catalog does not declare, and the build warns on anything declared that no gate references.
Two further semantics are worth knowing early, because they shape how you model access. Grants nest: one made at an enclosing scope covers everything within it, resolved by walking up ancestors at check time, with no rows fanned out to descendants. And the grant tuple and check shape are identical in every topology, standalone or linked or federated, so growing your deployment never rewrites your call sites.

​
What’s included in the packages

The Client (@alfiz/core) and Application (@alfiz/application) are the whole system for one organization with one application. Nothing below is held back for a paid tier:
  • Permission grammar, catalog, and typed keys. Catalog-derived template-literal types mean every literal call site is verified at compile time, and every runtime-string path is verified against the catalog before evaluation
  • can / require / canAny / can.fresh / holds. In-process checks; canAny and holds are visibility affordances only, never gates; can.fresh bypasses all caches for destructive actions
  • Per-request snapshots. One provider round-trip, then synchronous checks safe inside .map()
  • Four enforcement points. Page, navigation visibility, server action, and conditional UI; the verifier catches surfaces that skip any of the four
  • Static verification and catalog lints. alfiz-verify fails the build on an exported action with no gate, a visibility affordance used as a gate, an unknown key, and client-reachable service-key material
  • Scoped grants, revokes, expiry, and provenance. Every grant is one row: (subject, role-or-pattern, scope, expiry?) with a full provenance record and an audit entry
  • Groups, nested groups, roles, and reporting hierarchy. Union-only inheritance throughout; the single negative layer is the personal revoke
  • Access requests and management-layer approvals. Requestable roles and scope types flow through a built-in staged approval workflow, including manager-chain approval
  • Sessions and view-as. Typed per-request sessions with admin preview that fails closed and never mis-attributes
  • Permission metrics. An optional observation per check, an OpenTelemetry adapter, a local aggregator, and the revocation safeguard
  • The headless permission tree. The wildcard-aware selection logic (buildPermissionTree, toggleNode, isNodeChecked) behind any role editor or grant picker you build, plus listing helpers that push a permission filter into your own SQL
The @alfiz/prisma package adds a Prisma storage driver and schema fragment so the Application layer slots straight into your existing Prisma setup; @alfiz/mongo does the same for MongoDB, with no schema to merge. @alfiz/verify ships the alfiz-verify CLI.
Alfiz does not issue or validate tokens, and ships no identity-provider adapter. You verify the session with your own provider, whether that is Clerk or Auth.js or anything else, and pass the resulting user id to Alfiz. See Sessions for the wiring.

​
Alfiz Cloud

When a non-engineer needs to administer access, or when your second application arrives, Alfiz Cloud extends the open-source foundation without replacing it.

Dashboard

A hosted, styled, maintained UI for managing grants, approvals, and audit history. Add admin seats and your team uses it immediately; your Application stays the org root and the only writer, because every relayed write lands in the same provider methods your local code calls.

Federation

When you need cross-application authorization, federation adds a central catalog registry (namespace ownership, versioning, tombstones), cross-namespace role composition, cross-application request aggregation, and service-principal credential management.
Alfiz is never in your request path. Every can() runs in-process against your own database, so Alfiz Cloud is not a dependency of your application: it cannot add latency to a check, cannot throttle one, and cannot fail in a way that stops one. That holds in every topology, including full federation.Pricing follows from it. Alfiz Cloud bills for the work it performs: admin seats, federated applications, provisioned connectors, retained audit volume. Check volume is not a billing dimension and will not become one. See Metering and caps.

​
Next steps

Quickstart

Install @alfiz/core and @alfiz/application, define your first catalog, and run your first can() check in minutes.

Core Concepts

Understand the catalog, scope types, grant model, inheritance rules, and the four enforcement points in depth.