@teikyo/access 0.5.0 → 0.6.0

package/README.md

@@ -66,7 +66,12 @@ 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.
+- `GrantStore` upserts grants by `(created_by, subject, pattern)`, normalises DIDs and validates patterns.
+- `grant` and `revoke` require `createdBy`, scope writes to that creator, and increment its set version.
+- `replaceSet` atomically replaces one creator's grants using `expectedVersion`. Stale versions throw `GrantVersionConflictError` with `currentVersion`.
+- `getSetVersion` returns zero before the first mutation. `replaceSet` can enforce `maxEntries`, throwing `GrantLimitError` without writes.
+- `accessGrantsPlugin({ operators })` reconciles `config:operators` to one `admin/*` grant per configured DID during setup.
+- `reconcileOperators(store, { dids, pattern? })` exposes the same reconciliation with an optional pattern.
 - `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.
 

package/lib/admin/handlers.d.ts

@@ -0,0 +1,9 @@
+import type { ProcedureHandlers } from '@enkaku/server';
+import type { AccessGrants } from '../grants/plugin.js';
+import type { AccessAdminProtocol } from './protocol.js';
+export type AccessAdminHandlersParams = {
+    grants: AccessGrants;
+    maxEntries?: number;
+};
+/** WARNING: mount behind Enkaku's `admin/*` grant check, because handlers rely on transport authorisation. */
+export declare function createAccessAdminHandlers({ grants, maxEntries, }: AccessAdminHandlersParams): ProcedureHandlers<AccessAdminProtocol>;

package/lib/admin/handlers.js

@@ -0,0 +1,98 @@
+import { HandlerError } from '@enkaku/server';
+import { normalizeDID } from '@kokuin/token';
+import { GrantLimitError, GrantVersionConflictError } from '../grants/store.js';
+import { patternsOverlap } from '../patterns.js';
+function issuer(payload) {
+    if (typeof payload.iss !== 'string') throw new HandlerError({
+        code: 'ACCESS_DENIED',
+        message: 'Verified caller required'
+    });
+    return payload.iss;
+}
+function assertGrantable(pattern) {
+    if (patternsOverlap(pattern, 'admin/*')) {
+        throw new HandlerError({
+            code: 'FORBIDDEN_PATTERN',
+            message: 'Admin patterns are configured by operators'
+        });
+    }
+}
+async function mutate(operation) {
+    try {
+        return await operation();
+    } catch (error) {
+        if (error instanceof GrantVersionConflictError) {
+            throw HandlerError.from(error, {
+                code: 'VERSION_CONFLICT',
+                data: {
+                    currentVersion: error.currentVersion
+                },
+                message: error.message
+            });
+        }
+        if (error instanceof GrantLimitError) throw HandlerError.from(error, {
+            code: 'LIMIT',
+            message: error.message
+        });
+        throw error;
+    }
+}
+/** WARNING: mount behind Enkaku's `admin/*` grant check, because handlers rely on transport authorisation. */ export function createAccessAdminHandlers({ grants, maxEntries }) {
+    const store = grants.store;
+    return {
+        'admin/grants/list': async ({ message, param })=>{
+            const createdBy = param.createdBy ?? issuer(message.payload);
+            return await store.listSet(createdBy);
+        },
+        'admin/grants/set': async ({ message, param })=>{
+            for (const entry of param.entries)assertGrantable(entry.pattern);
+            return await mutate(()=>{
+                return store.replaceSet({
+                    ...param,
+                    createdBy: issuer(message.payload),
+                    maxEntries
+                });
+            });
+        },
+        'admin/grants/add': async ({ message, param })=>{
+            assertGrantable(param.pattern);
+            const createdBy = issuer(message.payload);
+            // Use replaceSet so limits and version checks remain atomic with the mutation.
+            const version = await store.getSetVersion(createdBy);
+            const entries = (await store.list({
+                createdBy
+            })).filter((entry)=>{
+                return entry.subject !== normalizeDID(param.subject) || entry.pattern !== param.pattern;
+            }).map((entry)=>{
+                return {
+                    subject: entry.subject,
+                    pattern: entry.pattern,
+                    ...entry.expiresAt === null ? {} : {
+                        expiresAt: entry.expiresAt
+                    }
+                };
+            });
+            entries.push(param);
+            return await mutate(()=>{
+                return store.replaceSet({
+                    createdBy,
+                    entries,
+                    expectedVersion: version,
+                    maxEntries
+                });
+            });
+        },
+        'admin/grants/remove': async ({ message, param })=>{
+            assertGrantable(param.pattern);
+            const createdBy = issuer(message.payload);
+            await store.revoke({
+                createdBy,
+                subject: param.subject,
+                pattern: param.pattern
+            });
+            return {
+                version: await store.getSetVersion(createdBy)
+            };
+        }
+    };
+}

