@kubun/plugin-connector 0.14.1 → 0.14.2

package/lib/manager.js

@@ -3,12 +3,22 @@ export class ConnectorManager {
     #registry;
     #logger;
     #activeGraphs = new Map();
-    #events = new EventEmitter();
-    #syncEvents = new EventEmitter();
+    #events;
+    #syncEvents;
+    #lifecycleEvents;
     #defaults;
     constructor(params){
         this.#registry = params.registry;
         this.#logger = params.logger;
+        this.#events = new EventEmitter({
+            logger: params.logger
+        });
+        this.#syncEvents = new EventEmitter({
+            logger: params.logger
+        });
+        this.#lifecycleEvents = new EventEmitter({
+            logger: params.logger
+        });
         this.#defaults = {
             boundary: params.defaults?.boundary ?? {
                 maxAge: 'P90D'
@@ -35,7 +45,7 @@ export class ConnectorManager {
                     name,
                     graphID
                 });
-                this.#events.emit('connector:activated', {
+                this.#events.fire('connector:activated', {
                     connectorName: name,
                     graphID
                 });
@@ -54,7 +64,7 @@ export class ConnectorManager {
                 this.#logger.info('Connector {name} deactivated', {
                     name
                 });
-                this.#events.emit('connector:deactivated', {
+                this.#events.fire('connector:deactivated', {
                     connectorName: name
                 });
             }
@@ -77,11 +87,36 @@ export class ConnectorManager {
     onConnectorDeactivated(callback) {
         return this.#events.on('connector:deactivated', callback);
     }
+    /**
+   * 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() {
+        return this.#events;
+    }
+    /** Listen-only view of the merged lifecycle channel carrying every tagged event. */ get lifecycleEvents() {
+        return this.#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(type, payload) {
+        this.#emitLifecycle(type, payload);
+    }
+    #emitLifecycle(type, payload) {
+        this.#events.fire(type, payload);
+        this.#lifecycleEvents.fire('lifecycle', {
+            type,
+            ...payload
+        });
+    }
     get syncEvents() {
         return this.#syncEvents;
     }
-    async emitSyncEvent(event) {
-        await this.#syncEvents.emit('sync', event);
+    emitSyncEvent(event) {
+        this.#syncEvents.fire('sync', event);
     }
     onSyncEvent(callback) {
         return this.#syncEvents.on('sync', callback);

package/lib/oauth.d.ts

@@ -4,6 +4,10 @@ import type { Runtime } from '@sozai/runtime';
 import type { ConnectorAPI, CredentialAPI } from './api.js';
 import type { ConnectorRegistry } from './registry.js';
 import type { CompleteConnectorAuthInput, CompleteConnectorAuthOutput, StartConnectorAuthInput, StartConnectorAuthOutput } from './schema.js';
+export type CompleteAuthResult = {
+    output: CompleteConnectorAuthOutput;
+    ownerDID: string;
+};
 export type OAuthServiceParams = {
     runtime: Runtime;
     providers: Array<OAuthProviderDefinition>;
@@ -16,5 +20,5 @@ export declare class OAuthService {
     #private;
     constructor(params: OAuthServiceParams);
     startAuth(args: StartConnectorAuthInput, ownerDID: string, connectorAPI?: ConnectorAPI, preflightMethods?: MethodRegistry): Promise<StartConnectorAuthOutput>;
-    completeAuth(args: CompleteConnectorAuthInput, credentialProvider?: CredentialProvider, connectorAPI?: ConnectorAPI): Promise<CompleteConnectorAuthOutput>;
+    completeAuth(args: CompleteConnectorAuthInput, credentialProvider?: CredentialProvider, connectorAPI?: ConnectorAPI): Promise<CompleteAuthResult>;
 }

package/lib/oauth.js

@@ -167,8 +167,11 @@ export class OAuthService {
             controllerWrappableDID: pending.controllerWrappableDID ?? undefined
         });
         return {
-            providerName: args.provider,
-            scopes
+            output: {
+                providerName: args.provider,
+                scopes
+            },
+            ownerDID: pending.ownerDID
         };
     }
 }

