@vibesdotdev/integrations 0.0.0-stage → 1.0.0-rc.2

package/dist/kinds/integration.kind.d.ts

@@ -0,0 +1,74 @@
+import type { KindContext, RuntimeKindDescriptor } from '@vibesdotdev/kernel/schemas/kind';
+import type { RuntimeDescriptor } from '@vibesdotdev/kernel/schemas/descriptor';
+import type { CredentialCandidates } from '@vibesdotdev/secrets/schemas';
+import { type IntegrationConfig, type IntegrationConnectionSelector, type IntegrationCredentialSource, type IntegrationCredentialWriteMetadata, type IntegrationConfigValue, type IntegrationOAuthAuthorization, type IntegrationOAuthCompletion, type IntegrationOAuthStart, type IntegrationOAuthMetadata, type IntegrationOperationResult, type IntegrationProviderDescriptor, type IntegrationProviderImplementation, type IntegrationProviderResolvedConfiguration } from '../schemas/integration-descriptor.ts';
+/**
+ * Base implementation of the integration/provider kind. Handles credential
+ * resolution, persistent config, OAuth lifecycle for descriptors that
+ * declare an `oauth` block, and operation dispatch.
+ *
+ * Provider packs (e.g. `@vibesdotdev/integrations-quickbooks`) extend this
+ * class to implement declared operations like `'sync'`. The runtime calls
+ * extended classes through plugin loaders registered on the
+ * `integration/provider` kind.
+ */
+export declare class BaseIntegrationProvider implements IntegrationProviderImplementation {
+    readonly descriptor: IntegrationProviderDescriptor;
+    private readonly settingsReader;
+    private readonly store;
+    protected readonly context: KindContext;
+    constructor(descriptor: RuntimeDescriptor, context: KindContext);
+    /** Throw if the descriptor doesn't declare the named operation. */
+    protected requireDeclaredOperation(opId: string): void;
+    /** Provider policy applies to every read before Core resolves metadata or values. */
+    protected credentialSources(): Promise<IntegrationCredentialSource[]>;
+    getConfig(): Promise<IntegrationConfig>;
+    getCredentials(): Promise<Record<string, string>>;
+    getCredential(key: string): Promise<string | undefined>;
+    /** Return metadata references without resolving credential values in provider code. */
+    getCredentialCandidates(key: string): Promise<CredentialCandidates>;
+    private credentialCandidates;
+    /** Provider request configuration contains references; only Secrets reads their values. */
+    getCredentialUseConfiguration(selector?: Readonly<IntegrationConnectionSelector>): Promise<IntegrationProviderResolvedConfiguration>;
+    private loadSelectedConnection;
+    getResolvedConfiguration(selector?: Readonly<IntegrationConnectionSelector>): Promise<IntegrationProviderResolvedConfiguration>;
+    setCredential(key: string, value: string, metadata?: IntegrationCredentialWriteMetadata): Promise<void>;
+    unsetCredential(key: string): Promise<void>;
+    startAuthorization(input: IntegrationOAuthStart): Promise<IntegrationOAuthAuthorization>;
+    completeAuthorization(input: IntegrationOAuthCompletion): Promise<void>;
+    private missingStoreError;
+    invokeOperation<T = unknown>(opId: string, args?: IntegrationConfigValue): Promise<IntegrationOperationResult<T>>;
+    protected requireOAuthMetadata(): IntegrationOAuthMetadata;
+    private requireWriteableSource;
+    private scopedSource;
+    private resolveCredentialSource;
+    private resolveCredentialSet;
+    private readSelectedConnection;
+    private hostCredentialSources;
+    private mergeCredentialReferences;
+    private resolveSelectedConnection;
+    private protectHostEndpointConfiguration;
+    private resolveCredentialReference;
+    /**
+     * Build org-scoped scopeId for credential lookup.
+     * Combines the live request orgId with the descriptor-level scopeId.
+     * Format: {orgId}:{scopeId} when both present, {orgId} when only orgId.
+     */
+    private resolveScopeId;
+    /**
+     * Resolve the CALLING request's org id at call time. The integration
+     * provider instance is value-cached by the runtime for the isolate
+     * lifetime, so a constructor-snapshotted `this.context.orgId` would
+     * freeze to whichever org FIRST resolved the provider — every later
+     * request (any org) would then read and write that first org's
+     * credentials and config (cross-tenant bleed; the Microsoft pack fixed
+     * the same bug in ac19f2688). Read the live request context instead
+     * (`runtime.context('orgId')`, set by hosts via runWithRequestContext),
+     * falling back to the constructor-injected context orgId, then
+     * undefined (system/platform scope).
+     */
+    protected getCurrentOrgId(): Promise<string | undefined>;
+    private getSettingValue;
+}
+export declare const integrationProviderKind: RuntimeKindDescriptor<IntegrationProviderDescriptor, IntegrationProviderImplementation, KindContext>;
+//# sourceMappingURL=integration.kind.d.ts.map

