@kubun/plugin-connector 0.9.0 → 0.11.0

package/lib/index.js

@@ -1 +1,223 @@
-import{fromEmitter as e}from"@enkaku/generator";import{connectorStoreDefinition as t}from"@kubun/store-connector";import{executeAction as r}from"./action.js";import{createConnectorAPI as n}from"./api.js";import{DBCredentialProvider as o}from"./credential.js";import{ConnectorManager as c}from"./manager.js";import{OAuthService as s}from"./oauth.js";import{ConnectorRegistry as i}from"./registry.js";import{createConnectorSchemaExtension as a,toConnectorSyncEventResult as u}from"./schema.js";import{orchestrateSync as l}from"./sync/orchestrate.js";import{DBSyncStateStore as m}from"./sync/state.js";export{executeAction}from"./action.js";export{ConnectorManager}from"./manager.js";export{OAuthService}from"./oauth.js";export{ConnectorRegistry}from"./registry.js";export{createConnectorSchemaExtension,toConnectorSyncEventResult}from"./schema.js";export{SyncEngine}from"./sync/engine.js";export{orchestrateSync}from"./sync/orchestrate.js";export{EntityProcessor}from"./sync/processor.js";export{DBSyncStateStore}from"./sync/state.js";async function p(e,t,r,n,o){let c=t.get(o);if(null==c)throw Error(`Connector "${o}" not found`);let s=await e.getSyncState(o,n),i=!1,a=!1,u=null;if("device"!==c.auth.provider){let e=await r.get(c.auth.provider,n);if(null!=e){i=!0,null!=e.expiresAt&&(u=e.expiresAt.toISOString());let t=c.auth;a=null==t.writeScopes||t.writeScopes.every(t=>e.scopes.includes(t))}}return null==s?{name:o,status:"IDLE",authenticated:i,hasWriteAccess:a,authExpiresAt:u,lastSyncedAt:null,entityCount:null,error:null}:{name:o,status:"idle"===s.status?"IDLE":"syncing"===s.status?"SYNCING":"ERROR",authenticated:i,hasWriteAccess:a,authExpiresAt:u,lastSyncedAt:s.lastSyncedAt??null,entityCount:s.entityCount??null,error:s.error??null}}export function createConnectorPlugin(y){let f=y.providers??[];return d=>{d.db.register(t);let g=new i;for(let e of y.connectors)g.register(e);let S=n({stores:d.db}),D=new o({api:S,runtime:d.runtime,providers:f}),h=new m({api:S}),w=new c({registry:g,logger:d.getLogger("connector"),defaults:y.defaults}),j=new s({runtime:d.runtime,providers:f,registry:g,credentialProvider:D});return{name:"connector",schemaExtension:e=>a({registry:g,config:e}),api:S,createContextFactory:()=>(t,c)=>{let s=n({stores:c}),i=new o({api:s,runtime:d.runtime,providers:f});return{getState:e=>p(s,g,i,t.viewerDID,e),getStates:()=>Promise.all(g.list().map(e=>p(s,g,i,t.viewerDID,e))),startAuth:e=>j.startAuth(e),completeAuth:e=>j.completeAuth(e,t.viewerDID,i),triggerSync:async e=>g.has(e.connector)?(c.onCommit(()=>{l({connectorName:e.connector,full:e.full??!1,registry:g,syncEventEmitter:w,stateStore:h,credentialProvider:D,ownerDID:t.viewerDID,stores:d.db,boundary:y.defaults?.boundary}).catch(()=>{})}),{status:"STARTED",connectorName:e.connector}):{status:"ERROR",connectorName:e.connector},subscribeToSyncEvents:t=>{let r=null!=t?e=>e.connectorName===t:void 0,n=e(w.syncEvents,"sync",{filter:r});return async function*(){for await(let e of n)yield u(e)}()},executeAction:async e=>{try{let n=await r({connector:e.connector,action:e.action,model:e.model,input:e.input,sourceID:e.sourceID},{stores:c,registry:g,credentialProvider:i,ownerDID:t.viewerDID});return{documentID:n.documentID,entity:n.entity,error:null}}catch(t){let e=t.code??"API_ERROR";return{documentID:null,entity:null,error:{code:e,message:t instanceof Error?t.message:String(t),requiredScopes:t.requiredScopes}}}}}}}}}export{o as DBCredentialProvider};
+import { connectorStoreDefinition } from '@kubun/store-connector';
+import { executeAction } from './action.js';
+import { createConnectorAPI } from './api.js';
+import { DBCredentialProvider } from './credential.js';
+import { ConnectorManager } from './manager.js';
+import { OAuthService } from './oauth.js';
+import { ConnectorRegistry } from './registry.js';
+import { createConnectorSchemaExtension, subscribeToConnectorSyncEvents } from './schema.js';
+import { orchestrateSync } from './sync/orchestrate.js';
+import { DBSyncStateStore } from './sync/state.js';
+import { createWriteGrantContext } from './write-grants.js';
+// ---- Re-exports ----
+export { executeAction } from './action.js';
+export { ConnectorManager } from './manager.js';
+export { OAuthService } from './oauth.js';
+export { ConnectorRegistry } from './registry.js';
+export { createConnectorSchemaExtension, toConnectorSyncEventResult } from './schema.js';
+export { SyncEngine } from './sync/engine.js';
+export { orchestrateSync } from './sync/orchestrate.js';
+export { EntityProcessor } from './sync/processor.js';
+export { DBSyncStateStore } from './sync/state.js';
+export { DBCredentialProvider };
+// ---- Plugin factory options ----
+/** Default sync-lease TTL (5 minutes) — an in-flight sync heartbeats this before expiry. */ const DEFAULT_LEASE_TTL_MS = 300_000;
+// ---- Connector state resolution ----
+async function resolveConnectorState(connectorAPI, registry, credentialProvider, viewerDID, connectorName) {
+    const connector = registry.get(connectorName);
+    if (connector == null) {
+        throw new Error(`Connector "${connectorName}" not found`);
+    }
+    const syncState = await connectorAPI.getSyncState(connectorName, viewerDID);
+    let authenticated = false;
+    let hasWriteAccess = false;
+    let authExpiresAt = null;
+    if (connector.auth.provider !== 'device') {
+        const credential = await credentialProvider.get(connector.auth.provider, viewerDID);
+        if (credential != null) {
+            authenticated = true;
+            if (credential.expiresAt != null) {
+                authExpiresAt = credential.expiresAt.toISOString();
+            }
+            const auth = connector.auth;
+            if (auth.writeScopes == null) {
+                hasWriteAccess = true;
+            } else {
+                hasWriteAccess = auth.writeScopes.every((scope)=>credential.scopes.includes(scope));
+            }
+        }
+    }
+    if (syncState == null) {
+        return {
+            name: connectorName,
+            status: 'IDLE',
+            authenticated,
+            hasWriteAccess,
+            authExpiresAt,
+            lastSyncedAt: null,
+            entityCount: null,
+            error: null
+        };
+    }
+    return {
+        name: connectorName,
+        status: syncState.status === 'idle' ? 'IDLE' : syncState.status === 'syncing' ? 'SYNCING' : 'ERROR',
+        authenticated,
+        hasWriteAccess,
+        authExpiresAt,
+        lastSyncedAt: syncState.lastSyncedAt ?? null,
+        entityCount: syncState.entityCount ?? null,
+        error: syncState.error ?? null
+    };
+}
+// ---- Plugin factory ----
+export function createConnectorPlugin(options) {
+    const providers = options.providers ?? [];
+    const leaseMs = options.syncLeaseTTL ?? DEFAULT_LEASE_TTL_MS;
+    return (params)=>{
+        params.db.register(connectorStoreDefinition);
+        const logger = params.getLogger('connector');
+        // On a multi-tenant server the connector signs writes with the server
+        // identity, but imported documents must be owned by the account viewer. A
+        // viewer delegates its own write authority to this server DID, so accepted
+        // grants must be addressed to it (`aud`).
+        const serverDID = params.identity.id;
+        const registry = new ConnectorRegistry();
+        for (const connector of options.connectors){
+            registry.register(connector);
+        }
+        const connectorAPI = createConnectorAPI({
+            stores: params.db,
+            cipher: params.cipher
+        });
+        const credentialProvider = new DBCredentialProvider({
+            api: connectorAPI,
+            runtime: params.runtime,
+            providers
+        });
+        const stateStore = new DBSyncStateStore({
+            api: connectorAPI
+        });
+        const manager = new ConnectorManager({
+            registry,
+            logger,
+            defaults: options.defaults
+        });
+        const oauthService = new OAuthService({
+            runtime: params.runtime,
+            providers,
+            registry,
+            credentialProvider,
+            connectorAPI
+        });
+        return {
+            name: 'connector',
+            schemaExtension: (config)=>createConnectorSchemaExtension({
+                    registry,
+                    config: config
+                }),
+            api: connectorAPI,
+            createContextFactory: ()=>{
+                return (ctx, stores)=>{
+                    // Per-request connector API and credential provider backed by the
+                    // request's StoreProvider (transactional during mutations).
+                    const requestAPI = createConnectorAPI({
+                        stores,
+                        cipher: params.cipher
+                    });
+                    const requestCredentialProvider = new DBCredentialProvider({
+                        api: requestAPI,
+                        runtime: params.runtime,
+                        providers
+                    });
+                    return {
+                        getState: (name)=>resolveConnectorState(requestAPI, registry, requestCredentialProvider, ctx.viewerDID, name),
+                        getStates: ()=>{
+                            const names = registry.list();
+                            return Promise.all(names.map((name)=>resolveConnectorState(requestAPI, registry, requestCredentialProvider, ctx.viewerDID, name)));
+                        },
+                        startAuth: (args)=>oauthService.startAuth(args, ctx.viewerDID, requestAPI),
+                        completeAuth: (args)=>oauthService.completeAuth(args, requestCredentialProvider, requestAPI),
+                        triggerSync: async (args)=>{
+                            if (!registry.has(args.connector)) {
+                                return {
+                                    status: 'ERROR',
+                                    connectorName: args.connector
+                                };
+                            }
+                            // Defer sync to after transaction commits — orchestrateSync starts
+                            // fire-and-forget background work that uses KubunDB.getStore() directly,
+                            // which would deadlock if the mutation transaction still holds the connection.
+                            stores.onCommit(()=>{
+                                orchestrateSync({
+                                    connectorName: args.connector,
+                                    full: args.full ?? false,
+                                    registry,
+                                    syncEventEmitter: manager,
+                                    stateStore,
+                                    credentialProvider,
+                                    ownerDID: ctx.viewerDID,
+                                    stores: params.db,
+                                    boundary: options.defaults?.boundary,
+                                    leaseMs,
+                                    logger,
+                                    mutateDocuments: params.graph.mutateDocuments
+                                }).catch(()=>{});
+                            });
+                            return {
+                                status: 'STARTED',
+                                connectorName: args.connector
+                            };
+                        },
+                        subscribeToSyncEvents: (connector)=>subscribeToConnectorSyncEvents(manager.syncEvents, connector),
+                        executeAction: async (args, writeDocument)=>{
+                            try {
+                                const result = await executeAction({
+                                    connector: args.connector,
+                                    action: args.action,
+                                    model: args.model,
+                                    input: args.input,
+                                    sourceID: args.sourceID
+                                }, {
+                                    stores,
+                                    registry,
+                                    credentialProvider: requestCredentialProvider,
+                                    ownerDID: ctx.viewerDID,
+                                    logger,
+                                    writeDocument
+                                });
+                                return {
+                                    documentID: result.documentID,
+                                    entity: result.entity,
+                                    error: null
+                                };
+                            } catch (err) {
+                                const errorObj = err;
+                                const code = errorObj.code ?? 'API_ERROR';
+                                const message = err instanceof Error ? err.message : String(err);
+                                const requiredScopes = errorObj.requiredScopes;
+                                return {
+                                    documentID: null,
+                                    entity: null,
+                                    error: {
+                                        code,
+                                        message,
+                                        requiredScopes
+                                    }
+                                };
+                            }
+                        },
+                        ...createWriteGrantContext({
+                            registry,
+                            serverDID,
+                            viewerDID: ctx.viewerDID,
+                            stores,
+                            credentialProvider: requestCredentialProvider,
+                            hlc: params.hlc
+                        })
+                    };
+                };
+            }
+        };
+    };
+}

