@kubun/plugin-connector 0.14.0 → 0.14.2

package/lib/index.js

@@ -1,14 +1,17 @@
-import { isSigningIdentity } from '@kokuin/token';
+import { isSigningIdentity, normalizeDID } from '@kokuin/token';
 import { createCredentialManager } from '@kubun/credential';
 import { connectorStoreDefinition } from '@kubun/store-connector';
 import { credentialStoreDefinition, getCredentialStore } from '@kubun/store-credential';
 import { executeAction } from './action.js';
 import { createConnectorAPI, createCredentialAPI } from './api.js';
-import { DBCredentialProvider } from './credential.js';
+import { connectorAuthRequiredPayload } from './auth-required.js';
+import { DBCredentialProvider, RefreshingCredentialProvider } from './credential.js';
+import { bridgeCredentialRefreshEvents } from './credential-refresh-bridge.js';
 import { ConnectorManager } from './manager.js';
 import { OAuthService } from './oauth.js';
+import { periodicSyncSubject } from './periodic-sync.js';
 import { ConnectorRegistry } from './registry.js';
-import { createConnectorSchemaExtension, subscribeToConnectorSyncEvents } from './schema.js';
+import { createConnectorSchemaExtension, subscribeToConnectorLifecycleEvents, subscribeToConnectorSyncEvents } from './schema.js';
 import { orchestrateSync } from './sync/orchestrate.js';
 import { DBSyncStateStore } from './sync/state.js';
 import { CONNECTOR_SYNC_CONCURRENCY, CONNECTOR_SYNC_WORKFLOW, createConnectorSyncWorkflow } from './sync/workflow.js';
@@ -25,7 +28,7 @@ export { orchestrateSync } from './sync/orchestrate.js';
 export { EntityProcessor } from './sync/processor.js';
 export { DBSyncStateStore } from './sync/state.js';
 export { CONNECTOR_SYNC_CONCURRENCY, CONNECTOR_SYNC_WORKFLOW, createConnectorSyncWorkflow } from './sync/workflow.js';
-export { DBCredentialProvider };
+export { DBCredentialProvider, RefreshingCredentialProvider,  };
 // 5m after a productive run; idle 15m→6h, error 1m→1h, offline 30s→15m.
 const DEFAULT_PERIODIC_SYNC_POLICY = {
     changed: 300000,
@@ -42,14 +45,26 @@ const DEFAULT_PERIODIC_SYNC_POLICY = {
         max: 900000
     }
 };
+// The engine's own registry has no typed "no such plugin" error — an
+// unregistered `getAPI(name)` throws a plain `Error` with this exact message
+// (packages/engine/src/registry.ts). A message match is the only signal
+// available, so it stays narrow (exact equality, not a substring), and a
+// tripwire test elsewhere pins the engine's message so a future rename fails
+// loudly here instead of silently re-masking real init failures as absence.
+function isWorkflowPluginAbsent(err) {
+    return err instanceof Error && err.message === 'API not registered: workflow';
+}
 // Present the standalone local stack as the unified surface: the credential
-// provider for get/set/delete, its credential API for provenance. Service mode
-// gets provenance as one more procedure, so both modes read it off one object.
+// provider for get/set/delete/peek, its credential API for provenance. Service
+// mode gets provenance as one more procedure, so both modes read it off one
+// object. The refreshing provider's `peek` is forwarded so a disconnect can test
+// existence without triggering a refresh.
 function withProvenance(provider, api) {
     return {
         get: (providerName, ownerDID)=>provider.get(providerName, ownerDID),
         set: (setParams)=>provider.set(setParams),
         delete: (providerName, ownerDID)=>provider.delete(providerName, ownerDID),
+        peek: (providerName, ownerDID)=>provider.peek(providerName, ownerDID),
         getCredentialProvenance: (providerName, ownerDID)=>api.getCredentialProvenance(providerName, ownerDID)
     };
 }
