@kubun/plugin-connector 0.12.1 → 0.13.0

package/lib/action.d.ts

@@ -1,4 +1,4 @@
-import type { CredentialProvider, EntityRecord } from '@kubun/connector';
+import type { CredentialProvider, EntityRecord, WriteAttachment } from '@kubun/connector';
 import type { StoreProvider } from '@kubun/db';
 import type { Logger } from '@kubun/logger';
 import type { ConnectorRegistry } from './registry.js';
@@ -27,5 +27,11 @@ export type ExecuteActionDeps = {
      * rather than opening a nested transaction.
      */
     writeDocument: SignedDocumentWriter;
+    /**
+     * Writes attachment bytes to the blob store; absent when no blob plugin is
+     * installed. Passed through to the connector's action handler so an action can
+     * import binary content (e.g. a Gmail attachment) on demand.
+     */
+    writeAttachment?: WriteAttachment;
 };
 export declare function executeAction(params: ExecuteActionParams, deps: ExecuteActionDeps): Promise<ExecuteActionResult>;

package/lib/action.js

@@ -2,7 +2,7 @@ import { DocumentID, DocumentModelID } from '@kubun/id';
 import { getGraphStore } from '@kubun/store-graph';
 import { EntityProcessor } from './sync/processor.js';
 export async function executeAction(params, deps) {
-    const { stores, registry, credentialProvider, ownerDID, logger, writeDocument } = deps;
+    const { stores, registry, credentialProvider, ownerDID, logger, writeDocument, writeAttachment } = deps;
     const { connector: connectorName, action: actionName, model: modelName, input, sourceID } = params;
     const connector = registry.get(connectorName);
     if (connector == null) {
@@ -49,21 +49,24 @@ export async function executeAction(params, deps) {
     }
     // For updates, merge contextual fields from existing document (e.g., calendarID)
     let mergedInput = input;
+    let existingData;
     if (actionName === 'update' && sourceID != null) {
         const uniqueBytes = new TextEncoder().encode(`${connectorName}:${sourceID}`);
         const docID = DocumentID.create(DocumentModelID.fromString(modelID), ownerDID, uniqueBytes);
         const graphStore = await getGraphStore(stores);
         const existingDoc = await graphStore.getDocument(docID);
         if (existingDoc?.data != null) {
+            existingData = existingDoc.data;
             mergedInput = {
-                ...existingDoc.data,
+                ...existingData,
                 ...input
             };
         }
     }
     // Dispatch to provider's action handler
     const handler = connector.actionHandler({
-        credential
+        credential,
+        writeAttachment
     });
     let entity;
     if (actionName === 'create') {
@@ -72,7 +75,7 @@ export async function executeAction(params, deps) {
         if (sourceID == null) {
             throw new Error('sourceID is required for update actions');
         }
-        entity = await handler.update(modelName, sourceID, mergedInput);
+        entity = await handler.update(modelName, sourceID, mergedInput, existingData);
     } else {
         throw new Error(`Unsupported action: ${actionName}`);
     }

package/lib/api.d.ts

@@ -1,5 +1,7 @@
+import { type MethodRegistry } from '@kokuin/token';
+import { type CredentialManager } from '@kubun/credential';
 import type { StoreProvider } from '@kubun/db';
-import type { Cipher } from '@kubun/engine';
+import type { Logger } from '@kubun/logger';
 import { type PendingAuthRecord } from '@kubun/store-connector';
 export type SyncStateData = {
     connectorName: string;
@@ -18,21 +20,70 @@ export type SetSyncStateParams = {
     status: string;
     error?: string | null;
 };
+/**
+ * Every `ownerDID` here is normalized before it reaches the store.
+ *
+ * The viewer DID arrives as a mutation's `iss`, which for `did:peer:4` is the
+ * long form on first contact with an audience and the short form afterwards. The
+ * two `owner_did` columns are equality keys, so an un-normalized one files the
+ * same account under two rows: a credential invisible under one spelling and
+ * un-revokable under the other, and a sync lease held twice at once.
+ *
+ * `ownerWrappableDID` is NOT normalized — see {@link createConnectorAPI}.
+ */
 export type ConnectorAPI = {
     getSyncState: (connectorName: string, ownerDID: string) => Promise<SyncStateData | null>;
     setSyncState: (connectorName: string, ownerDID: string, state: SetSyncStateParams) => Promise<SyncStateData>;
     deleteSyncState: (connectorName: string, ownerDID: string) => Promise<void>;
     listSyncStates: (connectorName: string) => Promise<Array<SyncStateData>>;
-    claimSync: (connectorName: string, ownerDID: string, leaseMs: number) => Promise<boolean>;
-    renewSync: (connectorName: string, ownerDID: string, leaseMs: number) => Promise<void>;
     getCredential: (providerName: string, ownerDID: string) => Promise<string | null>;
+    getCredentialProvenance: (providerName: string, ownerDID: string) => Promise<{
+        updatedAt: string | null;
+        writerDID: string | null;
+    } | null>;
+    /**
+     * Re-encrypt an existing credential. Refuses when none exists, because
+     * creating one is a different decision — see `createCredential`.
+     */
     setCredential: (providerName: string, ownerDID: string, credential: string) => Promise<void>;
+    /**
+     * Mint the key, its two wrappings and the entry, and record the pointer.
+     *
+     * Split from `setCredential` so the headless refresh path cannot mint a key.
+     * A minted key fixes who will ever be able to read it, and a refresh running
+     * with no owner in hand would mint one wrapped to the server alone — locking
+     * the account owner out of their own credential with nothing failing.
+     */
+    createCredential: (params: {
+        providerName: string;
+        ownerDID: string;
+        ownerWrappableDID: string;
+        controllerWrappableDID?: string;
+        credential: string;
+    }) => Promise<void>;
     deleteCredential: (providerName: string, ownerDID: string) => Promise<void>;
     createPendingAuth: (record: PendingAuthRecord) => Promise<void>;
     consumePendingAuth: (state: string) => Promise<PendingAuthRecord | null>;
     deleteExpiredPendingAuth: (cutoffMs: number) => Promise<void>;
 };
-export declare function createConnectorAPI(params: {
+export type CreateConnectorAPIParams = {
     stores: StoreProvider;
-    cipher: Cipher | undefined;
-}): ConnectorAPI;
+    logger: Logger;
+    /**
+     * Takes the `StoreProvider` rather than a manager, because during a mutation
+     * that provider is the transaction and a manager built over the base one
+     * would read outside it.
+     */
+    getCredentialManager: (stores: StoreProvider) => Promise<CredentialManager>;
+    /** The engine's own DID, in a form that can be encrypted to. */
+    serverWrappableDID: string;
+    /**
+     * Resolvers for wrapping recipients that carry no key material of their own
+     * (`did:kokuin:`), scoped to the request's transaction provider so a resolve
+     * reads the mutation's tx, never a second connection. A self-contained
+     * recipient resolves with an empty registry, so callers with no controller
+     * recipient in play still pass `() => []`.
+     */
+    getControllerMethods: (stores: StoreProvider) => MethodRegistry;
+};
+export declare function createConnectorAPI(params: CreateConnectorAPIParams): ConnectorAPI;

package/lib/api.js

@@ -1,16 +1,19 @@
+import { normalizeDID } from '@kokuin/token';
+import { CredentialSupersededBranch } from '@kubun/credential';
 import { getConnectorStore } from '@kubun/store-connector';
-// ---- Factory ----
+import { fromUTF, toUTF } from '@sozai/codec';
 export function createConnectorAPI(params) {
     const getStore = ()=>getConnectorStore(params.stores);
-    const cipher = params.cipher;
+    const getCredentials = ()=>params.getCredentialManager(params.stores);
     return {
         async getSyncState (connectorName, ownerDID) {
             const store = await getStore();
-            const state = await store.getSyncState(connectorName, ownerDID);
+            const owner = normalizeDID(ownerDID);
+            const state = await store.getSyncState(connectorName, owner);
             if (state == null) return null;
             return {
                 connectorName,
-                ownerDID,
+                ownerDID: owner,
                 checkpoint: state.checkpoint != null ? JSON.stringify(state.checkpoint) : null,
                 lastSyncedAt: state.lastSyncedAt,
                 entityCount: state.entityCount,
@@ -21,23 +24,24 @@ export function createConnectorAPI(params) {
         },
         async setSyncState (connectorName, ownerDID, state) {
             const store = await getStore();
+            const owner = normalizeDID(ownerDID);
             const lastSyncedAt = state.lastSyncedAt ?? new Date().toISOString();
             const entityCount = state.entityCount ?? 0;
             const checkpoint = state.checkpoint ?? null;
-            await store.setSyncState(connectorName, ownerDID, {
+            await store.setSyncState(connectorName, owner, {
                 checkpoint: checkpoint != null ? JSON.parse(checkpoint) : null,
                 lastSyncedAt,
                 entityCount,
                 status: state.status,
                 error: state.error ?? undefined
             });
-            const saved = await store.getSyncState(connectorName, ownerDID);
+            const saved = await store.getSyncState(connectorName, owner);
             if (saved == null) {
                 throw new Error('Failed to set sync state');
             }
             return {
                 connectorName,
-                ownerDID,
+                ownerDID: owner,
                 checkpoint: saved.checkpoint != null ? JSON.stringify(saved.checkpoint) : null,
                 lastSyncedAt: saved.lastSyncedAt,
                 entityCount: saved.entityCount,
@@ -48,7 +52,7 @@ export function createConnectorAPI(params) {
         },
         async deleteSyncState (connectorName, ownerDID) {
             const store = await getStore();
-            await store.deleteSyncState(connectorName, ownerDID);
+            await store.deleteSyncState(connectorName, normalizeDID(ownerDID));
         },
         async listSyncStates (connectorName) {
             const store = await getStore();
@@ -64,33 +68,115 @@ export function createConnectorAPI(params) {
                     leaseExpiresAt: entry.leaseExpiresAt ?? null
                 }));
         },
-        async claimSync (connectorName, ownerDID, leaseMs) {
+        async getCredential (providerName, ownerDID) {
             const store = await getStore();
-            return store.claimSync(connectorName, ownerDID, leaseMs);
+            const entryID = await store.getCredentialEntryID(providerName, normalizeDID(ownerDID));
+            if (entryID == null) return null;
+            try {
+                return toUTF(await (await getCredentials()).readEntry(entryID));
+            } catch (error) {
+                if (error instanceof CredentialSupersededBranch) {
+                    params.logger.warn('Credential entry {entryID} for provider {providerName} belongs to a superseded branch', {
+                        providerName,
+                        entryID
+                    });
+                    return null;
+                }
+                throw error;
+            }
         },
-        async renewSync (connectorName, ownerDID, leaseMs) {
+        async getCredentialProvenance (providerName, ownerDID) {
+            // Reflects the current pointer, not the winning branch — no superseded-branch guard
+            // (it never decrypts). Callers must gate on getCredential() != null so a loser-branch
+            // pointer's provenance is never surfaced.
             const store = await getStore();
-            await store.renewSync(connectorName, ownerDID, leaseMs);
+            const entryID = await store.getCredentialEntryID(providerName, normalizeDID(ownerDID));
+            if (entryID == null) return null;
+            return (await getCredentials()).getEntryProvenance(entryID);
         },
-        async getCredential (providerName, ownerDID) {
+        async setCredential (providerName, ownerDID, credential) {
             const store = await getStore();
-            const stored = await store.getCredential(providerName, ownerDID);
-            if (stored == null) return null;
-            if (cipher == null) {
-                throw new Error('Cannot decrypt connector credential: no at-rest cipher available');
+            const entryID = await store.getCredentialEntryID(providerName, normalizeDID(ownerDID));
+            if (entryID == null) {
+                throw new Error(`No connector credential to update for provider "${providerName}"; create it through the authorization flow`);
             }
-            return cipher.decrypt(stored);
+            // Opens the key through the server's own wrapping and rewrites the entry
+            // under it. No key is minted and no wrapping is touched, so a refresh
+            // cannot change who can read the credential.
+            await (await getCredentials()).updateEntry(entryID, fromUTF(credential));
         },
-        async setCredential (providerName, ownerDID, credential) {
-            if (cipher == null) {
-                throw new Error('Cannot persist connector credential: no at-rest cipher available');
-            }
+        async createCredential (input) {
+            const { providerName, ownerDID, ownerWrappableDID, credential } = input;
             const store = await getStore();
-            await store.setCredential(providerName, ownerDID, cipher.encrypt(credential));
+            const credentials = await getCredentials();
+            // Wrapping to a DID needs only that DID's published key, so an engine that
+            // cannot decrypt would mint this key perfectly and then be unable to read
+            // it — a failure that surfaces at the first headless sync, far from here.
+            // This is where `cipher == null` used to fail closed, and it still does.
+            if (!credentials.availableFactors().includes('did')) {
+                throw new Error(`Cannot create a connector credential for "${providerName}": this engine's identity cannot decrypt, so it could never read back what it stored`);
+            }
+            // Two wrappings from the first write, not one plus a later grant: the
+            // server has to read this to run sync, and the owner has to be able to
+            // rotate and revoke it. Owner is authority, a different question from who
+            // can decrypt: when a controller is supplied it is the owner, so a device
+            // revoke goes through the controller's capability chain rather than the
+            // device self-authorizing; absent one the device owns its own key.
+            //
+            // The two spellings below are deliberately different questions about the
+            // same identity, and NOT interchangeable: `owner_did` is an equality key
+            // and so is normalized, while a recipient is encrypted to and must keep
+            // its wrappable form. Normalizing a `did:peer:4` recipient hands the short
+            // form to `deriveSharedSecret`, which resolves no document and no
+            // agreement key — do not fold these together.
+            const wrappings = [
+                [
+                    {
+                        kind: 'did',
+                        recipientDID: ownerWrappableDID
+                    }
+                ],
+                [
+                    {
+                        kind: 'did',
+                        recipientDID: params.serverWrappableDID
+                    }
+                ]
+            ];
+            // A recovery recipient (e.g. a controller / seed-holder), so the credential
+            // survives device loss. Opt-in: absent when the caller supplied none. Kept
+            // in its wrappable form for the same reason as the two above — it is
+            // encrypted to, not compared against.
+            if (input.controllerWrappableDID != null) {
+                wrappings.push([
+                    {
+                        kind: 'did',
+                        recipientDID: input.controllerWrappableDID
+                    }
+                ]);
+            }
+            // The controller owns the key when supplied (its canonical DID equals the
+            // normalized wrappable form); the account pointer below stays keyed on the
+            // device — ownership and account scoping are separate concerns.
+            const keyOwnerDID = input.controllerWrappableDID != null ? normalizeDID(input.controllerWrappableDID) : normalizeDID(ownerDID);
+            const keyID = await credentials.createKey({
+                ownerDID: keyOwnerDID,
+                wrappings,
+                methods: params.getControllerMethods(params.stores)
+            });
+            const entryID = await credentials.putEntry(keyID, fromUTF(credential));
+            await store.setCredentialEntryID(providerName, normalizeDID(ownerDID), entryID);
         },
         async deleteCredential (providerName, ownerDID) {
             const store = await getStore();
-            await store.deleteCredential(providerName, ownerDID);
+            const owner = normalizeDID(ownerDID);
+            const entryID = await store.getCredentialEntryID(providerName, owner);
+            await store.deleteCredentialEntryID(providerName, owner);
+            if (entryID != null) {
+                // The pointer and the entry go together. Leaving the entry would keep
+                // the token readable by anyone who kept its id after a disconnect.
+                await (await getCredentials()).deleteEntry(entryID);
+            }
         },
         async createPendingAuth (record) {
             const store = await getStore();

package/lib/credential.d.ts

@@ -11,6 +11,12 @@ export declare class DBCredentialProvider implements CredentialProvider {
     #private;
     constructor(params: DBCredentialProviderParams);
     get(providerName: string, ownerDID: string): Promise<Credential | null>;
-    set(providerName: string, ownerDID: string, credential: Credential): Promise<void>;
+    set(params: {
+        providerName: string;
+        ownerDID: string;
+        credential: Credential;
+        ownerWrappableDID?: string;
+        controllerWrappableDID?: string;
+    }): Promise<void>;
     delete(providerName: string, ownerDID: string): Promise<void>;
 }

package/lib/credential.js

@@ -60,8 +60,26 @@ export class DBCredentialProvider {
         }
         return credential;
     }
-    async set(providerName, ownerDID, credential) {
-        await this.#api.setCredential(providerName, ownerDID, serializeCredential(credential));
+    async set(params) {
+        const { providerName, ownerDID, credential, ownerWrappableDID, controllerWrappableDID } = params;
+        const serialized = serializeCredential(credential);
+        // Update when one exists, mint only when it does not. Dispatching on
+        // presence rather than on the caller keeps the refresh path unable to mint
+        // even when it does hold a wrappable DID.
+        if (await this.#api.getCredential(providerName, ownerDID) != null) {
+            await this.#api.setCredential(providerName, ownerDID, serialized);
+            return;
+        }
+        if (ownerWrappableDID == null) {
+            throw new Error(`Cannot create a connector credential for "${providerName}" without the owner's wrappable DID`);
+        }
+        await this.#api.createCredential({
+            providerName,
+            ownerDID,
+            ownerWrappableDID,
+            controllerWrappableDID,
+            credential: serialized
+        });
     }
     async delete(providerName, ownerDID) {
         await this.#api.deleteCredential(providerName, ownerDID);
@@ -98,7 +116,11 @@ export class DBCredentialProvider {
                 accountLabel: credential.accountLabel,
                 metadata: credential.metadata
             };
-            await this.set(providerName, ownerDID, refreshed);
+            await this.set({
+                providerName,
+                ownerDID,
+                credential: refreshed
+            });
             return refreshed;
         } catch  {
             return null;

package/lib/index.d.ts

@@ -12,6 +12,7 @@ export { type RunSyncParams, SyncEngine, type SyncEngineParams } from './sync/en
 export { type OrchestrateSyncParams, type OrchestrateSyncResult, orchestrateSync, type SyncEventEmitter, } from './sync/orchestrate.js';
 export { EntityProcessor, type EntityProcessorParams, type MutateDocuments, type ProcessBatchResult, type SignedDocumentWriter, } from './sync/processor.js';
 export { DBSyncStateStore } from './sync/state.js';
+export { CONNECTOR_SYNC_CONCURRENCY, CONNECTOR_SYNC_WORKFLOW, type ConnectorSyncWorkflowDefinition, type ConnectorSyncWorkflowParams, createConnectorSyncWorkflow, } from './sync/workflow.js';
 export type { ConnectorAPI, SetSyncStateParams, SyncStateData };
 export { DBCredentialProvider, type DBCredentialProviderParams };
 export type ConnectorPluginOptions = {
@@ -19,9 +20,6 @@ export type ConnectorPluginOptions = {
     providers?: Array<OAuthProviderDefinition>;
     defaults?: {
         boundary?: SyncBoundary;
-        pollingInterval?: string;
     };
-    /** Override the sync-lease TTL in milliseconds (defaults to 5 minutes). */
-    syncLeaseTTL?: number;
 };
 export declare function createConnectorPlugin(options: ConnectorPluginOptions): (params: PluginFactoryParams) => KubunPlugin;