package/lib/periodic-sync.d.ts

@@ -0,0 +1,4 @@
+export declare function periodicSyncSubject(connector: string, ownerDID: string): {
+    owner: string;
+    subjectKey: string;
+};

package/lib/periodic-sync.js

@@ -0,0 +1,12 @@
+import { normalizeDID } from '@kokuin/token';
+// The adaptive schedule and the manual-sync singleton share one subject so a
+// scheduled run and a manual trigger interlock. Both fold the owner to its short
+// form first: credential rows and sync-state rows are keyed on the normalized
+// DID, and a viewer can arrive long-form (a mutation's `iss`).
+export function periodicSyncSubject(connector, ownerDID) {
+    const owner = normalizeDID(ownerDID);
+    return {
+        owner,
+        subjectKey: `${connector}:${owner}`
+    };
+}

package/lib/schema.d.ts

@@ -1,7 +1,8 @@
 import type { ConnectorSyncEventPayload } from '@kubun/connector';
 import type { SchemaExtension } from '@kubun/engine';
 import type { AdaptivePolicy } from '@kubun/plugin-workflow-api';
-import type { EventEmitter } from '@sozai/event';
+import type { EventEmitter, EventsSource } from '@sozai/event';
+import type { ConnectorLifecycleEventName, ConnectorLifecycleEventPayload } from './manager.js';
 import type { ConnectorRegistry } from './registry.js';
 import type { SignedDocumentWriter } from './sync/processor.js';
 /**
@@ -19,6 +20,7 @@ export type ConnectorState = {
     lastSyncedAt: string | null;
     entityCount: number | null;
     error: string | null;
+    workflowStatusError: 'WORKFLOW_UNAVAILABLE' | null;
 };
 /**
  * Input/output types for connector auth mutations.
@@ -139,6 +141,47 @@ export type ConnectorSyncEventEmitter = EventEmitter<{
  * potentially never.
  */
 export declare function subscribeToConnectorSyncEvents(emitter: ConnectorSyncEventEmitter, connector?: string | null): AsyncIterableIterator<ConnectorSyncEventResult>;