package/lib/admin/protocol.d.ts

@@ -0,0 +1,151 @@
+export declare const accessAdminProtocol: {
+    readonly 'admin/grants/list': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly createdBy: {
+                    readonly type: "string";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly version: {
+                    readonly type: "integer";
+                };
+                readonly entries: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly expiresAt: {
+                                readonly type: readonly ["integer", "null"];
+                            };
+                            readonly createdBy: {
+                                readonly type: "string";
+                            };
+                            readonly createdAt: {
+                                readonly type: "integer";
+                            };
+                            readonly subject: {
+                                readonly type: "string";
+                            };
+                            readonly pattern: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["subject", "pattern", "expiresAt", "createdBy", "createdAt"];
+                        readonly additionalProperties: false;
+                    };
+                };
+            };
+            readonly required: readonly ["entries", "version"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'admin/grants/set': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly entries: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly subject: {
+                                readonly type: "string";
+                            };
+                            readonly pattern: {
+                                readonly type: "string";
+                            };
+                            readonly expiresAt: {
+                                readonly type: "integer";
+                            };
+                        };
+                        readonly required: readonly ["subject", "pattern"];
+                        readonly additionalProperties: false;
+                    };
+                };
+                readonly expectedVersion: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                };
+            };
+            readonly required: readonly ["entries", "expectedVersion"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly version: {
+                    readonly type: "integer";
+                };
+            };
+            readonly required: readonly ["version"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'admin/grants/add': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly subject: {
+                    readonly type: "string";
+                };
+                readonly pattern: {
+                    readonly type: "string";
+                };
+                readonly expiresAt: {
+                    readonly type: "integer";
+                };
+            };
+            readonly required: readonly ["subject", "pattern"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly version: {
+                    readonly type: "integer";
+                };
+            };
+            readonly required: readonly ["version"];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly 'admin/grants/remove': {
+        readonly type: "request";
+        readonly param: {
+            readonly type: "object";
+            readonly properties: {
+                readonly subject: {
+                    readonly type: "string";
+                };
+                readonly pattern: {
+                    readonly type: "string";
+                };
+                readonly expiresAt: {
+                    readonly type: "integer";
+                };
+            };
+            readonly required: readonly ["subject", "pattern"];
+            readonly additionalProperties: false;
+        };
+        readonly result: {
+            readonly type: "object";
+            readonly properties: {
+                readonly version: {
+                    readonly type: "integer";
+                };
+            };
+            readonly required: readonly ["version"];
+            readonly additionalProperties: false;
+        };
+    };
+};
+export type AccessAdminProtocol = typeof accessAdminProtocol;

package/lib/admin/protocol.js

@@ -0,0 +1,119 @@
+const entry = {
+    type: 'object',
+    properties: {
+        subject: {
+            type: 'string'
+        },
+        pattern: {
+            type: 'string'
+        },
+        expiresAt: {
+            type: 'integer'
+        }
+    },
+    required: [
+        'subject',
+        'pattern'
+    ],
+    additionalProperties: false
+};
+const version = {
+    type: 'object',
+    properties: {
+        version: {
+            type: 'integer'
+        }
+    },
+    required: [
+        'version'
+    ],
+    additionalProperties: false
+};
+export const accessAdminProtocol = {
+    'admin/grants/list': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                createdBy: {
+                    type: 'string'
+                }
+            },
+            additionalProperties: false
+        },
+        result: {
+            type: 'object',
+            properties: {
+                version: {
+                    type: 'integer'
+                },
+                entries: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            ...entry.properties,
+                            expiresAt: {
+                                type: [
+                                    'integer',
+                                    'null'
+                                ]
+                            },
+                            createdBy: {
+                                type: 'string'
+                            },
+                            createdAt: {
+                                type: 'integer'
+                            }
+                        },
+                        required: [
+                            'subject',
+                            'pattern',
+                            'expiresAt',
+                            'createdBy',
+                            'createdAt'
+                        ],
+                        additionalProperties: false
+                    }
+                }
+            },
+            required: [
+                'entries',
+                'version'
+            ],
+            additionalProperties: false
+        }
+    },
+    'admin/grants/set': {
+        type: 'request',
+        param: {
+            type: 'object',
+            properties: {
+                entries: {
+                    type: 'array',
+                    items: entry
+                },
+                expectedVersion: {
+                    type: 'integer',
+                    minimum: 0
+                }
+            },
+            required: [
+                'entries',
+                'expectedVersion'
+            ],
+            additionalProperties: false
+        },
+        result: version
+    },
+    'admin/grants/add': {
+        type: 'request',
+        param: entry,
+        result: version
+    },
+    'admin/grants/remove': {
+        type: 'request',
+        param: entry,
+        result: version
+    }
+};