@@ -62,18 +77,37 @@ function displayStatusFor(status) {
     if (status === 'failed') return 'ERROR';
     return 'IDLE';
 }
-async function resolveConnectorState({ connectorAPI, registry, credentialProvider, getWorkflowAPI, viewerDID, connectorName }) {
+async function resolveConnectorState({ connectorAPI, registry, credentialProvider, getWorkflowAPI, viewerDID: rawViewerDID, connectorName }) {
     const connector = registry.get(connectorName);
     if (connector == null) {
         throw new Error(`Connector "${connectorName}" not found`);
     }
+    // Credential and sync-state rows are keyed on the normalized owner (a viewer
+    // can arrive long-form); the workflow status is keyed on the same subject as
+    // the schedule. Fold once so all three reads hit the right rows.
+    const viewerDID = normalizeDID(rawViewerDID);
     const syncState = await connectorAPI.getSyncState(connectorName, viewerDID);
     // The durable, lease-fenced truth: the workflow instance status. Preferred over
     // the hand-written syncState.status row, which a zombie handler can transiently
     // regress after crash-recovery. Falls back to that row only with no workflow
     // plugin (local-only sync) or no instance yet.
     let workflowStatus = null;
-    const workflowAPI = await getWorkflowAPI();
+    // A status read degrades to the syncState-only fallback below on a broken
+    // workflow plugin rather than failing outright — `getStates` fans this out
+    // over every registered connector with `Promise.all`, so one broken plugin
+    // would otherwise blank the whole list. `getWorkflowAPI` already logs the
+    // failure; this stays silent to avoid re-logging on every poll. The one
+    // signal kept is `workflowStatusError`: a genuine init failure (a caught
+    // rejection) sets it so a consumer can tell degraded-because-broken from
+    // degraded-because-absent (a resolved `undefined`, expected in local-only
+    // apps), which leaves it null.
+    let workflowStatusError = null;
+    let workflowAPI;
+    try {
+        workflowAPI = await getWorkflowAPI();
+    } catch  {
+        workflowStatusError = 'WORKFLOW_UNAVAILABLE';
+    }
     if (workflowAPI != null) {
         const instance = await workflowAPI.getCurrentInstance(CONNECTOR_SYNC_WORKFLOW, `${connectorName}:${viewerDID}`);
         if (instance != null) {
@@ -114,7 +148,8 @@ async function resolveConnectorState({ connectorAPI, registry, credentialProvide
             credentialWriterDID,
             lastSyncedAt: null,
             entityCount: null,
-            error: null
+            error: null,
+            workflowStatusError
         };
     }
     return {
@@ -127,7 +162,8 @@ async function resolveConnectorState({ connectorAPI, registry, credentialProvide
         credentialWriterDID,
         lastSyncedAt: syncState.lastSyncedAt ?? null,
         entityCount: syncState.entityCount ?? null,
-        error: syncState.error ?? null
+        error: syncState.error ?? null,
+        workflowStatusError
     };
 }
 // ---- Plugin factory ----
@@ -209,6 +245,12 @@ export function createConnectorPlugin(options) {
         // defaults to params.db for the background (workflow/orchestrate) paths, which
         // run outside any request transaction. A request path passes its own tx.
         let standaloneStack;
+        // Shared single-flight map for the standalone refresh decorator, one per plugin
+        // instance. The cached background stack and each per-request stack build their
+        // own decorator, but they all refresh the same stored credentials; sharing this
+        // map collapses the concurrent sync runs' refreshes of one credential to a
+        // single token exchange and a single emitted outcome.
+        const refreshInFlight = new Map();
         const getStandaloneStack = (stores = params.db)=>{
             // The background stack is cached on params.db; a per-request tx builds a
             // fresh stack so its reads and writes join that transaction.
@@ -220,13 +262,32 @@ export function createConnectorPlugin(options) {
                 serverWrappableDID,
                 getControllerMethods
             });
+            // The DB provider is storage-only; the decorator adds transparent
+            // refresh-on-read over it, writing a refreshed token back through the same
+            // storage provider so it joins the request's transaction.
+            const provider = new RefreshingCredentialProvider({
+                inner: new DBCredentialProvider({
+                    api
+                }),
+                runtime: params.runtime,
+                providers,
+                refreshInFlight
+            });
+            // Surface this decorator's refresh outcomes as connector lifecycle events.
+            // Each stack builds its own decorator with its own emitter, so the bridge
+            // is attached per construction; a per-request instance is short-lived, the
+            // background instance is cached. Deferring the emit through this stack's own
+            // `stores.onCommit` keeps a per-request refresh's lifecycle listener out of
+            // the mutation transaction that owns the single DB connection.
+            bridgeCredentialRefreshEvents({
+                source: provider.refreshEvents,
+                manager,
+                registry,
+                defer: (fn)=>stores.onCommit(fn)
+            });
             const stack = {
                 api,
-                provider: new DBCredentialProvider({
-                    api,
-                    runtime: params.runtime,
-                    providers
-                })
+                provider
             };
             if (stores === params.db) standaloneStack = stack;
             return stack;
@@ -237,6 +298,8 @@ export function createConnectorPlugin(options) {
         const resolveCredentialSurface = async (stores)=>{
             const serviceProvider = await credentialServiceProviderPromise;
             if (serviceProvider != null) {
+                // The remote service provider has no `peek`; a consumer falls back to
+                // its (non-local-refreshing) `get`.
                 return {
                     provider: serviceProvider
                 };
@@ -270,6 +333,15 @@ export function createConnectorPlugin(options) {
             logger,
             defaults: options.defaults
         });
+        // Emit `connector:authRequired` for a genuinely absent credential. The deep
+        // sync sites (workflow, orchestrate, action) only know `{ provider, ownerDID }`;
+        // the connector mapping, owner normalization and `reason: 'absent'` are folded
+        // in here. Timing is the caller's: the workflow and orchestrate sites emit
+        // directly (matching their sibling sync events); the action site defers via
+        // `stores.onCommit` because it runs inside the request's mutation transaction.
+        const emitAuthRequiredNow = (provider, ownerDID)=>{
+            manager.emitLifecycle('connector:authRequired', connectorAuthRequiredPayload(registry, provider, ownerDID));
+        };
         const oauthService = new OAuthService({
             runtime: params.runtime,
             providers,
@@ -288,7 +360,8 @@ export function createConnectorPlugin(options) {
             stores: params.db,
             mutateDocuments: params.graph.mutateDocuments,
             boundary: options.defaults?.boundary,
-            logger
+            logger,
+            emitAuthRequired: ({ provider, ownerDID })=>emitAuthRequiredNow(provider, ownerDID)
         });
         let workflowAPIPromise;
         const getWorkflowAPI = ()=>{
@@ -299,20 +372,132 @@ export function createConnectorPlugin(options) {
                     });
                     api.register(connectorSyncWorkflow.definition);
                     return api;
-                }).catch(()=>undefined);
+                }).catch((err)=>{
+                    if (isWorkflowPluginAbsent(err)) return undefined;
+                    // A present-but-broken plugin, not a genuinely absent one: don't
+                    // cache this rejection as a permanent no-op — reset so a later
+                    // call rebuilds the API instead of replaying a wedged failure
+                    // (or a transient one that has since cleared).
+                    workflowAPIPromise = undefined;
+                    logger.warn('workflow API resolution failed {error}', {
+                        error: err instanceof Error ? err.message : String(err)
+                    });
+                    throw err;
+                });
             }
             return workflowAPIPromise;
         };
+        // Register the connector-sync workflow eagerly at startup rather than on the
+        // first sync/schedule call. `getAPI` resolves only after the engine closes its
+        // plugin gate (every plugin's API registered), so this settles regardless of
+        // plugin order — and before any GraphQL request. Without it, a generic
+        // `periodicSync` query/mutation arriving first after a restart would see the
+        // workflow unregistered and bypass its managed-schedule protection.
+        void getWorkflowAPI().catch(()=>undefined);
+        // Owner-bound periodic-sync control. The public (viewer) path and the
+        // auto-enable-on-auth subscriber both route here so the schedule is keyed on
+        // the credential owner's normalized DID — matching the manual-sync singleton
+        // so scheduled and manual runs interlock. The emit is direct (not deferred):
+        // the sibling workflow call is already direct here, and the emit touches no
+        // store.
+        const enablePeriodicSyncForOwner = async (connector, ownerDID, policyOverride, scheduleOpts)=>{
+            if (!registry.has(connector)) {
+                throw new Error(`unknown connector: ${connector}`);
+            }
+            const workflowAPI = await getWorkflowAPI();
+            if (workflowAPI == null) {
+                throw new Error('workflow plugin required for periodic sync');
+            }
+            const { owner, subjectKey } = periodicSyncSubject(connector, ownerDID);
+            const policy = policyOverride ?? options.defaults?.periodicSyncPolicy ?? DEFAULT_PERIODIC_SYNC_POLICY;
+            const { id } = await workflowAPI.scheduleAdaptive(CONNECTOR_SYNC_WORKFLOW, {
+                connectorName: connector,
+                ownerDID: owner,
+                full: false
+            }, {
+                policy,
+                subjectKey,
+                reactivate: scheduleOpts?.reactivate
+            });
+            const result = await workflowAPI.getPeriodicSync(id);
+            // `reactivate: false` preserves a user-disabled row, so only announce
+            // `enabled` when the schedule actually is — a re-auth of a paused connector
+            // must not emit a state change that did not happen.
+            if (result?.enabled) {
+                manager.emitLifecycle('periodicSync:enabled', {
+                    connector,
+                    ownerDID: owner,
+                    subjectKey
+                });
+            }
+            return result;
+        };
+        const disablePeriodicSyncForOwner = async (connector, ownerDID)=>{
+            if (!registry.has(connector)) {
+                throw new Error(`unknown connector: ${connector}`);
+            }
+            const workflowAPI = await getWorkflowAPI();
+            if (workflowAPI == null) {
+                throw new Error('workflow plugin required for periodic sync');
+            }
+            const { owner, subjectKey } = periodicSyncSubject(connector, ownerDID);
+            const result = await workflowAPI.setPeriodicSyncEnabled(`${CONNECTOR_SYNC_WORKFLOW}:${subjectKey}`, false);
+            // A null result means no such schedule existed — nothing changed, so no
+            // `disabled` event.
+            if (result != null) {
+                manager.emitLifecycle('periodicSync:disabled', {
+                    connector,
+                    ownerDID: owner,
+                    subjectKey
+                });
+            }
+            return result;
+        };
+        // Opt-in: arm periodic sync for the authenticated owner on every
+        // `connector:authenticated`. Subscribed on `lifecycleEvents` (the merged,
+        // tagged channel), not the per-event `events` channel forwarded to
+        // external plugin consumers as `connectorPluginAPI.events` — this
+        // subscriber is the connector plugin's own internal wiring, not a
+        // consumer of its public surface, so it stays decoupled from whatever
+        // external listeners do with `events`. `reactivate: false` so a schedule
+        // the user explicitly disabled is not silently re-armed by a later
+        // re-authentication; an absent schedule is still created enabled. Fire-
+        // and-forget and best-effort: a missing workflow plugin (or any other
+        // failure) is caught here rather than thrown into the emitter's listener,
+        // which would otherwise only be logged and swallowed.
+        if (options.autoEnablePeriodicSync) {
+            manager.lifecycleEvents.on('lifecycle', (event)=>{
+                if (event.type !== 'connector:authenticated') return;
+                for (const connector of event.connectors){
+                    enablePeriodicSyncForOwner(connector, event.ownerDID, undefined, {
+                        reactivate: false
+                    }).catch((err)=>{
+                        logger.debug('auto-enable periodic sync skipped {connector} {ownerDID}', {
+                            connector,
+                            ownerDID: event.ownerDID,
+                            error: err instanceof Error ? err.message : String(err)
+                        });
+                    });
+                }
+            });
+        }
         // Process-local dedup for the no-workflow-plugin fallback path only (the
         // workflow singleton guards the primary path).
         const orchestrateInFlight = new Set();
+        // The exposed API: storage surface plus a listen-only view of the live
+        // manager's event channel. Consumers subscribe through `events`; the emit
+        // side stays with the manager, which internal producers hold directly.
+        const connectorPluginAPI = {
+            ...connectorAPI,
+            events: manager.events
+        };
         return {
             name: 'connector',
             schemaExtension: (config)=>createConnectorSchemaExtension({
                     registry,
                     config: config
                 }),
-            api: connectorAPI,
+            api: connectorPluginAPI,
             createContextFactory: ()=>{
                 return (ctx, stores)=>{
                     // Per-request connector API backed by the request's StoreProvider
@@ -332,7 +517,10 @@ export function createConnectorPlugin(options) {
                     };
                     // A base provider that defers to the resolved surface, so synchronous
                     // consumers (write-grants, executeAction) get one object while the
-                    // mode resolves lazily behind it.
+                    // mode resolves lazily behind it. `peek` uses the surface's
+                    // non-refreshing read when available, falling back to `get` (service
+                    // mode has no local peek), so a disconnect's existence check never
+                    // triggers a standalone refresh.
                     const requestProvider = {
                         get: async (providerName, ownerDID)=>(await getSurface()).provider.get(providerName, ownerDID),
                         set: async (setParams)=>{
@@ -341,6 +529,10 @@ export function createConnectorPlugin(options) {
                         delete: async (providerName, ownerDID)=>{
                             await (await getSurface()).provider.delete(providerName, ownerDID);
                         },
+                        peek: async (providerName, ownerDID)=>{
+                            const { provider } = await getSurface();
+                            return provider.peek != null ? provider.peek(providerName, ownerDID) : provider.get(providerName, ownerDID);
+                        },
                         getCredentialProvenance: async (providerName, ownerDID)=>(await getSurface()).provider.getCredentialProvenance(providerName, ownerDID)
                     };
                     return {
@@ -368,7 +560,27 @@ export function createConnectorPlugin(options) {
                         // `params.db` here would open a second connection inside the
                         // startConnectorAuth mutation tx and deadlock single-connection SQLite.
                         startAuth: async (args)=>oauthService.startAuth(args, ctx.viewerDID, requestAPI, getControllerMethods(stores)),
-                        completeAuth: (args)=>oauthService.completeAuth(args, requestProvider, requestAPI),
+                        completeAuth: async (args)=>{
+                            const { output, ownerDID } = await oauthService.completeAuth(args, requestProvider, requestAPI);
+                            // Announce the authorization to lifecycle consumers (e.g. auto-enable),
+                            // carrying the provider's connectors and the owner in its normalized
+                            // (short) form — the same folding the credential row is keyed on.
+                            const connectors = registry.getAll().filter((connector)=>connector.auth.provider === output.providerName).map((connector)=>connector.name);
+                            const normalizedOwnerDID = normalizeDID(ownerDID);
+                            // After the mutation commits, never inside it: a subscriber that
+                            // schedules a sync writes through the top-level db, which would
+                            // deadlock the single-connection tx still held here (as triggerSync
+                            // defers its enqueue below for the same reason).
+                            stores.onCommit(()=>{
+                                manager.emitLifecycle('connector:authenticated', {
+                                    provider: output.providerName,
+                                    connectors,
+                                    ownerDID: normalizedOwnerDID,
+                                    scopes: output.scopes
+                                });
+                            });
+                            return output;
+                        },
                         triggerSync: async (args)=>{
                             if (!registry.has(args.connector)) {
                                 return {
@@ -377,7 +589,10 @@ export function createConnectorPlugin(options) {
                                 };
                             }
                             const connectorName = args.connector;
-                            const ownerDID = ctx.viewerDID;
+                            // Fold the owner to its short form so the singleton subject matches
+                            // the periodic schedule's, and the workflow reads the credential and
+                            // sync-state rows keyed on the normalized owner.
+                            const ownerDID = normalizeDID(ctx.viewerDID);
                             const full = args.full ?? false;
                             // Defer to after the mutation commits — both the workflow enqueue
                             // (a store insert) and the fallback background run use the top-level
@@ -408,9 +623,20 @@ export function createConnectorPlugin(options) {
                                         boundary: options.defaults?.boundary,
                                         inFlight: orchestrateInFlight,
                                         logger,
-                                        mutateDocuments: params.graph.mutateDocuments
+                                        mutateDocuments: params.graph.mutateDocuments,
+                                        emitAuthRequired: ({ provider, ownerDID: owner })=>emitAuthRequiredNow(provider, owner)
+                                    });
+                                })().catch((err)=>{
+                                    // Surface a deferred-run failure instead of swallowing it — the
+                                    // workflow enqueue and the fallback orchestrate both settle here.
+                                    // The emit is failure-isolated (a throwing subscriber is logged
+                                    // by the emitter), so it needs no guard of its own.
+                                    manager.emitSyncEvent({
+                                        type: 'error',
+                                        connectorName,
+                                        error: err instanceof Error ? err.message : String(err)
                                     });
-                                })().catch(()=>{});
+                                });
                             });
                             return {
                                 status: 'STARTED',
@@ -418,43 +644,30 @@ export function createConnectorPlugin(options) {
                             };
                         },
                         subscribeToSyncEvents: (connector)=>subscribeToConnectorSyncEvents(manager.syncEvents, connector),
-                        // Recurring-sync control. Viewer-at-enable: the schedule is registered
-                        // under a viewer and its subject is `${connector}:${ownerDID}` —
-                        // identical to the manual sync singletonKey, so scheduled and manual
+                        // Viewer-scoped façade over the manager's INTERNAL merged lifecycle
+                        // channel: the viewer captured here (folded to its short form, as
+                        // every lifecycle payload's owner is) gates delivery, so one viewer
+                        // never observes another's auth activity.
+                        subscribeToLifecycleEvents: (connector)=>subscribeToConnectorLifecycleEvents(manager.lifecycleEvents, {
+                                viewerDID: normalizeDID(ctx.viewerDID),
+                                connector
+                            }),
+                        // Recurring-sync control. The schedule binds to the viewer as the
+                        // credential owner; its subject is `${connector}:${normalizeDID(owner)}`
+                        // — identical to the manual sync singletonKey, so scheduled and manual
                         // runs interlock. Scheduled fires later write with no viewer, via the
                         // engine-signed mutateDocuments path the workflow already uses.
-                        enablePeriodicSync: async (connector, policyOverride)=>{
-                            const workflowAPI = await getWorkflowAPI();
-                            if (workflowAPI == null) {
-                                throw new Error('workflow plugin required for periodic sync');
-                            }
-                            const ownerDID = ctx.viewerDID;
-                            const subjectKey = `${connector}:${ownerDID}`;
-                            const policy = policyOverride ?? options.defaults?.periodicSyncPolicy ?? DEFAULT_PERIODIC_SYNC_POLICY;
-                            const { id } = await workflowAPI.scheduleAdaptive(CONNECTOR_SYNC_WORKFLOW, {
-                                connectorName: connector,
-                                ownerDID,
-                                full: false
-                            }, {
-                                policy,
-                                subjectKey
-                            });
-                            return workflowAPI.getPeriodicSync(id);
-                        },
-                        disablePeriodicSync: async (connector)=>{
-                            const workflowAPI = await getWorkflowAPI();
-                            if (workflowAPI == null) {
-                                throw new Error('workflow plugin required for periodic sync');
-                            }
-                            const subjectKey = `${connector}:${ctx.viewerDID}`;
-                            return workflowAPI.setPeriodicSyncEnabled(`${CONNECTOR_SYNC_WORKFLOW}:${subjectKey}`, false);
-                        },
+                        enablePeriodicSync: (connector, policyOverride)=>enablePeriodicSyncForOwner(connector, ctx.viewerDID, policyOverride),
+                        disablePeriodicSync: (connector)=>disablePeriodicSyncForOwner(connector, ctx.viewerDID),
                         getPeriodicSync: async (connector)=>{
+                            if (!registry.has(connector)) {
+                                throw new Error(`unknown connector: ${connector}`);
+                            }
                             const workflowAPI = await getWorkflowAPI();
                             if (workflowAPI == null) {
                                 throw new Error('workflow plugin required for periodic sync');
                             }
-                            const subjectKey = `${connector}:${ctx.viewerDID}`;
+                            const { subjectKey } = periodicSyncSubject(connector, ctx.viewerDID);
                             return workflowAPI.getPeriodicSync(`${CONNECTOR_SYNC_WORKFLOW}:${subjectKey}`);
                         },
                         executeAction: async (args, writeDocument)=>{
@@ -473,10 +686,18 @@ export function createConnectorPlugin(options) {
                                     stores,
                                     registry,
                                     credentialProvider: requestProvider,
-                                    ownerDID: ctx.viewerDID,
+                                    // The credential row is keyed on the normalized owner.
+                                    ownerDID: normalizeDID(ctx.viewerDID),
                                     logger,
                                     writeDocument,
-                                    writeAttachment
+                                    writeAttachment,
+                                    // The action runs inside the request's mutation transaction;
+                                    // defer the emit past commit so a subscriber that schedules a
+                                    // sync does not deadlock the single-connection tx still held
+                                    // here (same guard as completeAuth and onCredentialRemoved).
+                                    emitAuthRequired: ({ provider, ownerDID })=>{
+                                        stores.onCommit(()=>emitAuthRequiredNow(provider, ownerDID));
+                                    }
                                 });
                                 return {
                                     documentID: result.documentID,
@@ -505,7 +726,23 @@ export function createConnectorPlugin(options) {
                             viewerDID: ctx.viewerDID,
                             stores,
                             credentialProvider: requestProvider,
-                            hlc: params.hlc
+                            hlc: params.hlc,
+                            // Announce a removed credential to lifecycle consumers, carrying the
+                            // provider's connectors and the owner in normalized (short) form.
+                            // After the mutation commits, never inside it: a subscriber that
+                            // schedules work writes through the top-level db, which would
+                            // deadlock the single-connection tx still held here (same guard as
+                            // completeAuth).
+                            onCredentialRemoved: ({ provider, ownerDID })=>{
+                                const connectors = registry.getAll().filter((connector)=>connector.auth.provider === provider).map((connector)=>connector.name);
+                                stores.onCommit(()=>{
+                                    manager.emitLifecycle('connector:deauthenticated', {
+                                        provider,
+                                        connectors,
+                                        ownerDID: normalizeDID(ownerDID)
+                                    });
+                                });
+                            }
                         })
                     };
                 };

package/lib/manager.d.ts

@@ -1,6 +1,6 @@
 import type { ConnectorSyncEventPayload, SyncBoundary } from '@kubun/connector';
 import type { Logger } from '@kubun/logger';
-import { EventEmitter } from '@sozai/event';
+import { EventEmitter, type EventsSource } from '@sozai/event';
 import type { ConnectorRegistry } from './registry.js';
 type SyncEvents = {
     sync: ConnectorSyncEventPayload;
@@ -12,10 +12,63 @@ export type ConnectorActivatedEvent = {
 export type ConnectorDeactivatedEvent = {
     connectorName: string;
 };
+export type ConnectorAuthenticatedEvent = {
+    provider: string;
+    connectors: Array<string>;
+    ownerDID: string;
+    scopes: Array<string>;
+};
+export type ConnectorDeauthenticatedEvent = {
+    provider: string;
+    connectors: Array<string>;
+    ownerDID: string;
+};
+export type ConnectorCredentialRefreshedEvent = {
+    provider: string;
+    connectors: Array<string>;
+    ownerDID: string;
+    scopes: Array<string>;
+    expiresAt?: number;
+};
+export type ConnectorAuthRequiredEvent = {
+    provider: string;
+    connectors: Array<string>;
+    ownerDID: string;
+    reason: 'absent' | 'invalid_grant';
+};
+export type PeriodicSyncEnabledEvent = {
+    connector: string;
+    ownerDID: string;
+    subjectKey: string;
+};
+export type PeriodicSyncDisabledEvent = {
+    connector: string;
+    ownerDID: string;
+    subjectKey: string;
+};
+/** Typed lifecycle channel: one event name per producer, each with its own payload. */
+export type ConnectorLifecycleEvents = {
+    'connector:authenticated': ConnectorAuthenticatedEvent;
+    'connector:deauthenticated': ConnectorDeauthenticatedEvent;
+    'connector:credentialRefreshed': ConnectorCredentialRefreshedEvent;
+    'connector:authRequired': ConnectorAuthRequiredEvent;
+    'periodicSync:enabled': PeriodicSyncEnabledEvent;
+    'periodicSync:disabled': PeriodicSyncDisabledEvent;
+};
+export type ConnectorLifecycleEventName = keyof ConnectorLifecycleEvents;
+/** Merged lifecycle channel payload: each typed event tagged with its name. */
+export type ConnectorLifecycleEventPayload = {
+    [Name in ConnectorLifecycleEventName]: {
+        type: Name;
+    } & ConnectorLifecycleEvents[Name];
+}[ConnectorLifecycleEventName];
+type LifecycleEvents = {
+    lifecycle: ConnectorLifecycleEventPayload;
+};
 export type ConnectorManagerEvents = {
     'connector:activated': ConnectorActivatedEvent;
     'connector:deactivated': ConnectorDeactivatedEvent;
-};
+} & ConnectorLifecycleEvents;
 export type ConnectorManagerParams = {
     registry: ConnectorRegistry;
     logger: Logger;
@@ -36,8 +89,23 @@ export declare class ConnectorManager {
     listActive(): Array<string>;
     onConnectorActivated(callback: (event: ConnectorActivatedEvent) => void): () => void;
     onConnectorDeactivated(callback: (event: ConnectorDeactivatedEvent) => void): () => void;
+    /**
+     * Listen-only view of the typed event channel. Consumers subscribe here (e.g.
+     * `events.on('connector:authenticated', …)`); the emit side stays private to
+     * the manager, so the returned surface carries no `fire`/`emit`.
+     */
+    get events(): EventsSource<ConnectorManagerEvents>;
+    /** Listen-only view of the merged lifecycle channel carrying every tagged event. */
+    get lifecycleEvents(): EventsSource<LifecycleEvents>;
+    /**
+     * Emit a lifecycle event to both the typed per-event channel and the merged
+     * channel. The two `fire` calls are independent and failure-isolated: a
+     * throwing listener on either channel is reported via the logger and cannot
+     * reject the caller or block the other channel.
+     */
+    emitLifecycle<Name extends ConnectorLifecycleEventName>(type: Name, payload: ConnectorLifecycleEvents[Name]): void;
     get syncEvents(): EventEmitter<SyncEvents>;
-    emitSyncEvent(event: ConnectorSyncEventPayload): Promise<void>;
+    emitSyncEvent(event: ConnectorSyncEventPayload): void;
     onSyncEvent(callback: (event: ConnectorSyncEventPayload) => void): () => void;
 }
 export {};