+/**
+ * Merged lifecycle event payload for subscriptions (GraphQL result type). Flat
+ * and nullable: a given event carries only the fields its variant defines, and
+ * the rest resolve to null (mirrors `ConnectorSyncEventResult`).
+ */
+export type ConnectorLifecycleEventResult = {
+    type: ConnectorLifecycleEventName;
+    ownerDID: string;
+    provider: string | null;
+    connector: string | null;
+    connectors: Array<string> | null;
+    scopes: Array<string> | null;
+    expiresAt: number | null;
+    reason: string | null;
+    subjectKey: string | null;
+};
+/**
+ * Flatten a merged lifecycle payload into the GraphQL result shape, filling the
+ * fields absent from the variant with null.
+ */
+export declare function toConnectorLifecycleEventResult(event: ConnectorLifecycleEventPayload): ConnectorLifecycleEventResult;
+/**
+ * Subscribe to the merged lifecycle channel as a single viewer, yielding GraphQL
+ * result shapes. Every event is filtered by `ownerDID` against the caller's
+ * already-normalized `viewerDID`, so one viewer never observes another's auth
+ * activity; an optional `connector` further restricts delivery, matching both
+ * the auth-family `connectors[]` membership and the periodicSync single
+ * `connector`. Built on the same manual async iterator as
+ * `subscribeToConnectorSyncEvents` so a consumer's `return()` removes the
+ * emitter listener immediately rather than leaking behind a parked read.
+ *
+ * The emitter is the manager's listen-only `EventsSource`; `fromEmitter` only
+ * reads its `.on`, but its parameter is typed to the concrete emitter class, so
+ * the source is narrowed to it here.
+ */
+export declare function subscribeToConnectorLifecycleEvents(emitter: EventsSource<{
+    lifecycle: ConnectorLifecycleEventPayload;
+}>, opts: {
+    viewerDID: string;
+    connector?: string | null;
+}): AsyncIterableIterator<ConnectorLifecycleEventResult>;
 /**
  * Per-request context methods for the Connector query and mutation fields.
  * Provided by the context factory when registry + credentials are configured.
@@ -153,6 +196,7 @@ export type ConnectorQueryContext = {
     completeAuth: (args: CompleteConnectorAuthInput) => Promise<CompleteConnectorAuthOutput>;
     triggerSync: (args: SyncTriggerInput) => Promise<SyncTriggerOutput>;
     subscribeToSyncEvents: (connector?: string | null) => AsyncIterable<ConnectorSyncEventResult>;
+    subscribeToLifecycleEvents: (connector?: string | null) => AsyncIterable<ConnectorLifecycleEventResult>;
     executeAction?: (args: ConnectorActionInput, writeDocument: SignedDocumentWriter) => Promise<ConnectorActionResult>;
     grantWriteCapability?: (args: {
         connector: string;

package/lib/schema.js

@@ -58,6 +58,107 @@ import { fromEmitter } from '@sozai/generator';
         }
     };
 }
+/**
+ * Flatten a merged lifecycle payload into the GraphQL result shape, filling the
+ * fields absent from the variant with null.
+ */ export function toConnectorLifecycleEventResult(event) {
+    const result = {
+        type: event.type,
+        ownerDID: event.ownerDID,
+        provider: null,
+        connector: null,
+        connectors: null,
+        scopes: null,
+        expiresAt: null,
+        reason: null,
+        subjectKey: null
+    };
+    switch(event.type){
+        case 'connector:authenticated':
+            result.provider = event.provider;
+            result.connectors = event.connectors;
+            result.scopes = event.scopes;
+            break;
+        case 'connector:deauthenticated':
+            result.provider = event.provider;
+            result.connectors = event.connectors;
+            break;
+        case 'connector:credentialRefreshed':
+            result.provider = event.provider;
+            result.connectors = event.connectors;
+            result.scopes = event.scopes;
+            result.expiresAt = event.expiresAt ?? null;
+            break;
+        case 'connector:authRequired':
+            result.provider = event.provider;
+            result.connectors = event.connectors;
+            result.reason = event.reason;
+            break;
+        case 'periodicSync:enabled':
+        case 'periodicSync:disabled':
+            result.connector = event.connector;
+            result.subjectKey = event.subjectKey;
+            break;
+    }
+    return result;
+}
+/**
+ * Subscribe to the merged lifecycle channel as a single viewer, yielding GraphQL
+ * result shapes. Every event is filtered by `ownerDID` against the caller's
+ * already-normalized `viewerDID`, so one viewer never observes another's auth
+ * activity; an optional `connector` further restricts delivery, matching both
+ * the auth-family `connectors[]` membership and the periodicSync single
+ * `connector`. Built on the same manual async iterator as
+ * `subscribeToConnectorSyncEvents` so a consumer's `return()` removes the
+ * emitter listener immediately rather than leaking behind a parked read.
+ *
+ * The emitter is the manager's listen-only `EventsSource`; `fromEmitter` only
+ * reads its `.on`, but its parameter is typed to the concrete emitter class, so
+ * the source is narrowed to it here.
+ */ export function subscribeToConnectorLifecycleEvents(emitter, opts) {
+    const { viewerDID, connector } = opts;
+    const filter = (event)=>{
+        if (event.ownerDID !== viewerDID) {
+            return false;
+        }
+        if (connector == null) {
+            return true;
+        }
+        return 'connectors' in event ? event.connectors.includes(connector) : event.connector === connector;
+    };
+    const generator = fromEmitter(emitter, 'lifecycle', {
+        filter
+    });
+    return {
+        [Symbol.asyncIterator] () {
+            return this;
+        },
+        async next () {
+            const { done, value } = await generator.next();
+            return done ? {
+                done: true,
+                value: undefined
+            } : {
+                done: false,
+                value: toConnectorLifecycleEventResult(value)
+            };
+        },
+        async return () {
+            await generator.return();
+            return {
+                done: true,
+                value: undefined
+            };
+        },
+        async throw (reason) {
+            await generator.throw(reason);
+            return {
+                done: true,
+                value: undefined
+            };
+        }
+    };
+}
 function requireConnector(ctx) {
     if (ctx.connector == null) {
         throw new Error('connector plugin is not wired into this context');
@@ -116,6 +217,7 @@ type Connector implements Node {
   lastSyncedAt: String
   entityCount: Int
   error: String
+  workflowStatusError: String
 }
 
 type StartConnectorAuthResult {
@@ -144,6 +246,18 @@ type ConnectorSyncEvent {
   error: String
 }
 
+type ConnectorLifecycleEvent {
+  type: String!
+  ownerDID: String!
+  provider: String
+  connector: String
+  connectors: [String!]
+  scopes: [String!]
+  expiresAt: Float
+  reason: String
+  subjectKey: String
+}
+
 type ConnectorActionError {
   code: String!
   message: String!
@@ -175,6 +289,7 @@ extend type Mutation {
 
 extend type Subscription {
   connectorSyncEvents(connector: String): ConnectorSyncEvent!
+  connectorLifecycleEvents(connector: String): ConnectorLifecycleEvent!
 }
 `);
     // Recurring-sync control. Gated because it references `PeriodicSync`, which is
@@ -398,6 +513,13 @@ input ConnectorUpdate${modelName}Input {
                 const ctx = context;
                 return requireConnector(ctx).subscribeToSyncEvents(args.connector);
             }
+        },
+        connectorLifecycleEvents: {
+            resolve: (event)=>event,
+            subscribe: (_source, args, context)=>{
+                const ctx = context;
+                return requireConnector(ctx).subscribeToLifecycleEvents(args.connector);
+            }
         }
     };
     return {

package/lib/sync/orchestrate.d.ts

@@ -10,7 +10,7 @@ import type { MutateDocuments } from './processor.js';
  * this type can be replaced with the concrete class.
  */
 export type SyncEventEmitter = {
-    emitSyncEvent(event: ConnectorSyncEventPayload): Promise<void>;
+    emitSyncEvent(event: ConnectorSyncEventPayload): void;
 };
 export type OrchestrateSyncParams = {
     connectorName: string;
@@ -33,6 +33,16 @@ export type OrchestrateSyncParams = {
      * imports upsert by unique key).
      */
     inFlight?: Set<string>;
+    /**
+     * Signal that this sync bailed because the provider credential is absent, so a
+     * consumer can prompt (re)authorization. Additive to the sync `error` event —
+     * not a replacement. Fired only for a missing credential, never for an absent
+     * server provider.
+     */
+    emitAuthRequired?: (params: {
+        provider: string;
+        ownerDID: string;
+    }) => void;
 };
 export type OrchestrateSyncResult = {
     status: 'started' | 'already_syncing' | 'error';

package/lib/sync/orchestrate.js

@@ -56,6 +56,12 @@ export async function orchestrateSync(params) {
         const credential = providerName ? await credentialProvider.get(providerName, ownerDID) : null;
         if (providerName != null && credential == null) {
             release();
+            // Additive to the error event below: the sync stream still sees the failure,
+            // and a lifecycle consumer additionally learns (re)authorization is needed.
+            params.emitAuthRequired?.({
+                provider: providerName,
+                ownerDID
+            });
             await emitError(`no credential for provider "${providerName}"`);
             return {
                 status: 'error'

package/lib/sync/workflow.d.ts

@@ -33,6 +33,7 @@ export type ConnectorSyncWorkflowDefinition = {
         name: string;
     };
     handlers: Record<string, ConnectorSyncHandler>;
+    managed: true;
 };
 export type ConnectorSyncWorkflowParams = {
     registry: ConnectorRegistry;
@@ -43,6 +44,16 @@ export type ConnectorSyncWorkflowParams = {
     mutateDocuments?: MutateDocuments;
     boundary?: SyncBoundary;
     logger: Logger;
+    /**
+     * Signal that a sync cannot proceed because the provider credential is absent,
+     * so a consumer can prompt (re)authorization. Fired only for a genuinely
+     * missing credential — never for an absent server provider, which is an
+     * ordinary offline/configuration outcome.
+     */
+    emitAuthRequired?: (params: {
+        provider: string;
+        ownerDID: string;
+    }) => void;
 };
 /**
  * Build the `connector-sync` workflow definition. One sync pass is a self-looping

package/lib/sync/workflow.js

@@ -14,7 +14,7 @@ import { MAX_LOGGED_ERRORS } from './processor.js';
  * definitions (two "boots" over one DB) do not share iterators — which is what
  * makes crash-recovery re-open the provider from the checkpoint.
  */ export function createConnectorSyncWorkflow(params) {
-    const { registry, credentialProvider, stateStore, syncEventEmitter, stores, mutateDocuments, logger } = params;
+    const { registry, credentialProvider, stateStore, syncEventEmitter, stores, mutateDocuments, logger, emitAuthRequired } = params;
     const sessions = new Map();
     const sessionKey = (state)=>`${state.connectorName}:${state.ownerDID}`;
     const effectiveBoundary = params.boundary ?? {
@@ -64,6 +64,15 @@ import { MAX_LOGGED_ERRORS } from './processor.js';
                     lastSyncedAt: new Date().toISOString(),
                     failedSample: []
                 };
+                // Only a genuinely absent credential asks for (re)authorization; an absent
+                // server provider stays a silent configuration outcome. Both still end
+                // offline (the event is additive, not a change to the offline outcome).
+                if (providerName != null && credential == null) {
+                    emitAuthRequired?.({
+                        provider: providerName,
+                        ownerDID
+                    });
+                }
                 return {
                     status: 'end',
                     state: offlineState,
@@ -126,6 +135,20 @@ import { MAX_LOGGED_ERRORS } from './processor.js';
                 }
                 const providerName = connector.auth.provider !== 'device' ? connector.auth.provider : null;
                 const credential = providerName ? await credentialProvider.get(providerName, state.ownerDID) : null;
+                // A crash-recovered batch whose credential has since been removed cannot
+                // resume: signal (re)authorization and end offline rather than opening the
+                // provider with an empty credential (which would fail mid-sync ⇒ error).
+                if (providerName != null && credential == null) {
+                    emitAuthRequired?.({
+                        provider: providerName,
+                        ownerDID: state.ownerDID
+                    });
+                    return {
+                        status: 'end',
+                        state,
+                        outcome: 'offline'
+                    };
+                }
                 if (connector.serverProvider == null) {
                     throw new Error(`Connector "${state.connectorName}" has no server provider`);
                 }
@@ -258,7 +281,8 @@ import { MAX_LOGGED_ERRORS } from './processor.js';
                 start,
                 batch,
                 finalize
-            }
+            },
+            managed: true
         }
     };
 }

package/lib/write-grants.d.ts

@@ -1,8 +1,11 @@
-import type { CredentialProvider } from '@kubun/credential-types';
+import type { Credential, CredentialProvider } from '@kubun/credential-types';
 import { HLC } from '@kubun/hlc';
 import { getDelegationStore } from '@kubun/store-delegation';
 import type { ConnectorRegistry } from './registry.js';
 import type { ConnectorWriteGrant } from './schema.js';
+type CredentialFacade = CredentialProvider & {
+    peek?(providerName: string, ownerDID: string): Promise<Credential | null>;
+};
 export type WriteGrantContextParams = {
     registry: ConnectorRegistry;
     /** The server identity a viewer delegates its write authority to (`aud`). */
@@ -10,8 +13,12 @@ export type WriteGrantContextParams = {
     /** The calling viewer (raw, unnormalized) — the grantor of every cap. */
     viewerDID: string;
     stores: Parameters<typeof getDelegationStore>[0];
-    credentialProvider: CredentialProvider;
+    credentialProvider: CredentialFacade;
     hlc: HLC;
+    onCredentialRemoved?: (params: {
+        provider: string;
+        ownerDID: string;
+    }) => void;
 };
 export type WriteGrantContext = {
     grantWriteCapability(args: {
@@ -33,3 +40,4 @@ export type WriteGrantContext = {
  * stored `resource` string handled here is only the revoke/list selector.
  */
 export declare function createWriteGrantContext(params: WriteGrantContextParams): WriteGrantContext;
+export {};

package/lib/write-grants.js

@@ -240,8 +240,17 @@ async function revokeCapsSubsetOf(delegationStore, grantor, audience, allowed) {
             }
             const delegationStore = await getDelegationStore(stores);
             const removed = await revokeCapsSubsetOf(delegationStore, viewerDID, audienceDID, providerURNs);
-            const credentialExisted = await credentialProvider.get(provider, viewerDID) != null;
+            // Test existence with the non-refreshing peek (falling back to `get` only
+            // when a caller supplies no peek) so disconnecting an expiring credential
+            // does not trigger a transparent refresh right before the delete.
+            const credentialExisted = (credentialProvider.peek != null ? await credentialProvider.peek(provider, viewerDID) : await credentialProvider.get(provider, viewerDID)) != null;
             await credentialProvider.delete(provider, viewerDID);
+            if (credentialExisted) {
+                params.onCredentialRemoved?.({
+                    provider,
+                    ownerDID: viewerDID
+                });
+            }
             return removed > 0 || credentialExisted;
         },
         connectorWriteGrants: async ()=>{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/plugin-connector",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "license": "see LICENSE.md",
   "sideEffects": false,
   "type": "module",
@@ -18,7 +18,7 @@
     "@kokuin/jwe": "^0.1.0",
     "@kokuin/token": "^0.5.0",
     "@kubun/connector": "^0.14.0",
-    "@kubun/credential": "^0.14.1",
+    "@kubun/credential": "^0.14.2",
     "@kubun/credential-types": "^0.14.0",
     "@kubun/db": "^0.14.0",
     "@kubun/engine": "^0.14.1",
@@ -27,7 +27,7 @@
     "@kubun/id": "^0.14.0",
     "@kubun/logger": "^0.14.0",
     "@kubun/plugin-blob-api": "^0.14.0",
-    "@kubun/plugin-workflow-api": "^0.14.0",
+    "@kubun/plugin-workflow-api": "^0.14.1",
     "@kubun/protocol": "^0.14.1",
     "@kubun/service-credential-api": "^0.14.0",
     "@kubun/store-connector": "^0.14.0",
@@ -56,11 +56,11 @@
     "@kubun/plugin-credential": "^0.14.0",
     "@kubun/plugin-service-client": "^0.14.0",
     "@kubun/plugin-service-server": "^0.14.0",
-    "@kubun/plugin-workflow": "^0.14.0",
+    "@kubun/plugin-workflow": "^0.14.1",
     "@kubun/service-controller-log-api": "^0.14.0",
     "@kubun/store-blob": "^0.14.0",
     "@kubun/store-controller": "^0.14.0",
-    "@kubun/store-workflow": "^0.14.0",
+    "@kubun/store-workflow": "^0.14.1",
     "@kubun/test-utils": "^0.13.0",
     "@testcontainers/postgresql": "^12.1.0",
     "get-port": "^7.2.0"