package/lib/grants/cache.js

@@ -1,5 +1,6 @@
 import { normalizeDID } from '@kokuin/token';
 import { patternMatches } from '../patterns.js';
+import { OPERATORS_CREATOR_ID } from './operators.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) {
@@ -92,7 +93,9 @@ const DEFAULT_MAX_ENTRIES = 10_000;
             throw new Error('GrantCache is disposed');
         }
         const grants = await this.#grantsFor(normalizeDID(subject));
-        return grants.some((grant)=>patternMatches(grant.pattern, procedure));
+        return grants.some((grant)=>{
+            return (!procedure.startsWith('admin/') || grant.createdBy === OPERATORS_CREATOR_ID) && patternMatches(grant.pattern, procedure);
+        });
     }
     /** Stop listening to the store and drop all cached state. */ dispose() {
         this.#disposed = true;

package/lib/grants/migrations.js

@@ -11,6 +11,32 @@ export function grantStoreMigrations(ctx) {
             async down (db) {
                 await db.schema.dropTable('grants').execute();
             }
+        },
+        '1-owner-key': {
+            async up (db) {
+                await db.schema.createTable('grants_owned').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_owner_pkey`, [
+                    'created_by',
+                    'subject',
+                    'pattern'
+                ]).execute();
+                await db.insertInto('grants_owned').columns([
+                    'subject',
+                    'pattern',
+                    'expires_at',
+                    'created_at',
+                    'created_by'
+                ]).expression(db.selectFrom('grants').select([
+                    'subject',
+                    'pattern',
+                    'expires_at',
+                    'created_at',
+                    'created_by'
+                ])).execute();
+                await db.schema.dropTable('grants').execute();
+                await db.schema.alterTable('grants_owned').renameTo('grants').execute();
+                await db.schema.createIndex(`${ctx.tablePrefix}_grants_subject`).on('grants').column('subject').execute();
+                await db.schema.createTable('grant_sets').addColumn('created_by', ctx.types.text, (column)=>column.notNull().primaryKey()).addColumn('version', 'integer', (column)=>column.notNull()).execute();
+            }
         }
     };
 }

package/lib/grants/operators.d.ts

@@ -0,0 +1,6 @@
+import type { GrantStore } from './store.js';
+export declare const OPERATORS_CREATOR_ID = "config:operators";
+export declare function reconcileOperators(store: GrantStore, params: {
+    dids: Array<string>;
+    pattern?: string;
+}): Promise<void>;

package/lib/grants/operators.js

@@ -0,0 +1,26 @@
+import { normalizeDID } from '@kokuin/token';
+import { GrantVersionConflictError } from './store.js';
+export const OPERATORS_CREATOR_ID = 'config:operators';
+export async function reconcileOperators(store, params) {
+    const entries = [
+        ...new Set(params.dids.map(normalizeDID))
+    ].map((subject)=>{
+        return {
+            subject,
+            pattern: params.pattern ?? 'admin/*'
+        };
+    });
+    for(let attempt = 0;; attempt++){
+        const expectedVersion = await store.getSetVersion(OPERATORS_CREATOR_ID);
+        try {
+            await store.replaceSet({
+                createdBy: OPERATORS_CREATOR_ID,
+                entries,
+                expectedVersion
+            });
+            return;
+        } catch (error) {
+            if (!(error instanceof GrantVersionConflictError) || attempt >= 4) throw error;
+        }
+    }
+}

package/lib/grants/plugin.d.ts

@@ -11,6 +11,7 @@ export type AccessGrants = {
 };
 export declare const ACCESS_GRANTS: import("@sozai/http-server").PluginName<"access:grants", AccessGrants>;
 export type AccessGrantsPluginParams = {
+    operators?: Array<string>;
     /** Maximum age of cached grants in milliseconds, a non-negative integer (0 disables caching). */
     cacheTTLMs?: number;
 };

package/lib/grants/plugin.js

@@ -1,6 +1,8 @@
+import { normalizeDID } from '@kokuin/token';
 import { pluginName } from '@sozai/http-server';
 import { HOZON_DB } from '@teikyo/hozon';
 import { GrantCache, isValidTTL } from './cache.js';
+import { reconcileOperators } from './operators.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 = {}) {
@@ -16,6 +18,9 @@ export const ACCESS_GRANTS = pluginName()('access:grants');
             const db = ctx.use(HOZON_DB);
             db.register(grantStoreDefinition);
             const store = await db.getStore(GRANT_STORE);
+            await reconcileOperators(store, {
+                dids: params.operators ?? []
+            });
             const cache = new GrantCache({
                 store,
                 ttlMs: params.cacheTTLMs
@@ -36,12 +41,13 @@ export const ACCESS_GRANTS = pluginName()('access:grants');
                         });
                     }
                 },
-                allow: ()=>async ({ payload, procedure, verifyDelegation })=>{
+                allow: ()=>{
+                    return async ({ payload, procedure, verifyDelegation })=>{
                         try {
-                            if (await cache.allows(payload.iss, procedure)) {
-                                return true;
+                            if (payload.sub == null || normalizeDID(payload.sub) === normalizeDID(payload.iss)) {
+                                return await cache.allows(payload.iss, procedure);
                             }
-                            if (payload.sub != null && await cache.allows(payload.sub, procedure)) {
+                            if (await cache.allows(payload.sub, procedure)) {
                                 return await verifyDelegation();
                             }
                             return false;
@@ -54,7 +60,8 @@ export const ACCESS_GRANTS = pluginName()('access:grants');
                                 cause
                             });
                         }
-                    }
+                    };
+                }
             };
         }
     };

package/lib/grants/store.d.ts

@@ -14,27 +14,49 @@ export type GrantParams = {
     expiresAt?: number;
 };
 export type RevokeParams = {
+    createdBy: string;
     subject: string;
     pattern?: string;
 };
+export type ReplaceGrantSetParams = {
+    createdBy: string;
+    entries: Array<{
+        subject: string;
+        pattern: string;
+        expiresAt?: number;
+    }>;
+    expectedVersion: number;
+    maxEntries?: number;
+};
+export type GrantVersionConflictErrorParams = {
+    currentVersion: number;
+};
+export declare class GrantVersionConflictError extends Error {
+    currentVersion: number;
+    constructor(params: GrantVersionConflictErrorParams);
+}
+export declare class GrantLimitError extends Error {
+    constructor();
+}
 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.
-     */
+    /** WARNING: use a top-level store for mutations, because nested transactions cannot commit independently. */
     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>;
+    replaceSet(params: ReplaceGrantSetParams): Promise<{
+        version: number;
+    }>;
+    getSetVersion(createdBy: string): Promise<number>;
+    /** Entries and version from one database snapshot, including expired grants. */
+    listSet(createdBy: string): Promise<{
+        entries: Array<Grant>;
+        version: number;
+    }>;
     list(params?: {
         subject?: string;
+        createdBy?: 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. */
+    /** Called after commit, once for each affected subject. */
     onChange(listener: (subject: string) => void): () => void;
 };
 export declare function createGrantStoreAPI(db: Kysely<GrantTables>): GrantStore;

package/lib/grants/store.js

@@ -1,7 +1,22 @@
+import { withStoreTransaction } from '@hozon/db';
 import { assertValidPattern } from '@kokuin/capability';
 import { normalizeDID } from '@kokuin/token';
 import { getLogger } from '@sozai/log';
 import { grantStoreMigrations } from './migrations.js';
+export class GrantVersionConflictError extends Error {
+    currentVersion;
+    constructor(params){
+        super('Grant set version conflict');
+        this.name = 'GrantVersionConflictError';
+        this.currentVersion = params.currentVersion;
+    }
+}
+export class GrantLimitError extends Error {
+    constructor(){
+        super('Grant set limit exceeded');
+        this.name = 'GrantLimitError';
+    }
+}
 function toGrant(row) {
     return {
         subject: row.subject,
@@ -37,49 +52,132 @@ export function createGrantStoreAPI(db) {
             }
         }
     }
+    async function lockVersion(tx, createdBy) {
+        await tx.insertInto('grant_sets').values({
+            created_by: createdBy,
+            version: 0
+        }).onConflict((conflict)=>conflict.column('created_by').doNothing()).execute();
+        // Reserve SQLite's writer and lock the Postgres row before reading the version.
+        const row = await tx.updateTable('grant_sets').set((eb)=>({
+                version: eb.ref('version')
+            })).where('created_by', '=', createdBy).returning('version').executeTakeFirstOrThrow();
+        return Number(row.version);
+    }
+    async function bumpVersion(tx, createdBy, version) {
+        await tx.updateTable('grant_sets').set({
+            version: version + 1
+        }).where('created_by', '=', createdBy).execute();
+    }
+    function grantRow(params) {
+        assertValidPattern(params.pattern);
+        if (params.expiresAt !== undefined && !Number.isSafeInteger(params.expiresAt)) {
+            throw new Error('Invalid grant expiry');
+        }
+        return {
+            subject: normalizeDID(params.subject),
+            pattern: params.pattern,
+            expires_at: params.expiresAt ?? null,
+            created_at: Date.now(),
+            created_by: normalizeDID(params.createdBy)
+        };
+    }
     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);
+            const row = grantRow(params);
+            await withStoreTransaction(db, async (tx)=>{
+                const version = await lockVersion(tx, row.created_by);
+                await tx.insertInto('grants').values(row).onConflict((conflict)=>{
+                    return conflict.columns([
+                        'created_by',
+                        'subject',
+                        'pattern'
+                    ]).doUpdateSet({
+                        expires_at: row.expires_at,
+                        created_at: row.created_at
+                    });
+                }).execute();
+                await bumpVersion(tx, row.created_by, version);
+            });
+            notify(row.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 createdBy = normalizeDID(params.createdBy);
+            const removed = await withStoreTransaction(db, async (tx)=>{
+                const version = await lockVersion(tx, createdBy);
+                let query = tx.deleteFrom('grants').where('subject', '=', subject).where('created_by', '=', createdBy);
+                if (params.pattern != null) query = query.where('pattern', '=', params.pattern);
+                const result = await query.executeTakeFirst();
+                await bumpVersion(tx, createdBy, version);
+                return Number(result.numDeletedRows);
+            });
+            if (removed > 0) notify(subject);
+            return removed;
+        },
+        async replaceSet (params) {
+            assertTopLevel();
+            const createdBy = normalizeDID(params.createdBy);
+            const result = await withStoreTransaction(db, async (tx)=>{
+                const version = await lockVersion(tx, createdBy);
+                if (version !== params.expectedVersion) throw new GrantVersionConflictError({
+                    currentVersion: version
+                });
+                if (params.maxEntries !== undefined && params.entries.length > params.maxEntries) throw new GrantLimitError();
+                const rows = params.entries.map((entry)=>grantRow({
+                        ...entry,
+                        createdBy
+                    }));
+                const previous = await tx.selectFrom('grants').select('subject').where('created_by', '=', createdBy).execute();
+                await tx.deleteFrom('grants').where('created_by', '=', createdBy).execute();
+                for (const row of rows)await tx.insertInto('grants').values(row).execute();
+                await bumpVersion(tx, createdBy, version);
+                return {
+                    version: version + 1,
+                    subjects: new Set([
+                        ...previous,
+                        ...rows
+                    ].map((row)=>row.subject))
+                };
+            });
+            for (const subject of result.subjects)notify(subject);
+            return {
+                version: result.version
+            };
+        },
+        async getSetVersion (createdBy) {
+            const row = await db.selectFrom('grant_sets').select('version').where('created_by', '=', normalizeDID(createdBy)).executeTakeFirst();
+            return row == null ? 0 : Number(row.version);
+        },
+        async listSet (createdBy) {
+            // One statement keeps entries and version consistent even under READ COMMITTED.
+            const rows = await db.selectFrom(db.selectNoFrom((eb)=>eb.val(normalizeDID(createdBy)).as('created_by')).as('creator')).leftJoin('grant_sets', 'grant_sets.created_by', 'creator.created_by').leftJoin('grants', 'grants.created_by', 'creator.created_by').selectAll('grants').select('grant_sets.version').orderBy('grants.created_at').orderBy('grants.pattern').execute();
+            const entries = [];
+            for (const row of rows){
+                if (row.subject !== null && row.pattern !== null && row.created_at !== null && row.created_by !== null) {
+                    entries.push(toGrant({
+                        subject: row.subject,
+                        pattern: row.pattern,
+                        expires_at: row.expires_at,
+                        created_at: row.created_at,
+                        created_by: row.created_by
+                    }));
+                }
             }
-            const result = await query.executeTakeFirst();
-            notify(subject);
-            return Number(result.numDeletedRows);
+            return {
+                entries,
+                version: Number(rows[0]?.version ?? 0)
+            };
         },
         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));
             }
+            if (params?.createdBy != null) {
+                query = query.where('created_by', '=', normalizeDID(params.createdBy));
+            }
             return (await query.execute()).map(toGrant);
         },
         async activeGrants (subject, now) {

package/lib/grants/tables.d.ts

@@ -1,4 +1,8 @@
 export type GrantTables = {
+    grant_sets: {
+        created_by: string;
+        version: number;
+    };
     grants: {
         subject: string;
         pattern: string;

package/lib/index.d.ts

@@ -1,8 +1,13 @@
+export { type AccessAdminHandlersParams, createAccessAdminHandlers } from './admin/handlers.js';
+export { type AccessAdminProtocol, accessAdminProtocol } from './admin/protocol.js';
 export { GrantCache, type GrantCacheParams } from './grants/cache.js';
+export { OPERATORS_CREATOR_ID, reconcileOperators } from './grants/operators.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 { GRANT_STORE, type Grant, GrantLimitError, type GrantParams, type GrantStore, GrantVersionConflictError, type GrantVersionConflictErrorParams, grantStoreDefinition, type ReplaceGrantSetParams, type RevokeParams, } from './grants/store.js';
 export type { GrantTables } from './grants/tables.js';
 export { patternMatches, patternsOverlap } from './patterns.js';
+export { ACCESS_REPLAY, type AccessReplay, type AccessReplayPluginParams, accessReplayPlugin, } from './replay/plugin.js';
+export { REPLAY_STORE, type ReplayStore, type ReplayTables, replayStoreDefinition, } from './replay/store.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

@@ -1,6 +1,11 @@
+export { createAccessAdminHandlers } from './admin/handlers.js';
+export { accessAdminProtocol } from './admin/protocol.js';
 export { GrantCache } from './grants/cache.js';
+export { OPERATORS_CREATOR_ID, reconcileOperators } from './grants/operators.js';
 export { ACCESS_GRANTS, accessGrantsPlugin } from './grants/plugin.js';
-export { GRANT_STORE, grantStoreDefinition } from './grants/store.js';
+export { GRANT_STORE, GrantLimitError, GrantVersionConflictError, grantStoreDefinition } from './grants/store.js';
 export { patternMatches, patternsOverlap } from './patterns.js';
+export { ACCESS_REPLAY, accessReplayPlugin } from './replay/plugin.js';
+export { REPLAY_STORE, replayStoreDefinition } from './replay/store.js';
 export { createRevocationHook, createRevocationStoreDefinition, REVOCATION_STORE } from './revocation/backend.js';
 export { ACCESS_REVOCATION, accessRevocationPlugin } from './revocation/plugin.js';

package/lib/replay/plugin.d.ts

@@ -0,0 +1,11 @@
+import type { ReplayCache } from '@enkaku/server';
+import type { HTTPPlugin } from '@sozai/http-server';
+import { HOZON_DB } from '@teikyo/hozon';
+export type AccessReplay = {
+    cache: ReplayCache;
+};
+export declare const ACCESS_REPLAY: import("@sozai/http-server").PluginName<"access:replay", AccessReplay>;
+export type AccessReplayPluginParams = {
+    cleanupIntervalMs?: number;
+};
+export declare function accessReplayPlugin(params?: AccessReplayPluginParams): HTTPPlugin<'access:replay', AccessReplay, [typeof HOZON_DB]>;

package/lib/replay/plugin.js

@@ -0,0 +1,28 @@
+import { pluginName } from '@sozai/http-server';
+import { HOZON_DB } from '@teikyo/hozon';
+import { REPLAY_STORE, replayStoreDefinition } from './store.js';
+export const ACCESS_REPLAY = pluginName()('access:replay');
+export function accessReplayPlugin(params = {}) {
+    return {
+        name: ACCESS_REPLAY,
+        dependsOn: [
+            HOZON_DB
+        ],
+        async setup (ctx) {
+            const db = ctx.use(HOZON_DB);
+            db.register(replayStoreDefinition);
+            const store = await db.getStore(REPLAY_STORE);
+            const timer = setInterval(()=>{
+                void store.cleanup().catch((error)=>{
+                    ctx.logger.error('replay cleanup failed', {
+                        error
+                    });
+                });
+            }, params.cleanupIntervalMs ?? 60_000);
+            ctx.onShutdown(()=>clearInterval(timer));
+            return {
+                cache: store
+            };
+        }
+    };
+}

package/lib/replay/store.d.ts

@@ -0,0 +1,14 @@
+import type { ReplayCache } from '@enkaku/server';
+import type { Kysely, StoreDefinition } from '@hozon/db';
+export type ReplayTables = {
+    replay_keys: {
+        key: string;
+        expires_at: number;
+    };
+};
+export type ReplayStore = ReplayCache & {
+    cleanup(): Promise<void>;
+};
+export declare const REPLAY_STORE = "teikyo-replay";
+export declare function createReplayStoreAPI(db: Kysely<ReplayTables>): ReplayStore;
+export declare const replayStoreDefinition: StoreDefinition<ReplayTables, ReplayStore>;

package/lib/replay/store.js

@@ -0,0 +1,36 @@
+import { withStoreTransaction } from '@hozon/db';
+export const REPLAY_STORE = 'teikyo-replay';
+export function createReplayStoreAPI(db) {
+    return {
+        async checkAndRecord (key, expiresAt) {
+            return await withStoreTransaction(db, async (tx)=>{
+                // Enkaku accepts tokens at expiry equality, so retain their replay records too.
+                await tx.deleteFrom('replay_keys').where('key', '=', key).where('expires_at', '<', Date.now()).execute();
+                const result = await tx.insertInto('replay_keys').values({
+                    key,
+                    expires_at: expiresAt
+                }).onConflict((conflict)=>conflict.column('key').doNothing()).executeTakeFirst();
+                return Number(result.numInsertedOrUpdatedRows) === 1;
+            });
+        },
+        async cleanup () {
+            await db.deleteFrom('replay_keys').where('expires_at', '<', Date.now()).execute();
+        }
+    };
+}
+export const replayStoreDefinition = {
+    name: REPLAY_STORE,
+    migrations: (ctx)=>{
+        return {
+            '0-init': {
+                async up (db) {
+                    await db.schema.createTable('replay_keys').addColumn('key', ctx.types.text, (column)=>column.notNull().primaryKey()).addColumn('expires_at', ctx.types.bigint, (column)=>column.notNull()).execute();
+                },
+                async down (db) {
+                    await db.schema.dropTable('replay_keys').execute();
+                }
+            }
+        };
+    },
+    createAPI: createReplayStoreAPI
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teikyo/access",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Access grants and revocation for Enkaku servers",
   "repository": {
     "type": "git",
@@ -19,7 +19,8 @@
     "lib/*"
   ],
   "dependencies": {
-    "@enkaku/server": "^0.23.0",
+    "@enkaku/protocol": "^0.23.1",
+    "@enkaku/server": "^0.23.1",
     "@hozon/db": "^0.5.1",
     "@kokuin/capability": "^0.7.0",
     "@kokuin/token": "^0.7.0",
@@ -30,7 +31,7 @@
   },
   "devDependencies": {
     "@hozon/provider": "^0.3.1",
-    "@kokuin/crypto": "^0.7.0",
+    "@kokuin/crypto": "^0.7.1",
     "@types/node": "^26.6.6",
     "del-cli": "^8.0.1",
     "vitest": "5.1.0"