@kubun/plugin-connector 0.10.0 → 0.11.0

package/lib/sync/processor.d.ts

@@ -1,20 +1,52 @@
-import type { EntityBatch } from '@kubun/connector';
+import type { EntityBatch, SyncFailureSample } from '@kubun/connector';
 import type { StoreProvider } from '@kubun/db';
-import type { ClustersRecord, DocumentFieldsMeta } from '@kubun/protocol';
+import type { ApplyVerifiedMutationResult, MutateDocumentsParams } from '@kubun/engine';
+import type { Logger } from '@kubun/logger';
+import type { ClustersRecord, DocumentData, DocumentFieldsMeta } from '@kubun/protocol';
+export declare const MAX_LOGGED_ERRORS = 10;
+/**
+ * Engine-signed document write helper. Signing with the engine identity while
+ * applying as `owner` (the account viewer) routes imports through the mutation
+ * log with field HLCs and `document:saved` events. Used by the sync path to
+ * build a {@link SignedDocumentWriter}.
+ */
+export type MutateDocuments = (params: MutateDocumentsParams) => Promise<Array<ApplyVerifiedMutationResult>>;
+/**
+ * Applies one imported document as a signed write owned by `owner`. Both the
+ * background sync path (via {@link MutateDocuments}) and the interactive action
+ * path (via the request's signed-set seam) supply this, so every import lands
+ * through the mutation pipeline — there is no direct graph-store write.
+ */
+export type SignedDocumentWriter = (params: {
+    owner: string;
+    modelID: string;
+    unique: Uint8Array;
+    data: DocumentData;
+}) => Promise<void>;
+export type ProcessBatchError = SyncFailureSample;
 export type ProcessBatchResult = {
     created: number;
     updated: number;
     deleted: number;
     failed: number;
     documentIDs: Array<string>;
+    errors: Array<ProcessBatchError>;
 };
 export type EntityProcessorParams = {
     stores: StoreProvider;
     modelID: string;
     ownerDID: string;
     connectorName: string;
+    logger: Logger;
     edgeFields?: DocumentFieldsMeta;
     clusters?: ClustersRecord;
+    /**
+     * Signs and applies each imported document as `ownerDID` through the mutation
+     * pipeline. The sync path backs this with the engine's own-DB write helper;
+     * the interactive action path backs it with the request's in-transaction
+     * signed-set seam.
+     */
+    writeDocument: SignedDocumentWriter;
 };
 export declare class EntityProcessor {
     #private;

package/lib/sync/processor.js

@@ -1 +1,191 @@
-import{DocumentID as e,DocumentModelID as t}from"@kubun/id";import{getGraphStore as r}from"@kubun/store-graph";export class EntityProcessor{#e;#t=null;#r;#o;#s;#n;#c;constructor(e){this.#e=e.stores,this.#r=t.fromString(e.modelID),this.#o=e.ownerDID,this.#s=e.connectorName,this.#n=e.edgeFields??{},this.#c=e.clusters}#i(t,r){let o=new TextEncoder().encode(`${t}:${r}`);return e.create(this.#r,this.#o,o)}#l(e){let r,o=this.#c;if(null==o)return;for(let t of Object.values(o))if(null!=t.record[e])return e;try{r=t.fromString(e)}catch{return}if(!r.isLocal)return;let s=r.index;for(let e of Object.values(o))for(let[t,r]of Object.entries(e.record))if(r===s)return t}#u(r){if(null==this.#c||0===Object.keys(this.#n).length)return r;let o={...r};for(let[s,n]of Object.entries(this.#n)){if("document"!==n.type||null==n.model)continue;let c=r[s];if(null==c||"object"!=typeof c)continue;let i=c.sourceService,l=c.sourceID;if("string"!=typeof i||"string"!=typeof l)continue;let u=this.#l(n.model);if(null==u)continue;let d=new TextEncoder().encode(`${i}:${l}`),a=e.create(t.fromString(u),this.#o,d);o[s]=a.toString()}return o}async processBatch(e){this.#t??=r(this.#e);let t=await this.#t,o=0,s=0,n=0,c=0,i=[];for(let r of e.entities)try{let e=this.#i(r.sourceService,r.sourceID),n=await t.getDocument(e),c={...r,lastSyncedAt:new Date().toISOString()},l=this.#u(c);if(null==n){let s=new TextEncoder().encode(`${r.sourceService}:${r.sourceID}`);await t.createDocument({id:e,owner:this.#o,unique:s,data:l}),o++}else await t.saveDocument({id:e,existing:n,data:l}),s++;i.push(e.toString())}catch{c++}if(e.deleted)for(let r of e.deleted)try{let e=this.#i(r.sourceService,r.sourceID),o=await t.getDocument(e);null!=o&&(await t.saveDocument({id:e,existing:o,data:{sourceService:r.sourceService,sourceID:r.sourceID,lastSyncedAt:new Date().toISOString(),_deleted:!0}}),n++)}catch{c++}return{created:o,updated:s,deleted:n,failed:c,documentIDs:i}}}
+import { DocumentID, DocumentModelID } from '@kubun/id';
+import { getGraphStore } from '@kubun/store-graph';
+export const MAX_LOGGED_ERRORS = 10;
+export class EntityProcessor {
+    #stores;
+    #graphStorePromise = null;
+    #modelID;
+    #ownerDID;
+    #connectorName;
+    #logger;
+    #edgeFields;
+    #clusters;
+    #writeDocument;
+    constructor(params){
+        this.#stores = params.stores;
+        this.#modelID = DocumentModelID.fromString(params.modelID);
+        this.#ownerDID = params.ownerDID;
+        this.#connectorName = params.connectorName;
+        this.#logger = params.logger;
+        this.#edgeFields = params.edgeFields ?? {};
+        this.#clusters = params.clusters;
+        this.#writeDocument = params.writeDocument;
+    }
+    #computeDocumentID(sourceService, sourceID) {
+        const unique = new TextEncoder().encode(`${sourceService}:${sourceID}`);
+        return DocumentID.create(this.#modelID, this.#ownerDID, unique);
+    }
+    #resolveTargetModelID(localOrGlobalModel) {
+        const clusters = this.#clusters;
+        if (clusters == null) return undefined;
+        // If it's already a global ID (exists in any cluster's record), use directly
+        for (const cluster of Object.values(clusters)){
+            if (cluster.record[localOrGlobalModel] != null) {
+                return localOrGlobalModel;
+            }
+        }
+        // Otherwise treat it as a local ID: parse the index, find matching global ID
+        let localModelID;
+        try {
+            localModelID = DocumentModelID.fromString(localOrGlobalModel);
+        } catch  {
+            return undefined;
+        }
+        if (!localModelID.isLocal) return undefined;
+        const targetIndex = localModelID.index;
+        for (const cluster of Object.values(clusters)){
+            for (const [globalID, index] of Object.entries(cluster.record)){
+                if (index === targetIndex) {
+                    return globalID;
+                }
+            }
+        }
+        return undefined;
+    }
+    #resolveEdgeReferences(data) {
+        const cluster = this.#clusters;
+        if (cluster == null || Object.keys(this.#edgeFields).length === 0) {
+            return data;
+        }
+        const resolved = {
+            ...data
+        };
+        for (const [field, meta] of Object.entries(this.#edgeFields)){
+            if (meta.type !== 'document' || meta.model == null) continue;
+            const value = data[field];
+            if (value == null || typeof value !== 'object') continue;
+            const ref = value;
+            const sourceService = ref.sourceService;
+            const sourceID = ref.sourceID;
+            if (typeof sourceService !== 'string' || typeof sourceID !== 'string') continue;
+            const targetModelID = this.#resolveTargetModelID(meta.model);
+            if (targetModelID == null) continue;
+            const unique = new TextEncoder().encode(`${sourceService}:${sourceID}`);
+            const docID = DocumentID.create(DocumentModelID.fromString(targetModelID), this.#ownerDID, unique);
+            resolved[field] = docID.toString();
+        }
+        return resolved;
+    }
+    async processBatch(batch) {
+        this.#graphStorePromise ??= getGraphStore(this.#stores);
+        const graphStore = await this.#graphStorePromise;
+        let created = 0;
+        let updated = 0;
+        let deleted = 0;
+        let failed = 0;
+        const documentIDs = [];
+        const errors = [];
+        let suppressed = 0;
+        for (const entity of batch.entities){
+            try {
+                const docID = this.#computeDocumentID(entity.sourceService, entity.sourceID);
+                const existing = await graphStore.getDocument(docID);
+                const rawData = {
+                    ...entity,
+                    lastSyncedAt: new Date().toISOString()
+                };
+                const data = this.#resolveEdgeReferences(rawData);
+                const unique = new TextEncoder().encode(`${entity.sourceService}:${entity.sourceID}`);
+                await this.#writeDocument({
+                    owner: this.#ownerDID,
+                    modelID: this.#modelID.toString(),
+                    unique,
+                    data
+                });
+                if (existing == null) {
+                    created++;
+                } else {
+                    updated++;
+                }
+                documentIDs.push(docID.toString());
+            } catch (err) {
+                failed++;
+                const message = err instanceof Error ? err.message : String(err);
+                if (errors.length < MAX_LOGGED_ERRORS) {
+                    errors.push({
+                        sourceService: entity.sourceService,
+                        sourceID: entity.sourceID,
+                        message
+                    });
+                    this.#logger.warn('connector sync entity failed', {
+                        connectorName: this.#connectorName,
+                        modelID: this.#modelID.toString(),
+                        sourceService: entity.sourceService,
+                        sourceID: entity.sourceID,
+                        error: message
+                    });
+                } else {
+                    suppressed++;
+                }
+            }
+        }
+        if (batch.deleted) {
+            for (const del of batch.deleted){
+                try {
+                    const docID = this.#computeDocumentID(del.sourceService, del.sourceID);
+                    const existing = await graphStore.getDocument(docID);
+                    if (existing != null) {
+                        const tombstone = {
+                            sourceService: del.sourceService,
+                            sourceID: del.sourceID,
+                            lastSyncedAt: new Date().toISOString(),
+                            _deleted: true
+                        };
+                        const unique = new TextEncoder().encode(`${del.sourceService}:${del.sourceID}`);
+                        await this.#writeDocument({
+                            owner: this.#ownerDID,
+                            modelID: this.#modelID.toString(),
+                            unique,
+                            data: tombstone
+                        });
+                        deleted++;
+                    }
+                } catch (err) {
+                    failed++;
+                    const message = err instanceof Error ? err.message : String(err);
+                    if (errors.length < MAX_LOGGED_ERRORS) {
+                        errors.push({
+                            sourceService: del.sourceService,
+                            sourceID: del.sourceID,
+                            message
+                        });
+                        this.#logger.warn('connector sync entity failed', {
+                            connectorName: this.#connectorName,
+                            modelID: this.#modelID.toString(),
+                            sourceService: del.sourceService,
+                            sourceID: del.sourceID,
+                            error: message
+                        });
+                    } else {
+                        suppressed++;
+                    }
+                }
+            }
+        }
+        if (suppressed > 0) {
+            this.#logger.warn('connector sync errors suppressed', {
+                connectorName: this.#connectorName,
+                modelID: this.#modelID.toString(),
+                suppressed
+            });
+        }
+        return {
+            created,
+            updated,
+            deleted,
+            failed,
+            documentIDs,
+            errors
+        };
+    }
+}

