@kubun/plugin-connector 0.13.1 → 0.14.1

package/lib/action.d.ts

@@ -1,4 +1,5 @@
-import type { CredentialProvider, EntityRecord, WriteAttachment } from '@kubun/connector';
+import type { EntityRecord, WriteAttachment } from '@kubun/connector';
+import type { CredentialProvider } from '@kubun/credential-types';
 import type { StoreProvider } from '@kubun/db';
 import type { Logger } from '@kubun/logger';
 import type { ConnectorRegistry } from './registry.js';

package/lib/api.d.ts

@@ -1,8 +1,8 @@
-import { type MethodRegistry } from '@kokuin/token';
-import { type CredentialManager } from '@kubun/credential';
 import type { StoreProvider } from '@kubun/db';
 import type { Logger } from '@kubun/logger';
 import { type PendingAuthRecord } from '@kubun/store-connector';
+export type { CreateCredentialAPIParams, CredentialAPI } from '@kubun/credential';
+export { createCredentialAPI } from '@kubun/credential';
 export type SyncStateData = {
     connectorName: string;
     ownerDID: string;
@@ -28,70 +28,18 @@ export type SetSyncStateParams = {
  * 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>>;
-    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>;
-    /**
-     * The controller resolvers for this API's (request-scoped) transaction
-     * provider — the exact `methods` the credential mint passes to `createKey`.
-     * Exposed so the OAuth pre-flight can ask `canWrapTo` with the same resolver
-     * the mint uses, rather than failing closed on a `did:kokuin:` owner whose
-     * agreement key is resolvable only through the controller resolver.
-     */
-    getControllerMethods: () => MethodRegistry;
 };
 export type CreateConnectorAPIParams = {
     stores: StoreProvider;
     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,10 +1,8 @@
 import { normalizeDID } from '@kokuin/token';
-import { CredentialSupersededBranch } from '@kubun/credential';
 import { getConnectorStore } from '@kubun/store-connector';
-import { fromUTF, toUTF } from '@sozai/codec';
+export { createCredentialAPI } from '@kubun/credential';
 export function createConnectorAPI(params) {
     const getStore = ()=>getConnectorStore(params.stores);
-    const getCredentials = ()=>params.getCredentialManager(params.stores);
     return {
         async getSyncState (connectorName, ownerDID) {
             const store = await getStore();
@@ -68,116 +66,6 @@ export function createConnectorAPI(params) {
                     leaseExpiresAt: entry.leaseExpiresAt ?? null
                 }));
         },
-        async getCredential (providerName, ownerDID) {
-            const store = await getStore();
-            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 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();
-            const entryID = await store.getCredentialEntryID(providerName, normalizeDID(ownerDID));
-            if (entryID == null) return null;
-            return (await getCredentials()).getEntryProvenance(entryID);
-        },
-        async setCredential (providerName, ownerDID, credential) {
-            const store = await getStore();
-            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`);
-            }
-            // 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 createCredential (input) {
-            const { providerName, ownerDID, ownerWrappableDID, credential } = input;
-            const store = await getStore();
-            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();
-            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();
             await store.createPendingAuth(record);
@@ -189,9 +77,6 @@ export function createConnectorAPI(params) {
         async deleteExpiredPendingAuth (cutoffMs) {
             const store = await getStore();
             await store.deleteExpiredPendingAuth(cutoffMs);
-        },
-        getControllerMethods () {
-            return params.getControllerMethods(params.stores);
         }
     };
 }

package/lib/credential.d.ts

@@ -1,22 +1,2 @@
-import type { Credential, CredentialProvider, OAuthProviderDefinition } from '@kubun/connector';
-import type { Runtime } from '@sozai/runtime';
-import type { ConnectorAPI } from './api.js';
-export type DBCredentialProviderParams = {
-    api: ConnectorAPI;
-    runtime: Runtime;
-    providers: Array<OAuthProviderDefinition>;
-    bufferSeconds?: number;
-};
-export declare class DBCredentialProvider implements CredentialProvider {
-    #private;
-    constructor(params: DBCredentialProviderParams);
-    get(providerName: string, ownerDID: string): Promise<Credential | null>;
-    set(params: {
-        providerName: string;
-        ownerDID: string;
-        credential: Credential;
-        ownerWrappableDID?: string;
-        controllerWrappableDID?: string;
-    }): Promise<void>;
-    delete(providerName: string, ownerDID: string): Promise<void>;
-}
+export type { DBCredentialProviderParams } from '@kubun/credential';
+export { DBCredentialProvider } from '@kubun/credential';

package/lib/credential.js

@@ -1,129 +1,4 @@
-const DEFAULT_BUFFER_SECONDS = 300;
-function serializeCredential(credential) {
-    const serialized = {
-        accessToken: credential.accessToken,
-        scopes: credential.scopes
-    };
-    if (credential.refreshToken != null) {
-        serialized.refreshToken = credential.refreshToken;
-    }
-    if (credential.expiresAt != null) {
-        serialized.expiresAt = credential.expiresAt.toISOString();
-    }
-    if (credential.accountLabel != null) {
-        serialized.accountLabel = credential.accountLabel;
-    }
-    if (credential.metadata != null) {
-        serialized.metadata = credential.metadata;
-    }
-    return JSON.stringify(serialized);
-}
-function deserializeCredential(raw) {
-    // ParseJSONResultsPlugin may have already parsed the JSON string
-    const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
-    const credential = {
-        accessToken: parsed.accessToken,
-        scopes: parsed.scopes
-    };
-    if (parsed.refreshToken != null) {
-        credential.refreshToken = parsed.refreshToken;
-    }
-    if (parsed.expiresAt != null) {
-        credential.expiresAt = new Date(parsed.expiresAt);
-    }
-    if (parsed.accountLabel != null) {
-        credential.accountLabel = parsed.accountLabel;
-    }
-    if (parsed.metadata != null) {
-        credential.metadata = parsed.metadata;
-    }
-    return credential;
-}
-export class DBCredentialProvider {
-    #api;
-    #runtime;
-    #providers;
-    #bufferMs;
-    constructor(params){
-        this.#api = params.api;
-        this.#runtime = params.runtime;
-        this.#providers = params.providers;
-        this.#bufferMs = (params.bufferSeconds ?? DEFAULT_BUFFER_SECONDS) * 1000;
-    }
-    async get(providerName, ownerDID) {
-        const raw = await this.#api.getCredential(providerName, ownerDID);
-        if (raw == null) return null;
-        const credential = deserializeCredential(raw);
-        if (this.#isExpiringSoon(credential) && credential.refreshToken != null) {
-            const refreshed = await this.#refresh(providerName, ownerDID, credential, credential.refreshToken);
-            return refreshed ?? credential;
-        }
-        return 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);
-    }
-    #isExpiringSoon(credential) {
-        if (credential.expiresAt == null) return false;
-        return credential.expiresAt.getTime() - Date.now() < this.#bufferMs;
-    }
-    async #refresh(providerName, ownerDID, credential, refreshToken) {
-        const provider = this.#providers.find((p)=>p.name === providerName);
-        if (provider == null || provider.clientID == null || provider.clientSecret == null) {
-            return null;
-        }
-        try {
-            const response = await this.#runtime.fetch(provider.tokenEndpoint, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/x-www-form-urlencoded'
-                },
-                body: new URLSearchParams({
-                    grant_type: 'refresh_token',
-                    refresh_token: refreshToken,
-                    client_id: provider.clientID,
-                    client_secret: provider.clientSecret
-                })
-            });
-            if (!response.ok) return null;
-            const tokenData = await response.json();
-            const refreshed = {
-                accessToken: tokenData.access_token,
-                refreshToken: tokenData.refresh_token ?? credential.refreshToken,
-                expiresAt: tokenData.expires_in != null ? new Date(Date.now() + tokenData.expires_in * 1000) : undefined,
-                scopes: tokenData.scope?.split(' ') ?? credential.scopes,
-                accountLabel: credential.accountLabel,
-                metadata: credential.metadata
-            };
-            await this.set({
-                providerName,
-                ownerDID,
-                credential: refreshed
-            });
-            return refreshed;
-        } catch  {
-            return null;
-        }
-    }
-}
+// The DB-backed credential provider moved to @kubun/credential; re-exported here
+// so existing importers of `../src/credential.js` and the package index keep
+// resolving it.
+export { DBCredentialProvider } from '@kubun/credential';

package/lib/index.d.ts

@@ -1,6 +1,8 @@
-import type { ConnectorDefinition, OAuthProviderDefinition, SyncBoundary } from '@kubun/connector';
+import type { ConnectorDefinition, SyncBoundary } from '@kubun/connector';
+import type { OAuthProviderDefinition } from '@kubun/credential-types';
 import type { KubunPlugin, PluginFactoryParams } from '@kubun/engine';
-import { type ConnectorAPI, type SetSyncStateParams, type SyncStateData } from './api.js';
+import type { AdaptivePolicy } from '@kubun/plugin-workflow-api';
+import { type ConnectorAPI, type CredentialAPI, type SetSyncStateParams, type SyncStateData } from './api.js';
 import { DBCredentialProvider, type DBCredentialProviderParams } from './credential.js';
 export { type ExecuteActionDeps, type ExecuteActionParams, type ExecuteActionResult, executeAction, } from './action.js';
 export { type ConnectorActivatedEvent, type ConnectorDeactivatedEvent, ConnectorManager, type ConnectorManagerEvents, type ConnectorManagerParams, } from './manager.js';
@@ -13,13 +15,14 @@ export { type OrchestrateSyncParams, type OrchestrateSyncResult, orchestrateSync
 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 type { ConnectorAPI, CredentialAPI, SetSyncStateParams, SyncStateData };
 export { DBCredentialProvider, type DBCredentialProviderParams };
 export type ConnectorPluginOptions = {
     connectors: Array<ConnectorDefinition>;
     providers?: Array<OAuthProviderDefinition>;
     defaults?: {
         boundary?: SyncBoundary;
+        periodicSyncPolicy?: AdaptivePolicy;
     };
 };
 export declare function createConnectorPlugin(options: ConnectorPluginOptions): (params: PluginFactoryParams) => KubunPlugin;