Check Shapes: can, canAny, can.fresh, and require

Every check in Alfiz flows through one of two shapes: can is the authorization gate, and canAny is the visibility affordance. A third form, can.fresh, carries the same signature as can but bypasses every cache. It exists because bounded staleness is acceptable on most reads but never on destructive writes. Understanding which shape to reach for, and when, is the core of using Alfiz correctly.

`can(principal, key, scope?)`

can is the only valid gate shape. Call it before performing any state-changing operation or returning protected data.

const allowed: boolean = await alfiz.can(
  { userId },           // PrincipalRef
  "docs.files.read",   // K, compile-time verified against the catalog
  "docs.doc:123",      // ScopeId (optional; omit for global checks)
);

principal is a PrincipalRef, a discriminated union:

{ userId: string }      // a human user
{ serviceId: string }   // a service account

Pass the shape that matches your session: { userId: session.userId } for user sessions, { serviceId: "export-worker" } for machine callers. key is a typed template-literal derived from your catalog. The TypeScript compiler rejects any string that is not a declared leaf. You can also pass a readonly array of keys, and can returns true when the principal holds any one of them:

await alfiz.can({ userId }, ["docs.files.read", "docs.files.update_file"], "docs.doc:123");

scope is an optional ScopeId: the resource instance being accessed (e.g., "docs.doc:123", "docs.folder:9"). Omit it for global checks. When a principal holds the key at any ancestor of the scope, can returns true, because hierarchy is resolved at check time. can returns Promise<boolean>. It never throws on a denied check; use require when you want a throw instead.

Every call to can is verified against the catalog before evaluation. If the key is not declared, Alfiz throws UnknownPermissionError, a programming error and not a denial. Map it to a 500, never to a 403.

`can.fresh(principal, key, scope?)`

can.fresh carries exactly the same signature as can but bypasses all caches: subject closures are not read from the cache, and object ancestor chains are re-fetched from the provider.

// Destructive action: always use can.fresh
const allowed = await alfiz.can.fresh(
  { userId },
  "docs.files.delete",
  "docs.folder:9",
);

When to use can.fresh:

Destructive actions. Deleting, publishing, or transferring a resource where a stale allow would be worse than a brief latency hit.
Just-in-time elevations. The principal was just granted emergency access and must be able to act on it immediately, without waiting for a cache TTL.

Why it exists, and the staleness bounds: Subject-side closures are cached for subjectCacheTtlMs (default 30 seconds). A revocation can therefore take up to 30 seconds to propagate to can responses. On most read paths that bound is acceptable. On destructive paths it is not, and can.fresh is the explicit escape hatch.

Pair can.fresh with destructive server actions as a convention: can.fresh makes the staleness contract visible at the call site, so reviewers know the action is being explicit about freshness.

`canAny(principal, pattern)`

canAny is the visibility affordance. It answers the question: does this principal hold anything matching pattern, at any scope? Use it to show or hide navigation items and section headings.

const visible: boolean = await alfiz.canAny(
  { userId },
  "docs.*",   // PatternOf<typeof catalog>, a catalog-typed wildcard pattern
);

pattern is a wildcard string derived from the catalog’s $pattern union, for example "docs.*" or "docs.files.*". Passing an undeclared pattern throws UnknownPermissionError.

canAny is never a gate. It tells you whether a section is worth showing. It does not authorize any action. The alfiz-verify static verifier emits an error whenever canAny appears inside a server action or route handler. Gate on a concrete key with can or require.

`require` and `requireAny`

require and requireAny are the throwing forms of can and canAny. They return Promise<void> and throw AccessDeniedError when the check fails.

// Throws AccessDeniedError on denial
await alfiz.require(
  { userId },
  "docs.files.update_file",
  "docs.doc:123",
);

// Throws AccessDeniedError if the principal holds nothing under "docs.*"
await alfiz.requireAny({ userId }, "docs.*");

AccessDeniedError carries a typed reason field:

import { AccessDeniedError } from "@alfiz/core";

