@teikyo/access
v0.6.0
Published
Access grants and revocation for Enkaku servers
Readme
@teikyo/access
Access grants and capability revocation for Enkaku servers on @sozai/http-server. It provides the access:grants and access:revocation plugins (exported as ACCESS_GRANTS and ACCESS_REVOCATION), both backed by the hozon:db plugin from @teikyo/hozon, plus a short-lived grant cache and the access pattern helpers.
Install
pnpm add @teikyo/access @sozai/http-server honoGrants plugin
accessGrantsPlugin() provides the grant store and an allow() predicate for Enkaku access rules. It is normally consumed through @teikyo/enkaku's access.grants option.
import { createServer } from '@sozai/http-server'
import { accessGrantsPlugin, accessRevocationPlugin } from '@teikyo/access'
import { hozonDBPlugin } from '@teikyo/hozon'
const server = await createServer({
plugins: [
hozonDBPlugin({ db: './app.db' }),
accessGrantsPlugin({ cacheTTLMs: 5000 }),
accessRevocationPlugin({ requireJTI: true }),
],
})| Option | Type | Description |
| --- | --- | --- |
| accessGrantsPlugin({ cacheTTLMs }) | number (optional) | Maximum age of cached grants in milliseconds, 5000 by default. Must be a non-negative integer (0 disables caching); anything else throws Invalid cacheTTLMs. |
| accessRevocationPlugin({ requireJTI }) | boolean (optional) | Reject capabilities without a jti. Defaults to true. It also accepts the DID resolution options (resolver, cache, methods). |
Rule composition
The allow() predicate admits a caller when any of these holds:
- the token issuer holds a grant matching the procedure;
- the token
subholds a matching grant and the delegation chain verifies, so a delegate acts with the grants of the subject that delegated to it.
Anything else is denied, and a store failure is logged and denied with Access denied. When used through @teikyo/enkaku, the gated patterns get this predicate and caller-supplied rules must not overlap them (see that package).
Operator capability
Enkaku handles two server-identity cases before access rules are consulted, and neither calls the grants predicate or needs a grant:
- A token whose
subis the server identity is checked directly as a capability. TheverifyTokenhook still runs on its chain, so withaccess.revocationenabled the capability can be revoked, and whilerequireJTIistrueit must carry ajti. - A token whose
issis the server identity itself bypasses both the rules and the revocation hook.
Issue such capabilities and keys only to operators.
Cache delay across processes
GrantCache drops a subject's entry as soon as the store in the same process reports a change. A grant created or revoked by another process sharing the database is only seen once the cached entry expires, so the delay is at most one cache TTL (cacheTTLMs, 5 s by default).
Store and cache
import { GRANT_STORE, GrantCache, type GrantStore, grantStoreDefinition } from '@teikyo/access'
db.register(grantStoreDefinition)
const store = await db.getStore<GrantStore>(GRANT_STORE)
await store.grant({ subject: 'did:key:z6Mk...', pattern: 'app/*', createdBy: 'did:key:z6Mk...' })
const cache = new GrantCache({ store })
await cache.allows('did:key:z6Mk...', 'app/read')GrantStoreupserts grants by(created_by, subject, pattern), normalises DIDs and validates patterns.grantandrevokerequirecreatedBy, scope writes to that creator, and increment its set version.replaceSetatomically replaces one creator's grants usingexpectedVersion. Stale versions throwGrantVersionConflictErrorwithcurrentVersion.getSetVersionreturns zero before the first mutation.replaceSetcan enforcemaxEntries, throwingGrantLimitErrorwithout writes.accessGrantsPlugin({ operators })reconcilesconfig:operatorsto oneadmin/*grant per configured DID during setup.reconcileOperators(store, { dids, pattern? })exposes the same reconciliation with an optional pattern.GrantCacheholds active grants per subject forttlMs(default 5000), or until the earliest grant expiry, and drops a subject's entry as soon as the store reports a change.patternMatches(pattern, procedure)uses the matcher Enkaku applies to access rules;patternsOverlap(a, b)reports whether two patterns can cover a common procedure.
Revocation
accessRevocationPlugin() (plugin name access:revocation) provides a Hozon-backed revocation store and a verifyToken hook for Enkaku servers.
- Records are scoped by issuer: the store's
get(jti, issuer)only returns records signed byissuer, and the hook looks up the capability's own issuer, so another identity cannot revoke or shadow a jti it does not own. requireJTIdefaults totrue, so tokens created without an explicitjtiare rejected withToken without jti rejected; set it tofalseto accept them (they can never be revoked).- Register the store through the plugin, which carries the DID resolution options (
resolver,cache,methods) thataddneeds.