package/lib/sync/state.d.ts

@@ -12,6 +12,8 @@ export declare class DBSyncStateStore implements SyncStateStore {
     });
     get(connectorName: string, ownerDID: string): Promise<SyncState | null>;
     set(connectorName: string, ownerDID: string, state: SyncState): Promise<void>;
+    claimSync(connectorName: string, ownerDID: string, leaseMs: number): Promise<boolean>;
+    renewSync(connectorName: string, ownerDID: string, leaseMs: number): Promise<void>;
     delete(connectorName: string, ownerDID: string): Promise<void>;
     listForConnector(connectorName: string): Promise<Array<SyncStateEntry>>;
 }

package/lib/sync/state.js

@@ -1 +1,57 @@
-export class DBSyncStateStore{#t;constructor(t){this.#t=t.api}async get(t,n){let e=await this.#t.getSyncState(t,n);return null==e?null:{checkpoint:null!=e.checkpoint?"string"==typeof e.checkpoint?JSON.parse(e.checkpoint):e.checkpoint:null,lastSyncedAt:e.lastSyncedAt,entityCount:e.entityCount,status:e.status,error:e.error??void 0}}async set(t,n,e){await this.#t.setSyncState(t,n,{checkpoint:null!=e.checkpoint?JSON.stringify(e.checkpoint):null,lastSyncedAt:e.lastSyncedAt,entityCount:e.entityCount,status:e.status,error:e.error??null})}async delete(t,n){await this.#t.deleteSyncState(t,n)}async listForConnector(t){return(await this.#t.listSyncStates(t)).map(t=>({connectorName:t.connectorName,ownerDID:t.ownerDID,checkpoint:null!=t.checkpoint?"string"==typeof t.checkpoint?JSON.parse(t.checkpoint):t.checkpoint:null,lastSyncedAt:t.lastSyncedAt,entityCount:t.entityCount,status:t.status,error:t.error??void 0}))}}
+/**
+ * DB-backed SyncStateStore that wraps ConnectorAPI methods.
+ * Maps between the SyncState type (with unknown checkpoint) and the
+ * SyncStateData type (with JSON-serialized string checkpoint).
+ */ export class DBSyncStateStore {
+    #api;
+    constructor(params){
+        this.#api = params.api;
+    }
+    async get(connectorName, ownerDID) {
+        const data = await this.#api.getSyncState(connectorName, ownerDID);
+        if (data == null) {
+            return null;
+        }
+        return {
+            // ParseJSONResultsPlugin may have already parsed the checkpoint value
+            checkpoint: data.checkpoint != null ? typeof data.checkpoint === 'string' ? JSON.parse(data.checkpoint) : data.checkpoint : null,
+            lastSyncedAt: data.lastSyncedAt,
+            entityCount: data.entityCount,
+            status: data.status,
+            error: data.error ?? undefined,
+            leaseExpiresAt: data.leaseExpiresAt ?? undefined
+        };
+    }
+    async set(connectorName, ownerDID, state) {
+        await this.#api.setSyncState(connectorName, ownerDID, {
+            checkpoint: state.checkpoint != null ? JSON.stringify(state.checkpoint) : null,
+            lastSyncedAt: state.lastSyncedAt,
+            entityCount: state.entityCount,
+            status: state.status,
+            error: state.error ?? null
+        });
+    }
+    async claimSync(connectorName, ownerDID, leaseMs) {
+        return this.#api.claimSync(connectorName, ownerDID, leaseMs);
+    }
+    async renewSync(connectorName, ownerDID, leaseMs) {
+        await this.#api.renewSync(connectorName, ownerDID, leaseMs);
+    }
+    async delete(connectorName, ownerDID) {
+        await this.#api.deleteSyncState(connectorName, ownerDID);
+    }
+    async listForConnector(connectorName) {
+        const rows = await this.#api.listSyncStates(connectorName);
+        return rows.map((data)=>({
+                connectorName: data.connectorName,
+                ownerDID: data.ownerDID,
+                // ParseJSONResultsPlugin may have already parsed the checkpoint value
+                checkpoint: data.checkpoint != null ? typeof data.checkpoint === 'string' ? JSON.parse(data.checkpoint) : data.checkpoint : null,
+                lastSyncedAt: data.lastSyncedAt,
+                entityCount: data.entityCount,
+                status: data.status,
+                error: data.error ?? undefined,
+                leaseExpiresAt: data.leaseExpiresAt ?? undefined
+            }));
+    }
+}