package/lib/manager.d.ts

@@ -1,6 +1,6 @@
-import { EventEmitter } from '@enkaku/event';
 import type { ConnectorSyncEventPayload, SyncBoundary } from '@kubun/connector';
 import type { Logger } from '@kubun/logger';
+import { EventEmitter } from '@sozai/event';
 import type { ConnectorRegistry } from './registry.js';
 type SyncEvents = {
     sync: ConnectorSyncEventPayload;

package/lib/manager.js

@@ -1 +1,90 @@
-import{EventEmitter as t}from"@enkaku/event";export class ConnectorManager{#t;#e;#n=new Map;#r=new t;#s=new t;#i;constructor(t){this.#t=t.registry,this.#e=t.logger,this.#i={boundary:t.defaults?.boundary??{maxAge:"P90D"},pollingInterval:t.defaults?.pollingInterval??"PT5M"}}get defaults(){return this.#i}activateForGraph(t,e){for(let n of e){if(!this.#t.has(n))throw Error(`Connector "${n}" is not registered`);let e=this.#n.get(n),r=null==e||0===e.size;null==e&&(e=new Set,this.#n.set(n,e)),e.add(t),r&&(this.#e.info("Connector {name} activated by graph {graphID}",{name:n,graphID:t}),this.#r.emit("connector:activated",{connectorName:n,graphID:t}))}}deactivateForGraph(t,e){for(let n of e){let e=this.#n.get(n);null!=e&&(e.delete(t),0===e.size&&(this.#n.delete(n),this.#e.info("Connector {name} deactivated",{name:n}),this.#r.emit("connector:deactivated",{connectorName:n})))}}isActive(t){let e=this.#n.get(t);return null!=e&&e.size>0}getActiveGraphs(t){let e=this.#n.get(t);return e?Array.from(e):[]}listActive(){return Array.from(this.#n.keys()).filter(t=>this.isActive(t))}onConnectorActivated(t){return this.#r.on("connector:activated",t)}onConnectorDeactivated(t){return this.#r.on("connector:deactivated",t)}get syncEvents(){return this.#s}async emitSyncEvent(t){await this.#s.emit("sync",t)}onSyncEvent(t){return this.#s.on("sync",t)}}
+import { EventEmitter } from '@sozai/event';
+export class ConnectorManager {
+    #registry;
+    #logger;
+    #activeGraphs = new Map();
+    #events = new EventEmitter();
+    #syncEvents = new EventEmitter();
+    #defaults;
+    constructor(params){
+        this.#registry = params.registry;
+        this.#logger = params.logger;
+        this.#defaults = {
+            boundary: params.defaults?.boundary ?? {
+                maxAge: 'P90D'
+            },
+            pollingInterval: params.defaults?.pollingInterval ?? 'PT5M'
+        };
+    }
+    get defaults() {
+        return this.#defaults;
+    }
+    activateForGraph(graphID, connectorNames) {
+        for (const name of connectorNames){
+            if (!this.#registry.has(name)) {
+                throw new Error(`Connector "${name}" is not registered`);
+            }
+            let graphSet = this.#activeGraphs.get(name);
+            const wasInactive = graphSet == null || graphSet.size === 0;
+            if (graphSet == null) {
+                graphSet = new Set();
+                this.#activeGraphs.set(name, graphSet);
+            }
+            graphSet.add(graphID);
+            if (wasInactive) {
+                this.#logger.info('Connector {name} activated by graph {graphID}', {
+                    name,
+                    graphID
+                });
+                this.#events.emit('connector:activated', {
+                    connectorName: name,
+                    graphID
+                });
+            }
+        }
+    }
+    deactivateForGraph(graphID, connectorNames) {
+        for (const name of connectorNames){
+            const graphSet = this.#activeGraphs.get(name);
+            if (graphSet == null) {
+                continue;
+            }
+            graphSet.delete(graphID);
+            if (graphSet.size === 0) {
+                this.#activeGraphs.delete(name);
+                this.#logger.info('Connector {name} deactivated', {
+                    name
+                });
+                this.#events.emit('connector:deactivated', {
+                    connectorName: name
+                });
+            }
+        }
+    }
+    isActive(connectorName) {
+        const graphSet = this.#activeGraphs.get(connectorName);
+        return graphSet != null && graphSet.size > 0;
+    }
+    getActiveGraphs(connectorName) {
+        const graphSet = this.#activeGraphs.get(connectorName);
+        return graphSet ? Array.from(graphSet) : [];
+    }
+    listActive() {
+        return Array.from(this.#activeGraphs.keys()).filter((name)=>this.isActive(name));
+    }
+    onConnectorActivated(callback) {
+        return this.#events.on('connector:activated', callback);
+    }
+    onConnectorDeactivated(callback) {
+        return this.#events.on('connector:deactivated', callback);
+    }
+    get syncEvents() {
+        return this.#syncEvents;
+    }
+    async emitSyncEvent(event) {
+        await this.#syncEvents.emit('sync', event);
+    }
+    onSyncEvent(callback) {
+        return this.#syncEvents.on('sync', callback);
+    }
+}