try {
  await alfiz.require({ userId }, "docs.files.delete", "docs.folder:9");
} catch (err) {
  if (err instanceof AccessDeniedError) {
    // err.reason: "unauthenticated" | "forbidden" | "inactive"
    // err.permission: the key(s) that were checked
    // err.scope: the scope that was checked (if any)
    return redirect(err.reason === "unauthenticated" ? "/login" : "/403");
  }
  throw err;
}

Use require at the top of server actions and route handlers where you want a single thrown value to carry all downstream error handling. Use the boolean can when you need to branch without catching.

`snapshot(principal, options?)`: one round-trip, synchronous checks

Server-rendered frameworks make hundreds of conditional-UI checks inside .map() callbacks and pure helpers that cannot be async. snapshot solves this: one provider round-trip, then every subsequent check is synchronous.

// Once per request, one provider round-trip. Name the hierarchical scopes
// you intend to check, so their ancestor chains resolve now.
const snap = await alfiz.snapshot({ userId }, { scopes: ["docs.doc:123"] });

// Every check below is synchronous, so it is safe inside .map() and render helpers
snap.can("docs.files.read");                        // GLOBAL scope, not "anywhere"
snap.can("docs.files.update_file", "docs.doc:123"); // scoped, synchronous
snap.canAny("docs.*");                              // visibility affordance
snap.require("docs.files.read");                    // throws AccessDeniedError on deny
snap.holds("docs.files.delete");                    // held at ANY scope: unscoped UI hint
snap.heldKeys;                                      // ReadonlySet<PermissionKey>

A snapshot is a stronger consistency guarantee than repeated can calls: every check in a request sees one subject-data instant and one evaluation clock. The caches do not tick over mid-render. List pages. When you do not know your row scope IDs until after the query:

const snap = await alfiz.snapshot({ userId });
snap.require("docs.files.read");                    // gate the page

const rows = await db.docs.findMany({ ... });       // query now
await snap.resolve(rows.map((r) => `docs.doc:${r.id}`));

// Now synchronous per-row checks are safe
const editable = rows.filter((r) =>
  snap.can("docs.files.update_file", `docs.doc:${r.id}`)
);

Pass { fresh: true } to bypass caches at snapshot time, the same way can.fresh does for individual checks.

const snap = await alfiz.snapshot({ userId }, { fresh: true });

Flat scope types, meaning those declared parent: null and not multiParent, are always synchronously resolvable from a snapshot. Hierarchical scope types require pre-resolution, either via client.snapshot(principal, { scopes: [...] }) up front, or await snap.resolve([...]) once the IDs are known. Checking an unresolved hierarchical scope throws, rather than silently evaluating a truncated chain.

Staleness reference

Cache layer	Default TTL	Bust mechanism
Subject closures	30 s	Provider `user`, `subject`, `role`, `catalog`, or `all` invalidation event
Object ancestor chains	60 s	Provider `scope` event for any scope in the chain, or a `catalog` / `all` event; `app.notifyScopeMoved(scope)` from your code emits the `scope` event

can.fresh bypasses both layers. For moves your application makes in its own tables, call app.notifyScopeMoved(scope) from the same code path that changes the parent pointer. The TTL is the backstop and not the primary mechanism.

Get Started

The Catalog

Checks & Enforcement

Subjects & Access

Requests & Approvals

Growth Path

Operations

Alfiz Cloud

Check Shapes: can, canAny, can.fresh, and require

`can(principal, key, scope?)`

`can.fresh(principal, key, scope?)`

`canAny(principal, pattern)`

`require` and `requireAny`

`snapshot(principal, options?)`: one round-trip, synchronous checks

Staleness reference

​can(principal, key, scope?)

​can.fresh(principal, key, scope?)

​canAny(principal, pattern)

​require and requireAny

​snapshot(principal, options?): one round-trip, synchronous checks

​Staleness reference

`can(principal, key, scope?)`

`can.fresh(principal, key, scope?)`

`canAny(principal, pattern)`

`require` and `requireAny`

`snapshot(principal, options?)`: one round-trip, synchronous checks

Staleness reference