@teikyo/access 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Le Cam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @teikyo/access
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+
+```sh
+pnpm add @teikyo/access @sozai/http-server hono
+```
+
+## Grants 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.
+
+```ts
+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:
+
+1. the token issuer holds a grant matching the procedure;
+2. the token `sub` holds 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 `sub` is the server identity is checked directly as a capability. The `verifyToken` hook still runs on its chain, so with `access.revocation` enabled the capability can be revoked, and while `requireJTI` is `true` it must carry a `jti`.
+- A token whose `iss` is 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
+
+```ts
+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')
+```
+
+- `GrantStore` upserts grants by `(subject, pattern)`, normalises subject DIDs and validates patterns.
+- `GrantCache` holds active grants per subject for `ttlMs` (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 by `issuer`, and the hook looks up the capability's own issuer, so another identity cannot revoke or shadow a jti it does not own.
+- `requireJTI` defaults to `true`, so capabilities created without an explicit `jti` are rejected with `Capability without jti rejected`; set it to `false` to accept them (they can never be revoked).
+- Register the store through the plugin, which carries the DID resolution options (`resolver`, `cache`, `methods`) that `add` needs.

package/lib/grants/cache.d.ts

@@ -0,0 +1,21 @@
+import type { GrantStore } from './store.js';
+export type GrantCacheParams = {
+    store: GrantStore;
+    /** Maximum age of a cached entry in milliseconds, a non-negative integer (0 disables caching). Defaults to 5000. */
+    ttlMs?: number;
+    /** Maximum number of cached subjects; the least recently used is evicted first. Defaults to 10000. */
+    maxEntries?: number;
+    /** Clock override, returning epoch milliseconds. */
+    now?: () => number;
+};
+/** Whether `ttlMs` is a usable cache lifetime: a non-negative safe integer (0 disables caching). */
+export declare function isValidTTL(ttlMs: number): boolean;
+/** Per-subject cache of active grants, invalidated by store changes and grant expiry. */
+export declare class GrantCache {
+    #private;
+    constructor(params: GrantCacheParams);
+    allows(subject: string, procedure: string): Promise<boolean>;
+    /** Stop listening to the store and drop all cached state. */
+    dispose(): void;
+    [Symbol.dispose](): void;
+}

package/lib/grants/cache.js

@@ -0,0 +1,106 @@
+import { normalizeDID } from '@kokuin/token';
+import { patternMatches } from '../patterns.js';
+const DEFAULT_TTL_MS = 5000;
+const DEFAULT_MAX_ENTRIES = 10_000;
+/** Whether `ttlMs` is a usable cache lifetime: a non-negative safe integer (0 disables caching). */ export function isValidTTL(ttlMs) {
+    return Number.isSafeInteger(ttlMs) && ttlMs >= 0;
+}
+/** Per-subject cache of active grants, invalidated by store changes and grant expiry. */ export class GrantCache {
+    #store;
+    #ttlMs;
+    #maxEntries;
+    #now;
+    #entries = new Map();
+    #refills = new Map();
+    #unsubscribe;
+    #disposed = false;
+    constructor(params){
+        const maxEntries = params.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+            throw new Error('Invalid maxEntries');
+        }
+        // `Infinity` would keep entries for grants without expiry forever, so changes made by another
+        // process would never be observed; `NaN` or a negative value would silently disable the cache.
+        const ttlMs = params.ttlMs ?? DEFAULT_TTL_MS;
+        if (!isValidTTL(ttlMs)) {
+            throw new Error('Invalid ttlMs');
+        }
+        this.#store = params.store;
+        this.#ttlMs = ttlMs;
+        this.#maxEntries = maxEntries;
+        this.#now = params.now ?? Date.now;
+        this.#unsubscribe = this.#store.onChange((subject)=>{
+            this.#entries.delete(subject);
+            this.#refills.delete(subject);
+        });
+    }
+    #grantsFor(subject) {
+        const now = this.#now();
+        const cached = this.#entries.get(subject);
+        if (cached != null) {
+            if (now < cached.expiresAt) {
+                // Re-insert to mark as most recently used.
+                this.#entries.delete(subject);
+                this.#entries.set(subject, cached);
+                return cached.grants;
+            }
+            this.#entries.delete(subject);
+        }
+        const pending = this.#refills.get(subject);
+        if (pending != null) {
+            return pending.promise;
+        }
+        const token = Symbol('refill');
+        const isCurrent = ()=>this.#refills.get(subject)?.token === token;
+        const promise = this.#store.activeGrants(subject, now).then((grants)=>{
+            if (isCurrent()) {
+                this.#refills.delete(subject);
+                let expiresAt = now + this.#ttlMs;
+                for (const grant of grants){
+                    if (grant.expiresAt != null && grant.expiresAt < expiresAt) {
+                        expiresAt = grant.expiresAt;
+                    }
+                }
+                this.#remember(subject, {
+                    grants,
+                    expiresAt
+                });
+            }
+            return grants;
+        }, (error)=>{
+            if (isCurrent()) {
+                this.#refills.delete(subject);
+            }
+            throw error;
+        });
+        this.#refills.set(subject, {
+            promise,
+            token
+        });
+        return promise;
+    }
+    #remember(subject, entry) {
+        this.#entries.set(subject, entry);
+        while(this.#entries.size > this.#maxEntries){
+            const oldest = this.#entries.keys().next();
+            if (oldest.done) break;
+            this.#entries.delete(oldest.value);
+        }
+    }
+    async allows(subject, procedure) {
+        if (this.#disposed) {
+            throw new Error('GrantCache is disposed');
+        }
+        const grants = await this.#grantsFor(normalizeDID(subject));
+        return grants.some((grant)=>patternMatches(grant.pattern, procedure));
+    }
+    /** Stop listening to the store and drop all cached state. */ dispose() {
+        this.#disposed = true;
+        this.#unsubscribe();
+        this.#entries.clear();
+        this.#refills.clear();
+    }
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+}

package/lib/grants/migrations.d.ts

@@ -0,0 +1,2 @@
+import type { Migration, MigrationContext } from '@hozon/db';
+export declare function grantStoreMigrations(ctx: MigrationContext): Record<string, Migration>;

package/lib/grants/migrations.js

@@ -0,0 +1,16 @@
+export function grantStoreMigrations(ctx) {
+    return {
+        '0-init': {
+            async up (db) {
+                await db.schema.createTable('grants').addColumn('subject', ctx.types.text, (column)=>column.notNull()).addColumn('pattern', ctx.types.text, (column)=>column.notNull()).addColumn('expires_at', ctx.types.bigint).addColumn('created_at', ctx.types.bigint, (column)=>column.notNull()).addColumn('created_by', ctx.types.text, (column)=>column.notNull()).addPrimaryKeyConstraint(`${ctx.tablePrefix}_grants_pkey`, [
+                    'subject',
+                    'pattern'
+                ]).execute();
+                await db.schema.createIndex(`${ctx.tablePrefix}_grants_subject`).on('grants').column('subject').execute();
+            },
+            async down (db) {
+                await db.schema.dropTable('grants').execute();
+            }
+        }
+    };
+}

package/lib/grants/plugin.d.ts

@@ -0,0 +1,16 @@
+import type { AllowPredicate } from '@enkaku/server';
+import { type HTTPPlugin } from '@sozai/http-server';
+import { HOZON_DB } from '@teikyo/hozon';
+import { type GrantStore } from './store.js';
+export type AccessGrants = {
+    store: GrantStore;
+    /** Build an Enkaku access predicate admitting issuers, or verified delegates, holding a matching grant. */
+    allow(): AllowPredicate;
+};
+export declare const ACCESS_GRANTS: import("@sozai/http-server").PluginName<"access:grants", AccessGrants>;
+export type AccessGrantsPluginParams = {
+    /** Maximum age of cached grants in milliseconds, a non-negative integer (0 disables caching). */
+    cacheTTLMs?: number;
+};
+/** Provide the grant store and an `allow()` predicate backed by a grant cache. */
+export declare function accessGrantsPlugin(params?: AccessGrantsPluginParams): HTTPPlugin<'access:grants', AccessGrants, [typeof HOZON_DB]>;

package/lib/grants/plugin.js

@@ -0,0 +1,48 @@
+import { pluginName } from '@sozai/http-server';
+import { HOZON_DB } from '@teikyo/hozon';
+import { GrantCache, isValidTTL } from './cache.js';
+import { GRANT_STORE, grantStoreDefinition } from './store.js';
+export const ACCESS_GRANTS = pluginName()('access:grants');
+/** Provide the grant store and an `allow()` predicate backed by a grant cache. */ export function accessGrantsPlugin(params = {}) {
+    if (params.cacheTTLMs != null && !isValidTTL(params.cacheTTLMs)) {
+        throw new Error('Invalid cacheTTLMs');
+    }
+    return {
+        name: ACCESS_GRANTS,
+        dependsOn: [
+            HOZON_DB
+        ],
+        async setup (ctx) {
+            const db = ctx.use(HOZON_DB);
+            db.register(grantStoreDefinition);
+            const store = await db.getStore(GRANT_STORE);
+            const cache = new GrantCache({
+                store,
+                ttlMs: params.cacheTTLMs
+            });
+            ctx.onClose(()=>cache.dispose());
+            return {
+                store,
+                allow: ()=>async ({ payload, procedure, verifyDelegation })=>{
+                        try {
+                            if (await cache.allows(payload.iss, procedure)) {
+                                return true;
+                            }
+                            if (payload.sub != null && await cache.allows(payload.sub, procedure)) {
+                                return await verifyDelegation();
+                            }
+                            return false;
+                        } catch (cause) {
+                            ctx.logger.error('access check failed for {procedure}', {
+                                procedure,
+                                error: cause
+                            });
+                            throw new Error('Access denied', {
+                                cause
+                            });
+                        }
+                    }
+            };
+        }
+    };
+}

package/lib/grants/store.d.ts

@@ -0,0 +1,42 @@
+import type { Kysely, StoreDefinition } from '@hozon/db';
+import type { GrantTables } from './tables.js';
+export type Grant = {
+    subject: string;
+    pattern: string;
+    expiresAt: number | null;
+    createdAt: number;
+    createdBy: string;
+};
+export type GrantParams = {
+    subject: string;
+    pattern: string;
+    createdBy: string;
+    expiresAt?: number;
+};
+export type RevokeParams = {
+    subject: string;
+    pattern?: string;
+};
+export type GrantStore = {
+    /**
+     * Add a grant, or replace the expiry and audit fields of an existing grant for the same subject
+     * and pattern -- the latest grant wins. Throws inside a database transaction, because listeners
+     * could not be notified after the commit.
+     */
+    grant(params: GrantParams): Promise<void>;
+    /**
+     * Remove one grant, or all grants of the subject when no pattern is given. Returns the rows
+     * removed. Throws inside a database transaction.
+     */
+    revoke(params: RevokeParams): Promise<number>;
+    list(params?: {
+        subject?: string;
+    }): Promise<Array<Grant>>;
+    /** Grants of the subject that have not expired at the given time. */
+    activeGrants(subject: string, now: number): Promise<Array<Grant>>;
+    /** Register a listener called after each committed mutation. Returns an unsubscribe function. */
+    onChange(listener: (subject: string) => void): () => void;
+};
+export declare function createGrantStoreAPI(db: Kysely<GrantTables>): GrantStore;
+export declare const GRANT_STORE = "teikyo-grants";
+export declare const grantStoreDefinition: StoreDefinition<GrantTables, GrantStore>;

package/lib/grants/store.js

@@ -0,0 +1,105 @@
+import { assertValidPattern } from '@kokuin/capability';
+import { normalizeDID } from '@kokuin/token';
+import { getLogger } from '@sozai/log';
+import { grantStoreMigrations } from './migrations.js';
+function toGrant(row) {
+    return {
+        subject: row.subject,
+        pattern: row.pattern,
+        expiresAt: row.expires_at == null ? null : Number(row.expires_at),
+        createdAt: Number(row.created_at),
+        createdBy: row.created_by
+    };
+}
+const TRANSACTION_ERROR = 'Grant mutations cannot run inside a transaction';
+const logger = getLogger([
+    'teikyo',
+    'access',
+    'grants'
+]);
+export function createGrantStoreAPI(db) {
+    const listeners = new Set();
+    function assertTopLevel() {
+        if (db.isTransaction) {
+            throw new Error(TRANSACTION_ERROR);
+        }
+    }
+    function notify(subject) {
+        for (const listener of listeners){
+            try {
+                listener(subject);
+            } catch (error) {
+                // A failing listener must not affect the others or the mutation result.
+                logger.error('grant change listener failed for {subject}', {
+                    subject,
+                    error
+                });
+            }
+        }
+    }
+    return {
+        async grant (params) {
+            assertTopLevel();
+            assertValidPattern(params.pattern);
+            if (params.expiresAt !== undefined && !Number.isSafeInteger(params.expiresAt)) {
+                throw new Error('Invalid grant expiry');
+            }
+            const subject = normalizeDID(params.subject);
+            const expiresAt = params.expiresAt ?? null;
+            const createdAt = Date.now();
+            const createdBy = normalizeDID(params.createdBy);
+            await db.insertInto('grants').values({
+                subject,
+                pattern: params.pattern,
+                expires_at: expiresAt,
+                created_at: createdAt,
+                created_by: createdBy
+            }).onConflict((conflict)=>conflict.columns([
+                    'subject',
+                    'pattern'
+                ]).doUpdateSet({
+                    expires_at: expiresAt,
+                    created_at: createdAt,
+                    created_by: createdBy
+                })).execute();
+            notify(subject);
+        },
+        async revoke (params) {
+            assertTopLevel();
+            const subject = normalizeDID(params.subject);
+            let query = db.deleteFrom('grants').where('subject', '=', subject);
+            if (params.pattern != null) {
+                query = query.where('pattern', '=', params.pattern);
+            }
+            const result = await query.executeTakeFirst();
+            notify(subject);
+            return Number(result.numDeletedRows);
+        },
+        async list (params) {
+            let query = db.selectFrom('grants').selectAll().orderBy('created_at').orderBy('pattern');
+            if (params?.subject != null) {
+                query = query.where('subject', '=', normalizeDID(params.subject));
+            }
+            return (await query.execute()).map(toGrant);
+        },
+        async activeGrants (subject, now) {
+            const rows = await db.selectFrom('grants').selectAll().where('subject', '=', normalizeDID(subject)).where((eb)=>eb.or([
+                    eb('expires_at', 'is', null),
+                    eb('expires_at', '>', now)
+                ])).execute();
+            return rows.map(toGrant);
+        },
+        onChange (listener) {
+            listeners.add(listener);
+            return ()=>{
+                listeners.delete(listener);
+            };
+        }
+    };
+}
+export const GRANT_STORE = 'teikyo-grants';
+export const grantStoreDefinition = {
+    name: GRANT_STORE,
+    migrations: grantStoreMigrations,
+    createAPI: createGrantStoreAPI
+};

package/lib/grants/tables.d.ts

@@ -0,0 +1,9 @@
+export type GrantTables = {
+    grants: {
+        subject: string;
+        pattern: string;
+        expires_at: number | null;
+        created_at: number;
+        created_by: string;
+    };
+};

package/lib/grants/tables.js

@@ -0,0 +1 @@
+export { };

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+export { GrantCache, type GrantCacheParams } from './grants/cache.js';
+export { ACCESS_GRANTS, type AccessGrants, type AccessGrantsPluginParams, accessGrantsPlugin, } from './grants/plugin.js';
+export { GRANT_STORE, type Grant, type GrantParams, type GrantStore, grantStoreDefinition, type RevokeParams, } from './grants/store.js';
+export type { GrantTables } from './grants/tables.js';
+export { patternMatches, patternsOverlap } from './patterns.js';
+export { createRevocationHook, createRevocationStoreDefinition, REVOCATION_STORE, type RevocationHookParams, type RevocationStoreAPI, type RevocationStoreParams, } from './revocation/backend.js';
+export { ACCESS_REVOCATION, type AccessRevocation, type AccessRevocationPluginParams, accessRevocationPlugin, } from './revocation/plugin.js';
+export type { RevocationTables } from './revocation/tables.js';

package/lib/index.js

@@ -0,0 +1,6 @@
+export { GrantCache } from './grants/cache.js';
+export { ACCESS_GRANTS, accessGrantsPlugin } from './grants/plugin.js';
+export { GRANT_STORE, grantStoreDefinition } from './grants/store.js';
+export { patternMatches, patternsOverlap } from './patterns.js';
+export { createRevocationHook, createRevocationStoreDefinition, REVOCATION_STORE } from './revocation/backend.js';
+export { ACCESS_REVOCATION, accessRevocationPlugin } from './revocation/plugin.js';

package/lib/patterns.d.ts

@@ -0,0 +1,4 @@
+/** Whether an access pattern covers a procedure, using the matcher Enkaku applies to access rules. */
+export declare function patternMatches(pattern: string, procedure: string): boolean;
+/** Whether two access patterns can both cover at least one procedure. */
+export declare function patternsOverlap(a: string, b: string): boolean;

package/lib/patterns.js

@@ -0,0 +1,11 @@
+import { hasPartsMatch } from '@kokuin/capability';
+/** Whether an access pattern covers a procedure, using the matcher Enkaku applies to access rules. */ export function patternMatches(pattern, procedure) {
+    return hasPartsMatch(procedure, pattern);
+}
+function baseOf(pattern) {
+    return pattern.endsWith('/*') ? pattern.slice(0, -2) : pattern;
+}
+/** Whether two access patterns can both cover at least one procedure. */ export function patternsOverlap(a, b) {
+    if (a === '*' || b === '*') return true;
+    return patternMatches(a, baseOf(b)) || patternMatches(b, baseOf(a));
+}

package/lib/revocation/backend.d.ts

@@ -0,0 +1,27 @@
+import type { StoreDefinition } from '@hozon/db';
+import { type RevocationBackend, type RevocationOptions, type VerifyTokenHook } from '@kokuin/capability';
+import type { RevocationTables } from './tables.js';
+/**
+ * Revocation backend of the store. `get` is scoped by issuer because the jti namespace belongs to
+ * each issuer: any identity can sign a valid revocation record for any jti, so a lookup by jti
+ * alone could return another issuer's record.
+ */
+export type RevocationStoreAPI = RevocationBackend;
+export type RevocationStoreParams = RevocationOptions;
+export declare const REVOCATION_STORE = "teikyo-revocations";
+/** Store definition carrying the resolution options `add` needs; register it through the plugin. */
+export declare function createRevocationStoreDefinition(options?: RevocationStoreParams): StoreDefinition<RevocationTables, RevocationStoreAPI>;
+export type RevocationHookParams = {
+    backend: RevocationStoreAPI;
+    /** Reject capabilities that carry no jti, which could never be revoked. */
+    requireJTI: boolean;
+    /** Called with the underlying cause of an infrastructure failure, before it is masked. */
+    onError: (cause: unknown) => void;
+    options?: RevocationOptions;
+};
+/**
+ * Build the Enkaku `verifyToken` hook. Lookups are bound to the token's issuer. Failures other than
+ * a revocation are logged through `onError` and surface as `Access denied`, because Enkaku copies
+ * error messages to the client.
+ */
+export declare function createRevocationHook(params: RevocationHookParams): VerifyTokenHook;

package/lib/revocation/backend.js

@@ -0,0 +1,85 @@
+import { createRevocationChecker } from '@kokuin/capability';
+import { normalizeDID, verifyToken } from '@kokuin/token';
+import { b64uToJSON } from '@sozai/codec';
+import { revocationStoreMigrations } from './migrations.js';
+export const REVOCATION_STORE = 'teikyo-revocations';
+function toRecord(row) {
+    // The signed data is authoritative: header and payload are rebuilt from it, not stored separately.
+    const [header = '', payload = ''] = row.data.split('.');
+    return {
+        header: b64uToJSON(header),
+        payload: b64uToJSON(payload),
+        signature: row.signature,
+        data: row.data
+    };
+}
+/**
+ * Create the revocation store API. `add` verifies the record's signature before storing it, like
+ * the in-memory backend of `@kokuin/capability`. It has no listeners to notify, so unlike grant
+ * mutations it is safe inside a database transaction: the row commits or rolls back with it.
+ */ function createRevocationStoreAPI(options = {}) {
+    return (db)=>{
+        return {
+            async add (record) {
+                const verified = await verifyToken(record, {
+                    historic: true,
+                    resolver: options.resolver,
+                    cache: options.cache,
+                    methods: options.methods
+                });
+                if (verified.payload.rev !== true || typeof verified.payload.jti !== 'string') {
+                    throw new Error('Invalid revocation record');
+                }
+                await db.insertInto('revocations').values({
+                    issuer: normalizeDID(verified.payload.iss),
+                    jti: verified.payload.jti,
+                    // Only the signed material is stored, never the caller's whole object.
+                    data: verified.data,
+                    signature: verified.signature,
+                    created_at: Date.now()
+                })// The first record per issuer wins: another record for the same issuer and jti is the
+                // same revocation, so this is idempotent.
+                .onConflict((conflict)=>conflict.columns([
+                        'issuer',
+                        'jti'
+                    ]).doNothing()).execute();
+            },
+            async get (jti, issuer) {
+                const row = await db.selectFrom('revocations').select([
+                    'data',
+                    'signature'
+                ]).where('issuer', '=', normalizeDID(issuer)).where('jti', '=', jti).executeTakeFirst();
+                return row == null ? undefined : toRecord(row);
+            }
+        };
+    };
+}
+/** Store definition carrying the resolution options `add` needs; register it through the plugin. */ export function createRevocationStoreDefinition(options) {
+    return {
+        name: REVOCATION_STORE,
+        migrations: revocationStoreMigrations,
+        createAPI: createRevocationStoreAPI(options)
+    };
+}
+/**
+ * Build the Enkaku `verifyToken` hook. Lookups are bound to the token's issuer. Failures other than
+ * a revocation are logged through `onError` and surface as `Access denied`, because Enkaku copies
+ * error messages to the client.
+ */ export function createRevocationHook(params) {
+    return async (token, raw)=>{
+        if (params.requireJTI && token.payload.jti == null) {
+            throw new Error('Capability without jti rejected');
+        }
+        try {
+            await createRevocationChecker(params.backend, params.options)(token, raw);
+        } catch (cause) {
+            if (cause instanceof Error && cause.message.startsWith('Token revoked:')) {
+                throw cause;
+            }
+            params.onError(cause);
+            throw new Error('Access denied', {
+                cause
+            });
+        }
+    };
+}

package/lib/revocation/migrations.d.ts

@@ -0,0 +1,2 @@
+import type { Migration, MigrationContext } from '@hozon/db';
+export declare function revocationStoreMigrations(ctx: MigrationContext): Record<string, Migration>;

package/lib/revocation/migrations.js

@@ -0,0 +1,15 @@
+export function revocationStoreMigrations(ctx) {
+    return {
+        '0-init': {
+            async up (db) {
+                await db.schema.createTable('revocations').addColumn('issuer', ctx.types.text, (column)=>column.notNull()).addColumn('jti', ctx.types.text, (column)=>column.notNull()).addColumn('data', ctx.types.text, (column)=>column.notNull()).addColumn('signature', ctx.types.text, (column)=>column.notNull()).addColumn('created_at', ctx.types.bigint, (column)=>column.notNull()).addPrimaryKeyConstraint(`${ctx.tablePrefix}_revocations_pkey`, [
+                    'issuer',
+                    'jti'
+                ]).execute();
+            },
+            async down (db) {
+                await db.schema.dropTable('revocations').execute();
+            }
+        }
+    };
+}

package/lib/revocation/plugin.d.ts

@@ -0,0 +1,16 @@
+import type { RevocationOptions, VerifyTokenHook } from '@kokuin/capability';
+import { type HTTPPlugin } from '@sozai/http-server';
+import { HOZON_DB } from '@teikyo/hozon';
+import { type RevocationStoreAPI } from './backend.js';
+export type AccessRevocation = {
+    backend: RevocationStoreAPI;
+    /** Enkaku `verifyToken` hook rejecting revoked capabilities. */
+    verifyToken: VerifyTokenHook;
+};
+export declare const ACCESS_REVOCATION: import("@sozai/http-server").PluginName<"access:revocation", AccessRevocation>;
+export type AccessRevocationPluginParams = RevocationOptions & {
+    /** Reject capabilities without a jti, which cannot be revoked. Defaults to `true`. */
+    requireJTI?: boolean;
+};
+/** Provide a persistent revocation backend and the `verifyToken` hook that consults it. */
+export declare function accessRevocationPlugin(params?: AccessRevocationPluginParams): HTTPPlugin<'access:revocation', AccessRevocation, [typeof HOZON_DB]>;

package/lib/revocation/plugin.js

@@ -0,0 +1,31 @@
+import { pluginName } from '@sozai/http-server';
+import { HOZON_DB } from '@teikyo/hozon';
+import { createRevocationHook, createRevocationStoreDefinition, REVOCATION_STORE } from './backend.js';
+export const ACCESS_REVOCATION = pluginName()('access:revocation');
+/** Provide a persistent revocation backend and the `verifyToken` hook that consults it. */ export function accessRevocationPlugin(params = {}) {
+    const { requireJTI = true, ...options } = params;
+    return {
+        name: ACCESS_REVOCATION,
+        dependsOn: [
+            HOZON_DB
+        ],
+        async setup (ctx) {
+            const db = ctx.use(HOZON_DB);
+            db.register(createRevocationStoreDefinition(options));
+            const backend = await db.getStore(REVOCATION_STORE);
+            return {
+                backend,
+                verifyToken: createRevocationHook({
+                    backend,
+                    requireJTI,
+                    options,
+                    onError: (cause)=>{
+                        ctx.logger.error('revocation lookup failed', {
+                            error: cause
+                        });
+                    }
+                })
+            };
+        }
+    };
+}

package/lib/revocation/tables.d.ts

@@ -0,0 +1,11 @@
+export type RevocationTables = {
+    revocations: {
+        /** Normalised DID of the record's issuer. */
+        issuer: string;
+        jti: string;
+        /** The signed `header.payload` string of the record. */
+        data: string;
+        signature: string;
+        created_at: number;
+    };
+};

package/lib/revocation/tables.js

@@ -0,0 +1 @@
+export { };

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@teikyo/access",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Access grants and revocation for Enkaku servers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TairuFramework/teikyo.git",
+    "directory": "packages/access"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/*"
+  ],
+  "dependencies": {
+    "@enkaku/server": "^0.21.4",
+    "@hozon/db": "^0.2.1",
+    "@kokuin/capability": "^0.4.0",
+    "@kokuin/token": "^0.5.0",
+    "@sozai/codec": "^0.4.2",
+    "@sozai/http-server": "^0.1.0",
+    "@sozai/log": "^0.4.0",
+    "@teikyo/hozon": "^0.1.1"
+  },
+  "devDependencies": {
+    "@hozon/provider": "^0.1.1",
+    "@types/node": "^26.6.4",
+    "del-cli": "^7.0.0",
+    "vitest": "5.0.3"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del-cli lib",
+    "build:js": "del-cli \"lib/**/*.js\" && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del-cli \"lib/**/*.d.ts\" \"lib/**/*.d.ts.map\" && tsc --emitDeclarationOnly --skipLibCheck",
+    "build:types:ci": "tsc --emitDeclarationOnly --skipLibCheck --declarationMap false",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
 }