package/lib/oauth.d.ts

@@ -1,5 +1,6 @@
-import type { Runtime } from '@enkaku/runtime';
 import type { CredentialProvider, OAuthProviderDefinition } from '@kubun/connector';
+import type { Runtime } from '@sozai/runtime';
+import type { ConnectorAPI } from './api.js';
 import type { ConnectorRegistry } from './registry.js';
 import type { CompleteConnectorAuthInput, CompleteConnectorAuthOutput, StartConnectorAuthInput, StartConnectorAuthOutput } from './schema.js';
 export type OAuthServiceParams = {
@@ -7,10 +8,11 @@ export type OAuthServiceParams = {
     providers: Array<OAuthProviderDefinition>;
     registry: ConnectorRegistry;
     credentialProvider: CredentialProvider;
+    connectorAPI: ConnectorAPI;
 };
 export declare class OAuthService {
     #private;
     constructor(params: OAuthServiceParams);
-    startAuth(args: StartConnectorAuthInput): Promise<StartConnectorAuthOutput>;
-    completeAuth(args: CompleteConnectorAuthInput, viewerDID: string, credentialProvider?: CredentialProvider): Promise<CompleteConnectorAuthOutput>;
+    startAuth(args: StartConnectorAuthInput, ownerDID: string, connectorAPI?: ConnectorAPI): Promise<StartConnectorAuthOutput>;
+    completeAuth(args: CompleteConnectorAuthInput, credentialProvider?: CredentialProvider, connectorAPI?: ConnectorAPI): Promise<CompleteConnectorAuthOutput>;
 }

package/lib/oauth.js

@@ -1 +1,137 @@
-export class OAuthService{#e;#r;#t;#i;constructor(e){this.#e=e.credentialProvider,this.#r=e.runtime,this.#t=e.providers,this.#i=e.registry}async startAuth(e){let r=this.#t.find(r=>r.name===e.provider);if(null==r)throw Error(`OAuth provider "${e.provider}" not found`);if(null==r.clientID)throw Error(`OAuth provider "${e.provider}" is missing clientID`);let t=!0===e.requestWriteAccess,i=new Set(r.baseScopes??[]);for(let r of e.connectors??this.#i.list()){let o=this.#i.get(r);if(null!=o&&o.auth.provider===e.provider){let e=o.auth;if(t&&null!=e.writeScopes)for(let r of e.writeScopes)i.add(r);else for(let r of e.scopes)i.add(r)}}let o=JSON.stringify({nonce:this.#r.getRandomID(),provider:e.provider}),s=new URL(r.authorizationEndpoint);return s.searchParams.set("client_id",r.clientID),s.searchParams.set("redirect_uri",e.redirectURL),s.searchParams.set("response_type","code"),s.searchParams.set("scope",Array.from(i).join(" ")),s.searchParams.set("state",o),s.searchParams.set("access_type","offline"),s.searchParams.set("prompt","consent"),{url:s.toString(),state:o}}async completeAuth(e,r,t){let i=this.#t.find(r=>r.name===e.provider);if(null==i)throw Error(`OAuth provider "${e.provider}" not found`);if(null==i.clientID||null==i.clientSecret)throw Error(`OAuth provider "${e.provider}" is missing clientID or clientSecret`);let o=await this.#r.fetch(i.tokenEndpoint,{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded"},body:new URLSearchParams({grant_type:"authorization_code",code:e.code,redirect_uri:e.redirectURL,client_id:i.clientID,client_secret:i.clientSecret})});if(!o.ok)throw Error(`Token exchange failed: ${o.statusText}`);let s=await o.json(),n=s.scope?.split(" ")??[];return await (t??this.#e).set(e.provider,r,{accessToken:s.access_token,refreshToken:s.refresh_token,expiresAt:null!=s.expires_in?new Date(Date.now()+1e3*s.expires_in):void 0,scopes:n}),{providerName:e.provider,scopes:n}}}
+import { sha256 } from '@noble/hashes/sha2.js';
+import { fromUTF, toB64U } from '@sozai/codec';
+// Pending authorization records self-expire after this window; a callback
+// presenting an older state is rejected and the row is swept on the next start.
+const PENDING_AUTH_TTL_MS = 10 * 60 * 1000;
+// PKCE requires unpadded base64url; toB64U emits `=` padding, so strip it.
+function toB64UNoPad(bytes) {
+    return toB64U(bytes).replace(/=+$/, '');
+}
+export class OAuthService {
+    #credentialProvider;
+    #runtime;
+    #providers;
+    #registry;
+    #connectorAPI;
+    constructor(params){
+        this.#credentialProvider = params.credentialProvider;
+        this.#runtime = params.runtime;
+        this.#providers = params.providers;
+        this.#registry = params.registry;
+        this.#connectorAPI = params.connectorAPI;
+    }
+    async startAuth(args, ownerDID, connectorAPI) {
+        // Prefer the request-scoped API so the pending-auth write joins the mutation
+        // transaction; the base API would deadlock a single-connection SQLite tx.
+        const api = connectorAPI ?? this.#connectorAPI;
+        const provider = this.#providers.find((p)=>p.name === args.provider);
+        if (provider == null) {
+            throw new Error(`OAuth provider "${args.provider}" not found`);
+        }
+        if (provider.clientID == null) {
+            throw new Error(`OAuth provider "${args.provider}" is missing clientID`);
+        }
+        const requestWriteAccess = args.requestWriteAccess === true;
+        const scopes = new Set(provider.baseScopes ?? []);
+        const connectorNames = args.connectors ?? this.#registry.list();
+        for (const name of connectorNames){
+            const connector = this.#registry.get(name);
+            if (connector != null && connector.auth.provider === args.provider) {
+                const auth = connector.auth;
+                if (requestWriteAccess && auth.writeScopes != null) {
+                    for (const scope of auth.writeScopes){
+                        scopes.add(scope);
+                    }
+                } else {
+                    for (const scope of auth.scopes){
+                        scopes.add(scope);
+                    }
+                }
+            }
+        }
+        const state = this.#runtime.getRandomID();
+        const codeVerifier = toB64UNoPad(this.#runtime.getRandomValues(new Uint8Array(32)));
+        const codeChallenge = toB64UNoPad(sha256(fromUTF(codeVerifier)));
+        await api.createPendingAuth({
+            state,
+            codeVerifier,
+            provider: args.provider,
+            ownerDID,
+            createdAt: Date.now()
+        });
+        await api.deleteExpiredPendingAuth(Date.now() - PENDING_AUTH_TTL_MS);
+        const url = new URL(provider.authorizationEndpoint);
+        url.searchParams.set('client_id', provider.clientID);
+        url.searchParams.set('redirect_uri', args.redirectURL);
+        url.searchParams.set('response_type', 'code');
+        url.searchParams.set('scope', Array.from(scopes).join(' '));
+        url.searchParams.set('state', state);
+        url.searchParams.set('code_challenge', codeChallenge);
+        url.searchParams.set('code_challenge_method', 'S256');
+        url.searchParams.set('access_type', 'offline');
+        // select_account forces the account chooser instead of letting Google
+        // auto-resolve the session account (authuser) — multi-account sessions
+        // otherwise intermittently dead-end on accounts.google.com/info/unknownerror.
+        // consent keeps the refresh-token guarantee for access_type=offline.
+        url.searchParams.set('prompt', 'select_account consent');
+        return {
+            url: url.toString(),
+            state
+        };
+    }
+    async completeAuth(args, credentialProvider, connectorAPI) {
+        // Consume via the request-scoped API so the single-use delete joins the
+        // mutation transaction rather than deadlocking a single-connection SQLite tx.
+        const api = connectorAPI ?? this.#connectorAPI;
+        const provider = this.#providers.find((p)=>p.name === args.provider);
+        if (provider == null) {
+            throw new Error(`OAuth provider "${args.provider}" not found`);
+        }
+        if (provider.clientID == null || provider.clientSecret == null) {
+            throw new Error(`OAuth provider "${args.provider}" is missing clientID or clientSecret`);
+        }
+        // Single-use consume rejects CSRF (state we never issued), replay (already
+        // consumed), and unknown callbacks in one check.
+        const pending = await api.consumePendingAuth(args.state);
+        if (pending == null) {
+            throw new Error('Invalid or expired OAuth state');
+        }
+        if (Date.now() - pending.createdAt > PENDING_AUTH_TTL_MS) {
+            throw new Error('OAuth state expired');
+        }
+        if (pending.provider !== args.provider) {
+            throw new Error('OAuth state provider mismatch');
+        }
+        const response = await this.#runtime.fetch(provider.tokenEndpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded'
+            },
+            body: new URLSearchParams({
+                grant_type: 'authorization_code',
+                code: args.code,
+                redirect_uri: args.redirectURL,
+                client_id: provider.clientID,
+                client_secret: provider.clientSecret,
+                code_verifier: pending.codeVerifier
+            })
+        });
+        if (!response.ok) {
+            throw new Error(`Token exchange failed: ${response.statusText}`);
+        }
+        const tokenData = await response.json();
+        const scopes = tokenData.scope?.split(' ') ?? [];
+        // Bind the credential to the owner that initiated the flow, not the ambient
+        // viewer completing the callback, so a stolen code cannot land under another DID.
+        await (credentialProvider ?? this.#credentialProvider).set(args.provider, pending.ownerDID, {
+            accessToken: tokenData.access_token,
+            refreshToken: tokenData.refresh_token,
+            expiresAt: tokenData.expires_in != null ? new Date(Date.now() + tokenData.expires_in * 1000) : undefined,
+            scopes
+        });
+        return {
+            providerName: args.provider,
+            scopes
+        };
+    }
+}