package/dist/kinds/integration.kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.kind.d.ts","sourceRoot":"","sources":["../../src/kinds/integration.kind.ts"],"names":[],"mappings":"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"}

package/dist/kinds/integration.kind.js

@@ -0,0 +1,542 @@
+import { parseIntegrationBoundary, IntegrationContextOrgIdSchema } from "../schemas/boundary.js";
+import { IntegrationCredentialSourceSchema } from "../schemas/integration-descriptor.js";
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { CredentialReferenceSchema } from '@vibesdotdev/kernel/credentials';
+import { applyIntegrationClientId, exchangeIntegrationAuthorizationCode } from "../server/integration-oauth.js";
+import { IntegrationConfigValueSchema, IntegrationConfigSchema, IntegrationOperationInputSchema, IntegrationConnectionSelectorSchema, IntegrationProviderResolvedConfigurationSchema, IntegrationOAuthStartSchema, IntegrationOAuthCompletionSchema, IntegrationCredentialKeySchema, IntegrationCredentialWriteRequestSchema, IntegrationProviderDescriptorSchema } from "../schemas/integration-descriptor.js";
+import { isIntegrationStoreAdapter } from "./integration.store.js";
+import { integrationStoreContextId } from "./integration-store.context.descriptor.js";
+import { createUnavailableSystemSettingsReader, isSystemSettingsReader, systemSettingsReaderContextId } from "../settings/context.js";
+/**
+ * Base implementation of the integration/provider kind. Handles credential
+ * resolution, persistent config, OAuth lifecycle for descriptors that
+ * declare an `oauth` block, and operation dispatch.
+ *
+ * Provider packs (e.g. `@vibesdotdev/integrations-quickbooks`) extend this
+ * class to implement declared operations like `'sync'`. The runtime calls
+ * extended classes through plugin loaders registered on the
+ * `integration/provider` kind.
+ */
+export class BaseIntegrationProvider {
+    descriptor;
+    settingsReader;
+    store;
+    context;
+    constructor(descriptor, context) {
+        this.descriptor = parseIntegrationBoundary(IntegrationProviderDescriptorSchema, descriptor);
+        this.context = context;
+        // Use a structural guard, not a nullish check: the runtime fills an
+        // unwired context slot with an inert placeholder that is truthy but
+        // has no `.get()`, which would defeat `?? createUnavailable...` and
+        // throw "settingsReader.get is not a function" on the first getConfig()
+        // of any descriptor with a configSettingKey. isSystemSettingsReader
+        // only accepts a real injected reader.
+        const injectedSettingsReader = context[systemSettingsReaderContextId];
+        this.settingsReader = isSystemSettingsReader(injectedSettingsReader)
+            ? injectedSettingsReader
+            : createUnavailableSystemSettingsReader(context.runtime);
+        const injectedStore = context[integrationStoreContextId];
+        this.store = isIntegrationStoreAdapter(injectedStore) ? injectedStore : undefined;
+    }
+    /** Throw if the descriptor doesn't declare the named operation. */
+    requireDeclaredOperation(opId) {
+        const declared = (this.descriptor.operations ?? []).find((op) => op.id === opId);
+        if (!declared) {
+            throw new CapabilityError('The integration operation is not declared.', 'INVALID_INPUT', { reason: 'integration-operation-undeclared', retryable: false });
+        }
+    }
+    /** Provider policy applies to every read before Core resolves metadata or values. */
+    async credentialSources() {
+        return this.descriptor.credentials;
+    }
+    async getConfig() {
+        if (this.descriptor.configurationSource === 'host')
+            return { ...this.descriptor.config };
+        let config = { ...this.descriptor.config };
+        const settingKey = this.descriptor.configSettingKey;
+        if (settingKey) {
+            const settingValue = await this.getSettingValue(settingKey);
+            if (settingValue !== undefined) {
+                config = { ...config, ...parseIntegrationBoundary(IntegrationConfigSchema, settingValue) };
+            }
+        }
+        // Scope the persisted-config read to this actor's org using the SAME
+        // selector the credential reads use (scope: 'org' + composite
+        // scopeId derived from the live request orgId). Without this,
+        // getConfig() returns whichever org's `core` row was updated most
+        // recently — a cross-tenant config bleed (org A reads org B's
+        // realmId etc.).
+        const orgId = await this.getCurrentOrgId();
+        const serviceConfig = await this.store?.loadConfig(this.descriptor.id, {
+            scope: 'org',
+            scopeId: this.resolveScopeId(undefined, orgId)
+        });
+        if (serviceConfig) {
+            config = { ...config, ...parseIntegrationBoundary(IntegrationConfigSchema, serviceConfig) };
+        }
+        return config;
+    }
+    async getCredentials() {
+        return (await this.resolveCredentialSet()).credentials;
+    }
+    async getCredential(key) {
+        const credentials = await this.getCredentials();
+        return credentials[key];
+    }
+    /** Return metadata references without resolving credential values in provider code. */
+    async getCredentialCandidates(key) {
+        key = parseIntegrationBoundary(IntegrationCredentialKeySchema, key);
+        const sources = (await this.credentialSources()).filter(source => source.key === key);
+        return this.credentialCandidates(sources);
+    }
+    async credentialCandidates(sources) {
+        const candidates = [];
+        for (const source of sources) {
+            if (source.source === 'setting') {
+                const value = await this.getSettingValue(source.settingKey);
+                if (value !== undefined)
+                    candidates.push(parseIntegrationBoundary(CredentialReferenceSchema, value));
+                continue;
+            }
+            if (source.reference !== undefined && source.scope === undefined) {
+                candidates.push(source.reference);
+                continue;
+            }
+            if (this.store) {
+                const orgId = source.scope === undefined || source.scope === 'org' ? await this.getCurrentOrgId() : undefined;
+                const selected = await this.store.loadCredential(this.descriptor.id, this.scopedSource(source, orgId));
+                if (selected)
+                    candidates.push(parseIntegrationBoundary(CredentialReferenceSchema, selected));
+            }
+            if (source.reference)
+                candidates.push(source.reference);
+        }
+        return candidates;
+    }
+    /** Provider request configuration contains references; only Secrets reads their values. */
+    async getCredentialUseConfiguration(selector) {
+        if (selector && this.descriptor.configurationSource === 'host') {
+            throw new CapabilityError('Host integration configuration cannot select a saved account.', 'CONFLICT', {
+                reason: 'integration-host-credential-selection-conflict', retryable: false
+            });
+        }
+        let selected;
+        if (selector) {
+            const load = this.store?.loadConnectionReferences;
+            if (!load)
+                throw new CapabilityError('Saved connection reference delivery is unavailable.', 'UNAVAILABLE', {
+                    reason: 'integration-connection-references-unsupported', retryable: false
+                });
+            selected = await this.loadSelectedConnection(selector, load);
+        }
+        const declaredSources = await this.credentialSources();
+        const sources = selected ? this.hostCredentialSources(declaredSources) : declaredSources;
+        const entries = [];
+        for (const key of new Set(sources.map(source => source.key))) {
+            const candidates = await this.credentialCandidates(sources.filter(source => source.key === key));
+            if (candidates.length > 0)
+                entries.push([key, candidates]);
+        }
+        const references = Object.fromEntries(entries);
+        const hostKeys = new Set(sources
+            .filter(source => source.source === 'setting' || source.reference !== undefined)
+            .map(source => source.key));
+        return parseIntegrationBoundary(IntegrationProviderResolvedConfigurationSchema, {
+            config: this.protectHostEndpointConfiguration(selected?.config ?? await this.getConfig(), hostKeys),
+            credentials: {},
+            credentialReferences: this.mergeCredentialReferences(references, selected?.credentialReferences ?? {})
+        });
+    }
+    async loadSelectedConnection(selector, load) {
+        selector = parseIntegrationBoundary(IntegrationConnectionSelectorSchema, selector);
+        const runtime = this.context.runtime;
+        if (!runtime) {
+            throw new CapabilityError('Selected integration delivery requires its authenticated runtime request.', 'UNAVAILABLE', { reason: 'integration-runtime-required', retryable: false });
+        }
+        const principal = runtime.requestPrincipal();
+        if (principal.kind === 'service') {
+            const account = principal.delegation?.account;
+            if (!account || principal.onBehalfOf !== account.ownerId || account.integrationId !== this.descriptor.id || account.connectionId !== selector.connectionId) {
+                throw new CapabilityError('Selected integration delivery requires verified authority for this account.', 'PERMISSION_DENIED', { reason: 'integration-account-delegation-mismatch', retryable: false });
+            }
+            const actor = { userId: account.ownerId };
+            if (account.orgId !== undefined)
+                actor.organizationId = account.orgId;
+            return this.readSelectedConnection(load, selector, actor);
+        }
+        if (principal.kind !== 'user')
+            throw new CapabilityError('Selected integration delivery requires an authenticated user.', 'PERMISSION_DENIED', { reason: 'integration-account-principal-required', retryable: false });
+        const actor = { userId: principal.userId };
+        if (principal.orgId !== undefined)
+            actor.organizationId = principal.orgId;
+        return this.readSelectedConnection(load, selector, actor);
+    }
+    async getResolvedConfiguration(selector) {
+        if (selector && this.descriptor.configurationSource === 'host') {
+            throw new CapabilityError('Host integration configuration cannot select a saved account.', 'CONFLICT', {
+                reason: 'integration-host-credential-selection-conflict', retryable: false
+            });
+        }
+        if (selector) {
+            const load = this.store?.loadConnection;
+            if (!load)
+                throw new CapabilityError('Saved connection selection is unavailable.', 'UNAVAILABLE', { reason: 'integration-connection-selection-unsupported' });
+            return this.resolveSelectedConnection(await this.loadSelectedConnection(selector, load));
+        }
+        const [config, resolved] = await Promise.all([
+            this.getConfig(),
+            this.resolveCredentialSet()
+        ]);
+        return {
+            config: this.protectHostEndpointConfiguration(config, resolved.hostCredentialKeys),
+            credentials: resolved.credentials,
+            credentialReferences: resolved.credentialReferences
+        };
+    }
+    async setCredential(key, value, metadata) {
+        const request = parseIntegrationBoundary(IntegrationCredentialWriteRequestSchema, {
+            key,
+            value,
+            metadata
+        });
+        const source = this.requireWriteableSource(request.key);
+        const orgId = source.scope === undefined || source.scope === 'org'
+            ? await this.getCurrentOrgId()
+            : undefined;
+        const scopedSource = this.scopedSource(source, orgId);
+        if (!this.store)
+            throw this.missingStoreError();
+        await this.store.writeCredential(this.descriptor.id, scopedSource, request.value, request.metadata);
+    }
+    async unsetCredential(key) {
+        key = parseIntegrationBoundary(IntegrationCredentialKeySchema, key);
+        const source = this.requireWriteableSource(key);
+        const orgId = source.scope === undefined || source.scope === 'org'
+            ? await this.getCurrentOrgId()
+            : undefined;
+        const scopedSource = this.scopedSource(source, orgId);
+        if (!this.store)
+            throw this.missingStoreError();
+        await this.store.deleteCredential(this.descriptor.id, scopedSource);
+    }
+    async startAuthorization(input) {
+        input = parseIntegrationBoundary(IntegrationOAuthStartSchema, input);
+        const oauth = this.requireOAuthMetadata();
+        const clientId = await this.getCredentialCandidates('clientId');
+        if (clientId.length === 0) {
+            throw new CapabilityError('Integration OAuth requires a client identifier.', 'UNAVAILABLE', { reason: 'integration-oauth-client-id-required', retryable: false });
+        }
+        const params = new URLSearchParams({
+            client_id: '{clientId}',
+            redirect_uri: input.redirectUri,
+            response_type: 'code',
+            state: input.state
+        });
+        const scopes = input.scopes ?? oauth.scopes;
+        if (scopes.length > 0) {
+            params.set('scope', scopes.join(' '));
+        }
+        for (const [key, value] of Object.entries(oauth.authorizationParams ?? {})) {
+            params.set(key, value);
+        }
+        try {
+            return { authorizationUrl: await applyIntegrationClientId(this.context.runtime, {
+                    authorizationUrl: `${oauth.authorizationEndpoint}?${params.toString()}`,
+                    clientId
+                }) };
+        }
+        catch (error) {
+            if (error instanceof CapabilityError && error.reason === 'oauth-client-credential-unset') {
+                throw new CapabilityError('Integration OAuth requires a client identifier.', 'UNAVAILABLE', { reason: 'integration-oauth-client-id-required', retryable: false });
+            }
+            throw error;
+        }
+    }
+    async completeAuthorization(input) {
+        input = parseIntegrationBoundary(IntegrationOAuthCompletionSchema, input);
+        const oauth = this.requireOAuthMetadata();
+        const tokens = await exchangeIntegrationAuthorizationCode(this.context.runtime, {
+            tokenEndpoint: oauth.tokenEndpoint,
+            clientId: await this.getCredentialCandidates('clientId'),
+            clientSecret: await this.getCredentialCandidates('clientSecret'),
+            clientAuthentication: oauth.clientAuthentication,
+            bodyEncoding: oauth.bodyEncoding,
+            headers: oauth.headers,
+            code: input.code,
+            redirectUri: input.redirectUri
+        });
+        // Persist callback-derived config first (e.g. QuickBooks realmId,
+        // Microsoft tenant) so subsequent getConfig() reads see them and
+        // the integration_services row is up-to-date before the secrets
+        // land via setCredential.
+        const configPatch = {};
+        for (const param of oauth.configFromCallback) {
+            const value = input.params?.[param];
+            if (value !== undefined)
+                configPatch[param] = value;
+        }
+        if (Object.keys(configPatch).length > 0) {
+            const orgId = await this.getCurrentOrgId();
+            if (!this.store)
+                throw this.missingStoreError();
+            await this.store.writeConfig(this.descriptor.id, { scope: 'org', scopeId: this.resolveScopeId(undefined, orgId) }, configPatch);
+        }
+        const accessExpiresAt = tokens.expires_in
+            ? new Date(Date.now() + tokens.expires_in * 1000).toISOString()
+            : undefined;
+        const refreshExpiry = tokens.x_refresh_token_expires_in ?? tokens.refresh_token_expires_in;
+        const refreshExpiresAt = refreshExpiry
+            ? new Date(Date.now() + refreshExpiry * 1000).toISOString()
+            : undefined;
+        await this.setCredential('accessToken', tokens.access_token, {
+            expiresAt: accessExpiresAt,
+            tags: { tokenType: 'access' }
+        });
+        if (tokens.refresh_token) {
+            await this.setCredential('refreshToken', tokens.refresh_token, {
+                expiresAt: refreshExpiresAt,
+                tags: { tokenType: 'refresh' }
+            });
+        }
+    }
+    missingStoreError() {
+        return new CapabilityError('The integration store is not mounted.', 'UNAVAILABLE', { reason: 'integration-store-unavailable', retryable: false });
+    }
+    async invokeOperation(opId, args) {
+        parseIntegrationBoundary(IntegrationOperationInputSchema, args);
+        const declared = (this.descriptor.operations ?? []).find((op) => op.id === opId);
+        if (!declared) {
+            throw new CapabilityError('The integration operation is not declared.', 'INVALID_INPUT', { reason: 'integration-operation-undeclared', retryable: false });
+        }
+        throw new CapabilityError('The integration operation has no implementation.', 'UNAVAILABLE', { reason: 'integration-operation-unimplemented', retryable: false });
+    }
+    requireOAuthMetadata() {
+        const oauth = this.descriptor.oauth;
+        if (!oauth) {
+            throw new CapabilityError('Integration OAuth metadata is not declared.', 'UNAVAILABLE', { reason: 'integration-oauth-metadata-required', retryable: false });
+        }
+        return oauth;
+    }
+    requireWriteableSource(key) {
+        key = parseIntegrationBoundary(IntegrationCredentialKeySchema, key);
+        const declared = (this.descriptor.credentials ?? []).filter((source) => source.key === key);
+        const source = declared.find((candidate) => candidate.source === 'secret'
+            && (candidate.scope !== undefined || candidate.reference === undefined));
+        if (!source) {
+            if (declared.some((candidate) => candidate.reference !== undefined && candidate.scope === undefined)) {
+                throw new CapabilityError('Host credential references are read-only.', 'INVALID_INPUT', { reason: 'integration-host-credential-readonly', retryable: false });
+            }
+            throw new CapabilityError('The integration credential is not declared as a managed secret.', 'INVALID_INPUT', { reason: 'integration-credential-source-readonly', retryable: false });
+        }
+        return source;
+    }
+    scopedSource(source, orgId) {
+        const scope = source.scope ?? 'org';
+        let scopeId;
+        if (scope === 'org') {
+            scopeId = this.resolveScopeId(source.scopeId, orgId);
+        }
+        else if (source.scopeId !== undefined) {
+            scopeId = source.scopeId;
+        }
+        else {
+            throw new CapabilityError('An integration credential requires a complete managed scope.', 'INVALID_INPUT', { reason: 'integration-credential-scope-incomplete', retryable: false });
+        }
+        return parseIntegrationBoundary(IntegrationCredentialSourceSchema, {
+            ...source,
+            scope,
+            scopeId,
+            providerType: source.providerType ?? this.descriptor.provider
+        });
+    }
+    async resolveCredentialSource(source, orgId) {
+        if (source.source === 'setting') {
+            const settingKey = source.settingKey;
+            if (!settingKey) {
+                throw new CapabilityError('The credential setting key is not declared.', 'INVALID_INPUT', {
+                    reason: 'integration-credential-setting-key-required', retryable: false
+                });
+            }
+            const value = await this.getSettingValue(settingKey);
+            if (value === undefined)
+                return { value: undefined, hostReference: false };
+            const reference = parseIntegrationBoundary(CredentialReferenceSchema, value);
+            const resolved = await this.resolveCredentialReference(reference, source.required);
+            return { value: resolved, hostReference: resolved !== undefined, reference };
+        }
+        if (source.reference !== undefined && source.scope === undefined) {
+            const resolved = await this.resolveCredentialReference(source.reference, source.required);
+            return { value: resolved, hostReference: resolved !== undefined, reference: source.reference };
+        }
+        if (!this.store) {
+            if (source.required)
+                throw this.missingStoreError();
+            return { value: undefined, hostReference: false };
+        }
+        const scopedSource = this.scopedSource(source, orgId);
+        const reference = await this.store.loadCredential(this.descriptor.id, scopedSource);
+        if (!reference) {
+            const resolved = await this.resolveCredentialReference(source.reference, source.required);
+            return { value: resolved, hostReference: resolved !== undefined, reference: source.reference };
+        }
+        // Metadata proved the tenant secret exists. A value lookup failure now
+        // propagates instead of being confused with an absent saved credential.
+        return {
+            value: await this.resolveCredentialReference(reference, true),
+            hostReference: false,
+            reference
+        };
+    }
+    async resolveCredentialSet(sources) {
+        sources ??= await this.credentialSources();
+        const credentials = {};
+        const credentialReferences = {};
+        const hostCredentialKeys = new Set();
+        const needsOrg = sources.some((source) => source.source === 'secret'
+            && !(source.reference !== undefined && source.scope === undefined)
+            && (source.scope === undefined || source.scope === 'org'));
+        const orgId = needsOrg ? await this.getCurrentOrgId() : undefined;
+        for (const source of sources) {
+            if (Object.hasOwn(credentials, source.key))
+                continue;
+            const resolved = await this.resolveCredentialSource(source, orgId);
+            if (resolved.value !== undefined) {
+                credentials[source.key] = resolved.value;
+                if (resolved.reference)
+                    credentialReferences[source.key] = [resolved.reference];
+                if (resolved.hostReference)
+                    hostCredentialKeys.add(source.key);
+                continue;
+            }
+            if (source.required) {
+                throw new CapabilityError('A required integration credential is absent.', 'UNAVAILABLE', { reason: 'integration-credential-required', retryable: false });
+            }
+        }
+        return { credentials, credentialReferences, hostCredentialKeys };
+    }
+    async readSelectedConnection(load, selector, actor) {
+        const store = this.store;
+        if (!store) {
+            throw new CapabilityError('Saved connection selection is unavailable.', 'UNAVAILABLE', {
+                reason: 'integration-connection-selection-unsupported', retryable: false
+            });
+        }
+        return parseIntegrationBoundary(IntegrationProviderResolvedConfigurationSchema, await load.call(store, this.descriptor, selector, actor));
+    }
+    hostCredentialSources(sources) {
+        return sources.filter((source) => source.source === 'setting'
+            || (source.reference !== undefined && source.scope === undefined));
+    }
+    mergeCredentialReferences(host, selected) {
+        return {
+            ...selected,
+            ...Object.fromEntries(Object.entries(host).map(([key, candidates]) => {
+                const accountCandidates = Object.hasOwn(selected, key) ? selected[key] : [];
+                return [key, [...candidates, ...accountCandidates]];
+            }))
+        };
+    }
+    async resolveSelectedConnection(selected) {
+        const hostSources = this.hostCredentialSources(await this.credentialSources());
+        const host = await this.resolveCredentialSet(hostSources);
+        // A resolved host value wins; a confirmed-absent optional host source
+        // advances to the selected account, as reference delivery does.
+        return parseIntegrationBoundary(IntegrationProviderResolvedConfigurationSchema, {
+            config: this.protectHostEndpointConfiguration(selected.config, host.hostCredentialKeys),
+            credentials: { ...selected.credentials, ...host.credentials },
+            credentialReferences: this.mergeCredentialReferences(host.credentialReferences, selected.credentialReferences)
+        });
+    }
+    protectHostEndpointConfiguration(config, hostCredentialKeys) {
+        if (hostCredentialKeys.size === 0)
+            return config;
+        const protectedConfig = { ...config };
+        for (const key of new Set(['baseUrl', ...this.descriptor.protectedConfigKeys])) {
+            const declared = key === 'baseUrl' ? this.descriptor.baseUrl ?? this.descriptor.config[key] : this.descriptor.config[key];
+            if (declared === undefined)
+                delete protectedConfig[key];
+            else
+                protectedConfig[key] = declared;
+        }
+        return protectedConfig;
+    }
+    async resolveCredentialReference(reference, required) {
+        const runtime = this.context.runtime;
+        if (!runtime) {
+            throw new CapabilityError('Integration credentials require the caller runtime.', 'UNAVAILABLE', { reason: 'integration-runtime-required', retryable: false });
+        }
+        if (!reference)
+            return undefined;
+        const result = await runtime.resolveCredential(reference);
+        if (result.ok)
+            return result.value;
+        if (!required && result.error.code === 'NOT_FOUND' && result.error.reason === 'credential-not-set') {
+            return undefined;
+        }
+        throw result.error;
+    }
+    /**
+     * Build org-scoped scopeId for credential lookup.
+     * Combines the live request orgId with the descriptor-level scopeId.
+     * Format: {orgId}:{scopeId} when both present, {orgId} when only orgId.
+     */
+    resolveScopeId(descriptorScopeId, orgId) {
+        if (!orgId) {
+            throw new CapabilityError('Organization identity is required for integration access.', 'PERMISSION_DENIED', {
+                reason: 'integration-organization-required', retryable: false
+            });
+        }
+        if (!descriptorScopeId)
+            return orgId;
+        return `${orgId}:${descriptorScopeId}`;
+    }
+    /**
+     * Resolve the CALLING request's org id at call time. The integration
+     * provider instance is value-cached by the runtime for the isolate
+     * lifetime, so a constructor-snapshotted `this.context.orgId` would
+     * freeze to whichever org FIRST resolved the provider — every later
+     * request (any org) would then read and write that first org's
+     * credentials and config (cross-tenant bleed; the Microsoft pack fixed
+     * the same bug in ac19f2688). Read the live request context instead
+     * (`runtime.context('orgId')`, set by hosts via runWithRequestContext),
+     * falling back to the constructor-injected context orgId, then
+     * undefined (system/platform scope).
+     */
+    async getCurrentOrgId() {
+        const runtime = this.context.runtime;
+        if (runtime?.hasContext('orgId')) {
+            const value = parseIntegrationBoundary(IntegrationContextOrgIdSchema, await runtime.context('orgId'));
+            if (value !== undefined)
+                return value;
+        }
+        return parseIntegrationBoundary(IntegrationContextOrgIdSchema, this.context.orgId);
+    }
+    async getSettingValue(settingKey) {
+        const settingValue = await this.settingsReader.get(settingKey);
+        if (settingValue === undefined)
+            return undefined;
+        return parseIntegrationBoundary(IntegrationConfigValueSchema, settingValue);
+    }
+}
+function resolveIntegrationProvider(candidates, scope) {
+    const typedCandidates = candidates.map((candidate) => parseIntegrationBoundary(IntegrationProviderDescriptorSchema, candidate));
+    if (typedCandidates.length === 0)
+        return undefined;
+    const enabled = typedCandidates.filter((descriptor) => descriptor.enabled !== false);
+    const matching = enabled.filter((descriptor) => {
+        if (!descriptor.hardware || descriptor.hardware.length === 0)
+            return true;
+        return scope.hardware !== undefined && descriptor.hardware.includes(scope.hardware);
+    });
+    if (matching.length === 0)
+        return enabled[0] ?? typedCandidates[0];
+    return [...matching].sort((left, right) => (right.priority ?? 0) - (left.priority ?? 0))[0];
+}
+export const integrationProviderKind = {
+    id: 'integration/provider',
+    descriptorSchema: IntegrationProviderDescriptorSchema,
+    defaultImplementation: BaseIntegrationProvider,
+    resolve: resolveIntegrationProvider,
+    contexts: [integrationStoreContextId]
+};
+//# sourceMappingURL=integration.kind.js.map