package/lib/write-grants.d.ts

@@ -0,0 +1,35 @@
+import type { CredentialProvider } from '@kubun/connector';
+import { HLC } from '@kubun/hlc';
+import { getDelegationStore } from '@kubun/store-delegation';
+import type { ConnectorRegistry } from './registry.js';
+import type { ConnectorWriteGrant } from './schema.js';
+export type WriteGrantContextParams = {
+    registry: ConnectorRegistry;
+    /** The server identity a viewer delegates its write authority to (`aud`). */
+    serverDID: string;
+    /** The calling viewer (raw, unnormalized) — the grantor of every cap. */
+    viewerDID: string;
+    stores: Parameters<typeof getDelegationStore>[0];
+    credentialProvider: CredentialProvider;
+    hlc: HLC;
+};
+export type WriteGrantContext = {
+    grantWriteCapability(args: {
+        connector: string;
+        tokens: Array<string>;
+    }): Promise<boolean>;
+    revokeConnectorWriteCapability(args: {
+        connector: string;
+    }): Promise<boolean>;
+    disconnectProvider(args: {
+        provider: string;
+    }): Promise<boolean>;
+    connectorWriteGrants(): Promise<Array<ConnectorWriteGrant>>;
+};
+/**
+ * Build the viewer→server write-capability context methods (grant, per-connector
+ * revoke, per-provider disconnect, and the live-grant listing). Authorization of
+ * the writes these caps enable happens in the engine off the signed token; the
+ * stored `resource` string handled here is only the revoke/list selector.
+ */
+export declare function createWriteGrantContext(params: WriteGrantContextParams): WriteGrantContext;