package/lib/registry.js

@@ -1 +1,24 @@
-export class ConnectorRegistry{#e=new Map;register(e){if(this.#e.has(e.name))throw Error(`Connector "${e.name}" is already registered`);this.#e.set(e.name,e)}unregister(e){this.#e.delete(e)}get(e){return this.#e.get(e)}has(e){return this.#e.has(e)}list(){return Array.from(this.#e.keys())}getAll(){return Array.from(this.#e.values())}}
+export class ConnectorRegistry {
+    #connectors = new Map();
+    register(connector) {
+        if (this.#connectors.has(connector.name)) {
+            throw new Error(`Connector "${connector.name}" is already registered`);
+        }
+        this.#connectors.set(connector.name, connector);
+    }
+    unregister(name) {
+        this.#connectors.delete(name);
+    }
+    get(name) {
+        return this.#connectors.get(name);
+    }
+    has(name) {
+        return this.#connectors.has(name);
+    }
+    list() {
+        return Array.from(this.#connectors.keys());
+    }
+    getAll() {
+        return Array.from(this.#connectors.values());
+    }
+}

package/lib/schema.d.ts

@@ -1,6 +1,8 @@
 import type { ConnectorSyncEventPayload } from '@kubun/connector';
 import type { SchemaExtension } from '@kubun/engine';
+import type { EventEmitter } from '@sozai/event';
 import type { ConnectorRegistry } from './registry.js';
+import type { SignedDocumentWriter } from './sync/processor.js';
 /**
  * Combined connector state returned by the `connector` and `connectors` queries.
  * Mirrors `ConnectorSyncStateResult` from `@kubun/graphql/src/context.ts`.
@@ -32,7 +34,7 @@ export type CompleteConnectorAuthInput = {
     provider: string;
     code: string;
     redirectURL: string;
-    state?: string | null;
+    state: string;
 };
 export type CompleteConnectorAuthOutput = {
     providerName: string;
@@ -72,6 +74,18 @@ export type ConnectorActionResult = {
     entity: Record<string, unknown> | null;
     error: ConnectorActionError | null;
 };
+/**
+ * A live viewer→server delegated write capability, resolved to the connector
+ * it authorizes. Surfaced to apps so a viewer can see and revoke the writes it
+ * has delegated to the server.
+ */
+export type ConnectorWriteGrant = {
+    connector: string;
+    provider: string;
+    modelURNs: Array<string>;
+    exp: number;
+    jti: string;
+};
 /**
  * Connector sync event payload for subscriptions (GraphQL result type).
  */
@@ -89,6 +103,23 @@ export type ConnectorSyncEventResult = {
  * Transform a raw `ConnectorSyncEventPayload` into the GraphQL result shape.
  */
 export declare function toConnectorSyncEventResult(event: ConnectorSyncEventPayload): ConnectorSyncEventResult;
+/**
+ * Emitter shape used by `ConnectorManager` to broadcast sync events.
+ */
+export type ConnectorSyncEventEmitter = EventEmitter<{
+    sync: ConnectorSyncEventPayload;
+}>;
+/**
+ * Subscribe to a connector sync-event emitter, yielding GraphQL result shapes.
+ *
+ * Implemented as a manual async iterator rather than an `async function*` wrapper
+ * so that a consumer's `return()` forwards directly to the underlying emitter
+ * generator, removing its listener immediately. A `for await` wrapper instead
+ * queues the `return()` behind a parked `next()` between events, so the emitter
+ * listener would leak until the next event arrives — for an idle subscription,
+ * potentially never.
+ */
+export declare function subscribeToConnectorSyncEvents(emitter: ConnectorSyncEventEmitter, connector?: string | null): AsyncIterableIterator<ConnectorSyncEventResult>;
 /**
  * Per-request context methods for the Connector query and mutation fields.
  * Provided by the context factory when registry + credentials are configured.
@@ -103,7 +134,18 @@ export type ConnectorQueryContext = {
     completeAuth: (args: CompleteConnectorAuthInput) => Promise<CompleteConnectorAuthOutput>;
     triggerSync: (args: SyncTriggerInput) => Promise<SyncTriggerOutput>;
     subscribeToSyncEvents: (connector?: string | null) => AsyncIterable<ConnectorSyncEventResult>;
-    executeAction?: (args: ConnectorActionInput) => Promise<ConnectorActionResult>;
+    executeAction?: (args: ConnectorActionInput, writeDocument: SignedDocumentWriter) => Promise<ConnectorActionResult>;
+    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>>;
 };
 declare module '@kubun/graphql' {
     interface PluginContextMap {