package/lib/write-grants.js

@@ -0,0 +1,286 @@
+import { normalizeDID, verifyToken } from '@kokuin/token';
+import { clusterModelURNs } from '@kubun/connector';
+import { HLC } from '@kubun/hlc';
+import { getDelegationStore } from '@kubun/store-delegation';
+import { GraphQLError } from 'graphql';
+/**
+ * Upper bound on the lifetime of an accepted write-capability grant (1 year).
+ * A viewer's grant delegates its own write authority to the server; a grant
+ * whose expiry is further out than this is rejected as implausibly long-lived.
+ */ const MAX_GRANT_LIFETIME_SECONDS = 365 * 24 * 60 * 60;
+// The stored `res` claim comes back either as an already-parsed array of model
+// URNs (Kysely's ParseJSONResultsPlugin decodes JSON-array text on read) or as
+// a raw scalar string for a legacy `'*'`-style capability. Normalize both to a
+// set of resource strings so callers can compare res-sets uniformly.
+function parseResourceSet(raw) {
+    if (Array.isArray(raw) && raw.every((item)=>typeof item === 'string')) {
+        return new Set(raw);
+    }
+    if (typeof raw === 'string') {
+        try {
+            const value = JSON.parse(raw);
+            return Array.isArray(value) && value.every((item)=>typeof item === 'string') ? new Set(value) : new Set([
+                raw
+            ]);
+        } catch (_error) {
+            return new Set([
+                raw
+            ]);
+        }
+    }
+    return new Set([
+        String(raw)
+    ]);
+}
+function setsEqual(a, b) {
+    return a.size === b.size && [
+        ...a
+    ].every((item)=>b.has(item));
+}
+// Hard-delete every held token whose res-set exactly equals ANY of
+// `targetSets`, leaving broader/`*`/unrelated caps intact. Reads the held
+// tokens once; returns the number of rows removed. Shared by the
+// per-connector revoke and the per-provider disconnect flows.
+async function revokeCapsMatchingSets(delegationStore, grantor, audience, targetSets) {
+    const held = await delegationStore.getDelegationTokens({
+        grantor,
+        audience
+    });
+    let removed = 0;
+    for (const row of held){
+        const parsed = parseResourceSet(row.resource);
+        if (targetSets.some((target)=>setsEqual(parsed, target))) {
+            if (await delegationStore.removeDelegationToken({
+                jti: row.jti
+            })) {
+                removed += 1;
+            }
+        }
+    }
+    return removed;
+}
+// Hard-delete every held token whose non-empty res-set is a SUBSET of
+// `allowed`. Used by provider disconnect so a cap scoped to any subset of the
+// provider's connector models (including after a model-set change) is dropped,
+// while caps covering models outside the provider stay intact.
+async function revokeCapsSubsetOf(delegationStore, grantor, audience, allowed) {
+    const held = await delegationStore.getDelegationTokens({
+        grantor,
+        audience
+    });
+    let removed = 0;
+    for (const row of held){
+        const parsed = parseResourceSet(row.resource);
+        if (parsed.size > 0 && [
+            ...parsed
+        ].every((urn)=>allowed.has(urn))) {
+            if (await delegationStore.removeDelegationToken({
+                jti: row.jti
+            })) removed += 1;
+        }
+    }
+    return removed;
+}
+/**
+ * Build the viewer→server write-capability context methods (grant, per-connector
+ * revoke, per-provider disconnect, and the live-grant listing). Authorization of
+ * the writes these caps enable happens in the engine off the signed token; the
+ * stored `resource` string handled here is only the revoke/list selector.
+ */ export function createWriteGrantContext(params) {
+    const { registry, serverDID, credentialProvider, stores, hlc } = params;
+    return {
+        grantWriteCapability: async ({ connector, tokens })=>{
+            const connectorDef = registry.get(connector);
+            if (connectorDef == null) {
+                throw new GraphQLError(`Connector "${connector}" not found`, {
+                    extensions: {
+                        code: 'CONNECTOR_NOT_FOUND'
+                    }
+                });
+            }
+            // A grant may scope its write authority to no broader than this
+            // connector's own models. Bounding `res` server-side means a
+            // viewer's least-privilege intent is enforced here, not only
+            // trusted from the client that minted the token.
+            const allowedURNs = new Set(clusterModelURNs(connectorDef.clusters));
+            const viewerDID = normalizeDID(params.viewerDID);
+            const audienceDID = normalizeDID(serverDID);
+            const now = Math.floor(Date.now() / 1000);
+            // Validate every token first — a single invalid token rejects the
+            // whole batch, so nothing is stored unless all tokens pass. The
+            // per-token writes below run inside the mutation transaction, so a
+            // later failure would also roll the batch back.
+            const accepted = [];
+            for (const token of tokens){
+                let payload;
+                try {
+                    const verified = await verifyToken(token);
+                    payload = verified.payload;
+                } catch (_error) {
+                    throw new GraphQLError('write-capability grant failed signature verification', {
+                        extensions: {
+                            code: 'CONNECTOR_WRITE_GRANT_INVALID'
+                        }
+                    });
+                }
+                // The grant must be self-signed by the viewer delegating its own
+                // authority: issuer and subject are both the calling viewer.
+                if (normalizeDID(payload.iss) !== viewerDID || normalizeDID(payload.sub) !== viewerDID) {
+                    throw new GraphQLError('write-capability grant must be self-signed by the viewer', {
+                        extensions: {
+                            code: 'CONNECTOR_WRITE_GRANT_INVALID'
+                        }
+                    });
+                }
+                // The grant must delegate to this server so the engine's
+                // auto-attach picks it up on later server-signed writes.
+                if (normalizeDID(payload.aud) !== audienceDID) {
+                    throw new GraphQLError('write-capability grant is not addressed to this server', {
+                        extensions: {
+                            code: 'CONNECTOR_WRITE_GRANT_INVALID'
+                        }
+                    });
+                }
+                if (payload.act !== 'document/write') {
+                    throw new GraphQLError('write-capability grant does not grant document/write', {
+                        extensions: {
+                            code: 'CONNECTOR_WRITE_GRANT_INVALID'
+                        }
+                    });
+                }
+                if (typeof payload.exp !== 'number' || payload.exp <= now || payload.exp > now + MAX_GRANT_LIFETIME_SECONDS) {
+                    throw new GraphQLError('write-capability grant has an invalid expiry', {
+                        extensions: {
+                            code: 'CONNECTOR_WRITE_GRANT_INVALID'
+                        }
+                    });
+                }
+                if (payload.jti == null) {
+                    throw new GraphQLError('write-capability grant is missing a token id', {
+                        extensions: {
+                            code: 'CONNECTOR_WRITE_GRANT_INVALID'
+                        }
+                    });
+                }
+                // The grant's resource set must be a non-empty subset of this
+                // connector's models — an empty scope, a `'*'` wildcard, or any
+                // out-of-scope URN exceeds what the viewer may delegate here.
+                const resSet = parseResourceSet(payload.res);
+                if (!(resSet.size > 0 && [
+                    ...resSet
+                ].every((urn)=>allowedURNs.has(urn)))) {
+                    throw new GraphQLError('write-capability grant resource exceeds connector scope', {
+                        extensions: {
+                            code: 'CONNECTOR_WRITE_GRANT_INVALID'
+                        }
+                    });
+                }
+                const resource = typeof payload.res === 'string' ? payload.res : JSON.stringify(payload.res);
+                accepted.push({
+                    jti: payload.jti,
+                    token,
+                    resource,
+                    exp: payload.exp
+                });
+            }
+            const delegationStore = await getDelegationStore(stores);
+            const hlcNow = HLC.serialize(hlc.now());
+            for (const entry of accepted){
+                await delegationStore.addDelegationToken({
+                    jti: entry.jti,
+                    grantor: viewerDID,
+                    audience: audienceDID,
+                    token: entry.token,
+                    resource: entry.resource,
+                    act: 'document/write',
+                    exp: entry.exp,
+                    hlc: hlcNow
+                });
+            }
+            return true;
+        },
+        revokeConnectorWriteCapability: async ({ connector })=>{
+            const connectorDef = registry.get(connector);
+            if (connectorDef == null) {
+                throw new GraphQLError(`Connector "${connector}" not found`, {
+                    extensions: {
+                        code: 'CONNECTOR_NOT_FOUND'
+                    }
+                });
+            }
+            // Only a held cap scoped to precisely this connector's model set
+            // is dropped — broader caps (`*`) and other-connector caps stay
+            // intact.
+            const target = new Set(clusterModelURNs(connectorDef.clusters));
+            const viewerDID = normalizeDID(params.viewerDID);
+            const audienceDID = normalizeDID(serverDID);
+            const delegationStore = await getDelegationStore(stores);
+            const removed = await revokeCapsMatchingSets(delegationStore, viewerDID, audienceDID, [
+                target
+            ]);
+            return removed > 0;
+        },
+        disconnectProvider: async ({ provider })=>{
+            // Disconnecting a provider revokes every connector cap the viewer
+            // delegated for connectors backed by it, then drops the shared
+            // OAuth credential. A provider with zero registered connectors
+            // still runs the credential cleanup — no unknown-provider throw.
+            const viewerDID = normalizeDID(params.viewerDID);
+            const audienceDID = normalizeDID(serverDID);
+            const connectors = registry.getAll().filter((connector)=>connector.auth.provider === provider);
+            // Union of every model backed by this provider. Any held cap whose
+            // scope falls within that union is dropped — this covers a cap that
+            // no longer matches a connector's current model set exactly (drift),
+            // which an exact-set revoke would miss. Zero connectors → empty
+            // union → nothing revoked, leaving only the credential cleanup.
+            const providerURNs = new Set();
+            for (const connector of connectors){
+                for (const urn of clusterModelURNs(connector.clusters))providerURNs.add(urn);
+            }
+            const delegationStore = await getDelegationStore(stores);
+            const removed = await revokeCapsSubsetOf(delegationStore, viewerDID, audienceDID, providerURNs);
+            const credentialExisted = await credentialProvider.get(provider, viewerDID) != null;
+            await credentialProvider.delete(provider, viewerDID);
+            return removed > 0 || credentialExisted;
+        },
+        connectorWriteGrants: async ()=>{
+            const viewerDID = normalizeDID(params.viewerDID);
+            const audienceDID = normalizeDID(serverDID);
+            const now = Math.floor(Date.now() / 1000);
+            const delegationStore = await getDelegationStore(stores);
+            const held = await delegationStore.getDelegationTokens({
+                grantor: viewerDID,
+                audience: audienceDID
+            });
+            const revoked = new Set((await delegationStore.getHeldRevocations({
+                audience: audienceDID
+            })).map((row)=>row.jti));
+            const connectors = registry.getAll().map((connector)=>({
+                    name: connector.name,
+                    provider: connector.auth.provider,
+                    set: new Set(clusterModelURNs(connector.clusters))
+                }));
+            const grants = [];
+            for (const row of held){
+                // Skip expired and already-revoked caps; only surface live,
+                // per-connector grants. A `*` or otherwise broader cap matches
+                // no connector set and is intentionally not listed.
+                if (row.exp <= now) continue;
+                if (revoked.has(row.jti)) continue;
+                const parsed = parseResourceSet(row.resource);
+                const match = connectors.find((connector)=>setsEqual(parsed, connector.set));
+                if (match == null) continue;
+                grants.push({
+                    connector: match.name,
+                    provider: match.provider,
+                    modelURNs: [
+                        ...match.set
+                    ],
+                    exp: row.exp,
+                    jti: row.jti
+                });
+            }
+            return grants;
+        }
+    };
+}