@almadar/integrations 2.25.0 → 2.26.0

package/dist/{BaseIntegration-MA-b4fh8.d.ts → BaseIntegration-C_5q54DM.d.ts}

@@ -117,6 +117,65 @@ interface ValidationError {
  */
 declare function validateParams(integration: string, action: string, params: IntegrationParams): ValidationResult;
 
+/**
+ * Optional per-call context for principal-scoped resolution (W4) and
+ * caller-identity enforcement (I-25). The default — absent — means the
+ * tenant/app-wide credential set with an anonymous caller; role-gated
+ * integrations (credentials) fail closed without it. Additive: every
+ * existing call site is untouched.
+ */
+interface IntegrationCallContext {
+    principal?: string;
+    /** The caller's roster role, from the same identity entity-ACL enforces against. */
+    role?: string;
+}
+/**
+ * Factory for creating and managing integration instances
+ */
+declare class IntegrationFactory {
+    private instances;
+    private configs;
+    /**
+     * Configure an integration (doesn't instantiate yet). A `principal` scopes
+     * the config to that principal; the app-wide config (no principal) is the
+     * fallback for every principal.
+     */
+    configure(name: string, config: Omit<IntegrationConfig, 'name'>, principal?: string): void;
+    /**
+     * Get or create an integration instance. Principal-scoped lookups fall
+     * back to the app-wide config when no per-principal config exists.
+     */
+    get(name: string, principal?: string): BaseIntegration;
+    /**
+     * Execute an action on an integration
+     */
+    execute(integration: string, action: string, params: IntegrationParams, context?: IntegrationCallContext): Promise<IntegrationResult>;
+    /**
+     * Check if integration is configured
+     */
+    isConfigured(name: string, principal?: string): boolean;
+    /**
+     * Register an integration instance directly (used by mock infrastructure)
+     */
+    registerInstance(name: string, instance: BaseIntegration, principal?: string): void;
+    /**
+     * Drop the cached instance(s) for a name so the next `get` rebuilds from
+     * the current config — how a credential change goes live without restart.
+     * Configs are kept; without a name, every instance is dropped.
+     */
+    invalidate(name?: string): void;
+    /**
+     * Clear all instances (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Clear all instances and configs
+     */
+    reset(): void;
+}
+declare function getIntegrationFactory(): IntegrationFactory;
+declare function resetIntegrationFactory(): void;
+
 /**
  * Base class for all integrations
  */
@@ -125,9 +184,11 @@ declare abstract class BaseIntegration {
     protected logger: IntegrationLogger;
     constructor(config: IntegrationConfig);
     /**
-     * Execute an action
+     * Execute an action. `context` carries the caller's identity when the host
+     * supplies one; integrations that gate actions by role read it and fail
+     * closed when it is absent.
      */
-    abstract execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
+    abstract execute(action: string, params: IntegrationParams, context?: IntegrationCallContext): Promise<IntegrationResult>;
     /**
      * Validate action params against registry
      */
@@ -146,4 +207,4 @@ declare abstract class BaseIntegration {
     protected executeWithRetry<T>(fn: () => Promise<T>): Promise<T>;
 }
 
-export { BaseIntegration as B, type IntegrationConfig as I, type ValidationError as V, IntegrationError as a, type IntegrationErrorCode as b, type IntegrationLogger as c, type IntegrationParamValue as d, type IntegrationParams as e, type IntegrationResult as f, type ValidationResult as g, validateParams as v };
+export { BaseIntegration as B, type IntegrationCallContext as I, type ValidationError as V, type IntegrationConfig as a, IntegrationError as b, type IntegrationErrorCode as c, IntegrationFactory as d, type IntegrationLogger as e, type IntegrationParamValue as f, type IntegrationParams as g, type IntegrationResult as h, type ValidationResult as i, getIntegrationFactory as j, resetIntegrationFactory as r, validateParams as v };

package/dist/index.d.ts

@@ -1,10 +1,8 @@
-import { c as IntegrationLogger, b as IntegrationErrorCode, I as IntegrationConfig, B as BaseIntegration, e as IntegrationParams, f as IntegrationResult } from './BaseIntegration-MA-b4fh8.js';
-export { a as IntegrationError, d as IntegrationParamValue, V as ValidationError, g as ValidationResult, v as validateParams } from './BaseIntegration-MA-b4fh8.js';
-import { e as CredentialStore } from './store-CW1v7Apc.js';
-export { A as ArxivActions, C as CLIActions, a as CREDENTIAL_ENTITY_TYPE, b as CREDENTIAL_MASTER_KEY_ENV, c as CredentialEntry, d as CredentialPersistence, D as DatabaseActions, f as DatabaseDriver, g as DatabaseQueryParamValue, h as DatabaseQueryParams, i as DatabaseQueryResult, j as DatabaseRow, k as DeepAgentActions, l as DockerActions, E as EmailActions, G as GitHubActions, I as IconifyActions, m as IntegrationActionName, n as IntegrationContracts, o as IntegrationName, L as LLMIntegrationActions, M as MLActions, O as OAuthActions, p as OtelActions, Q as QueueActions, R as RedisActions, S as StorageActions, q as StripeActions, T as TwilioActions, W as WebhookActions, r as WikimediaActions, Y as YouTubeActions } from './store-CW1v7Apc.js';
-import { LogMeta } from '@almadar/core';
-import { a as IntegrationFactory } from './factory-BPVhvv5q.js';
-export { I as IntegrationCallContext, g as getIntegrationFactory, r as resetIntegrationFactory } from './factory-BPVhvv5q.js';
+import { e as IntegrationLogger, c as IntegrationErrorCode, a as IntegrationConfig, B as BaseIntegration, d as IntegrationFactory, g as IntegrationParams, h as IntegrationResult, I as IntegrationCallContext } from './BaseIntegration-C_5q54DM.js';
+export { b as IntegrationError, f as IntegrationParamValue, V as ValidationError, i as ValidationResult, j as getIntegrationFactory, r as resetIntegrationFactory, v as validateParams } from './BaseIntegration-C_5q54DM.js';
+import { e as CredentialStore, d as CredentialPersistence, H as HookDeclaration } from './store-tehIm2rt.js';
+export { A as ArxivActions, C as CLIActions, a as CREDENTIAL_ENTITY_TYPE, b as CREDENTIAL_MASTER_KEY_ENV, c as CredentialEntry, D as DatabaseActions, f as DatabaseDriver, g as DatabaseQueryParamValue, h as DatabaseQueryParams, i as DatabaseQueryResult, j as DatabaseRow, k as DeepAgentActions, l as DockerActions, E as EmailActions, G as GitHubActions, I as IconifyActions, m as IntegrationActionName, n as IntegrationContracts, o as IntegrationName, L as LLMIntegrationActions, M as MLActions, O as OAuthActions, p as OtelActions, Q as QueueActions, R as RedisActions, S as StorageActions, q as StripeActions, T as TwilioActions, W as WebhookActions, r as WikimediaActions, Y as YouTubeActions, s as serviceHooks } from './store-tehIm2rt.js';
+import { LogMeta, EntityRow, EventPayload } from '@almadar/core';
 export { GitHubIntegration } from './integrations/github/index.js';
 
 /**
@@ -88,6 +86,30 @@ declare function uninstallCredentialStore(): void;
  */
 declare function resolveCredentialRef(ref: string, env?: Record<string, string | undefined>): string | undefined;
 
+/** Env var overriding where the dev credential file lives. */
+declare const CREDENTIALS_FILE_ENV = "ALMADAR_CREDENTIALS_FILE";
+/**
+ * File-backed `CredentialPersistence` for dev store-first mode (I-31): rows
+ * survive playground restarts so the encrypt-at-rest path is exercised on
+ * every dev run, exactly like a deployed app's Firestore-backed store. Rows
+ * arrive already encrypted (ciphertext/iv/authTag) — this adapter never sees
+ * plaintext. Writes are atomic (tmp file + rename). Never use in production.
+ */
+declare class FileCredentialPersistence implements CredentialPersistence {
+    private readonly path;
+    private counter;
+    constructor(path?: string);
+    get filePath(): string;
+    private load;
+    private save;
+    create(entityType: string, data: EntityRow): Promise<{
+        id: string;
+    }>;
+    update(_entityType: string, id: string, data: EntityRow): Promise<void>;
+    delete(_entityType: string, id: string): Promise<void>;
+    list(_entityType: string): Promise<EntityRow[]>;
+}
+
 /**
  * Canonical Almadar shapes for the Stripe integration.
  *
@@ -463,13 +485,61 @@ declare class CalendarIntegration extends BaseIntegration {
 }
 
 /**
- * Google Drive integration — service account auth, optionally acting as a
- * Workspace user via domain-wide delegation (GOOGLE_DRIVE_SUBJECT). File
- * content crosses this boundary as base64 (data URL accepted on upload).
+ * All registered inbound-hook providers, derived from the `serviceHooks`
+ * declarations (the single source the registry and codegen also derive from).
+ * Hosts that serve arbitrary schemas (the playground) mount this full map;
+ * generated apps get a per-app subset via the compiler's hooks-providers.ts.
+ *
+ * `HOOK_PROVIDER_FACTORIES` is the static factory table TypeScript needs
+ * (export names cannot be resolved dynamically without casts); the drift
+ * guard below fails loudly if a declaration names a factory this table lacks.
+ */
+
+interface HookProviderInput {
+    headers: Record<string, string | undefined>;
+    rawBody: string;
+}
+type HookProviderResult = {
+    event: string;
+    payload: EventPayload;
+} | {
+    ack: true;
+} | {
+    error: string;
+};
+type RegisteredHookProvider = (input: HookProviderInput) => HookProviderResult;
+/** Every hook declaration across all services — used by the drift-guard test. */
+declare function allHookDeclarations(): HookDeclaration[];
+/**
+ * Build the full provider map from every service's hook declarations,
+ * resolving each provider's verification secret from `env`. Throws when a
+ * declaration names a factory the table above does not carry — declaration
+ * and implementation must advance together.
+ */
+declare function registeredHookProviders(env?: Record<string, string | undefined>): Record<string, RegisteredHookProvider>;
+
+/**
+ * Google Drive integration — dual auth:
+ * - **Service account** (GOOGLE_DRIVE_SA_KEY, optional GOOGLE_DRIVE_SUBJECT
+ *   delegation) serves reads (list/get/share).
+ * - **User OAuth** (GOOGLE_DRIVE_REFRESH_TOKEN + the app's OAUTH_CLIENT_ID/
+ *   SECRET, obtained once via `tools/scripts/drive-consent.mjs`) serves
+ *   WRITES (`uploadFile`/`createFolder`) when present — Google enforces zero
+ *   SA storage quota on personal accounts, so SA writes into a shared My
+ *   Drive folder are impossible; the user client also covers reads when no
+ *   SA key is configured. `GOOGLE_DRIVE_FOLDER_ID` is the default upload
+ *   parent. File content crosses this boundary as base64 (data URL accepted
+ *   on upload).
  */
 declare class DriveIntegration extends BaseIntegration {
-    private client;
+    private readonly saClient;
+    private readonly userClient;
+    private readonly defaultFolderId;
     constructor(config: IntegrationConfig);
+    /** Reads prefer the SA client (delegation-aware); user client covers its absence. */
+    private readClient;
+    /** Writes REQUIRE the user client on personal accounts (SA has no storage quota); SA only as a Workspace fallback. */
+    private writeClient;
     execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
     private listFiles;
     private getFile;
@@ -694,6 +764,36 @@ declare class OtelIntegration extends BaseIntegration {
     private getAllMetrics;
 }
 
+/** Supported OAuth providers */
+type OAuthProvider = 'google' | 'github' | 'auth0';
+/** Server-held per-authorization state (never leaves the process). */
+interface PendingAuthorization {
+    provider: OAuthProvider;
+    redirectUri: string;
+    pkceVerifier: string;
+}
+/**
+ * Where pending OIDC authorizations (PKCE verifier, redirect URI) live
+ * between `authorize` and `token`. The in-memory default works single-
+ * instance; a multi-instance deployment injects a shared-store impl (the
+ * FirestoreCredentialPersistence structural pattern) via
+ * `installPendingGrantStore` — no sticky routing needed once it does.
+ * `take` is single-use: it returns AND removes, so a state token can never
+ * be replayed. `sweep` drops expired grants.
+ */
+interface PendingGrantStore {
+    put(state: string, grant: PendingAuthorization, ttlMs: number): Promise<void>;
+    take(state: string): Promise<PendingAuthorization | null>;
+    sweep(): Promise<void>;
+}
+declare class InMemoryPendingGrantStore implements PendingGrantStore {
+    private readonly grants;
+    put(state: string, grant: PendingAuthorization, ttlMs: number): Promise<void>;
+    take(state: string): Promise<PendingAuthorization | null>;
+    sweep(): Promise<void>;
+}
+/** Install a shared pending-grant store (multi-instance hosts); null resets to in-memory. */
+declare function installPendingGrantStore(store: PendingGrantStore | null): void;
 /**
  * OAuth2/OIDC integration.
  *
@@ -707,9 +807,11 @@ declare class OtelIntegration extends BaseIntegration {
  *   behind `OAUTH_MODE=mock` (or absent client credentials) so existing
  *   tests and offline dev flows are untouched.
  *
- * Pending-authorization state (PKCE verifier, redirect URI) is held
- * in-process keyed by `state` — multi-instance deployments need sticky
- * routing between authorize and token (ledger note).
+ * Pending-authorization state (PKCE verifier, redirect URI) lives in a
+ * `PendingGrantStore` — in-memory by default (single instance), injectable
+ * via `installPendingGrantStore` for multi-instance deployments (a shared
+ * store replaces the old sticky-routing requirement). Grants are TTL-bound
+ * and single-use.
  */
 declare class OAuthIntegration extends BaseIntegration {
     /** Maps state token -> provider for pending MOCK authorization flows */
@@ -720,8 +822,9 @@ declare class OAuthIntegration extends BaseIntegration {
     private refreshIndex;
     /** Maps access token -> mock user session */
     private sessions;
-    /** Maps state -> pending OIDC authorization (real backend) */
-    private pending;
+    /** Pending OIDC authorizations (real backend) — injectable, in-memory default. */
+    private readonly fallbackPending;
+    private pendingStore;
     /** Maps access token -> ID-token subject, for userinfo subject checks */
     private subjects;
     /** Discovered issuer configurations, keyed by issuer URL */
@@ -757,13 +860,18 @@ declare class OAuthIntegration extends BaseIntegration {
  * plaintext); `set` accepts only env vars DECLARED in `serviceCredentials`
  * for the named service (plus well-formed connection refs for `database`),
  * so the page can never become an arbitrary env-injection surface; values
- * are never logged.
+ * are never logged. `set`/`remove`/`test` additionally require the caller's
+ * role (from IntegrationCallContext) to be in the admin list
+ * (ALMADAR_CREDENTIAL_ADMIN_ROLES, default admin,owner) and FAIL CLOSED
+ * without one — the un-bypassable twin of the organism-side page gate (I-25).
  */
 declare class CredentialsIntegration extends BaseIntegration {
     constructor(config: IntegrationConfig);
-    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
+    execute(action: string, params: IntegrationParams, context?: IntegrationCallContext): Promise<IntegrationResult>;
+    private adminRoles;
     private declaredFor;
     private assertSettable;
+    private storeFirst;
     private list;
     private set;
     private remove;
@@ -905,4 +1013,4 @@ declare class ArxivIntegration extends BaseIntegration {
     private search;
 }
 
-export { AccountingIntegration, type AlmadarCheckoutSession, type AlmadarCustomer, type AlmadarInvoiceFailure, type AlmadarInvoicePayment, type AlmadarPortalSession, type AlmadarStripeEvent, type AlmadarStripeEventOk, type AlmadarSubscription, type AlmadarSubscriptionStatus, type AlmadarTier, ArxivIntegration, type ArxivResult, BankingIntegration, BaseIntegration, CLIIntegration, CalendarIntegration, type CancelSubscriptionInput, ConsoleLogger, type CreateCheckoutInput, type CreateCustomerInput, type CreatePortalInput, CredentialStore, CredentialsIntegration, DatabaseIntegration, DeepAgentIntegration, DockerIntegration, DriveIntegration, EmailIntegration, EsignIntegration, IconifyIntegration, IntegrationConfig, type IntegrationConstructor, IntegrationErrorCode, IntegrationFactory, IntegrationLogger, IntegrationParams, IntegrationResult, LLMIntegration, MLIntegration, MetaAdsIntegration, OAuthIntegration, OtelIntegration, PushIntegration, QueueIntegration, RedisIntegration, type RetryConfig, type SqlGuardResult, StorageIntegration, StripeIntegration, type StripePriceMap, TwilioIntegration, type UpdateSubscriptionInput, type VerifyAndParseInput, WebhookIntegration, WikimediaIntegration, YouTubeIntegration, assertReadOnlySelect, getActiveFactory, getInstalledCredentialStore, getIntegration, getRegisteredIntegrations, googleCalendarHookProvider, installActiveFactory, installCredentialStore, isKnownIntegration, parseCalendarPushNotification, registerIntegration, resolveCredentialRef, uninstallCredentialStore, verifyAndParseStripeEvent, withRetry };
+export { AccountingIntegration, type AlmadarCheckoutSession, type AlmadarCustomer, type AlmadarInvoiceFailure, type AlmadarInvoicePayment, type AlmadarPortalSession, type AlmadarStripeEvent, type AlmadarStripeEventOk, type AlmadarSubscription, type AlmadarSubscriptionStatus, type AlmadarTier, ArxivIntegration, type ArxivResult, BankingIntegration, BaseIntegration, CLIIntegration, CREDENTIALS_FILE_ENV, CalendarIntegration, type CancelSubscriptionInput, ConsoleLogger, type CreateCheckoutInput, type CreateCustomerInput, type CreatePortalInput, CredentialPersistence, CredentialStore, CredentialsIntegration, DatabaseIntegration, DeepAgentIntegration, DockerIntegration, DriveIntegration, EmailIntegration, EsignIntegration, FileCredentialPersistence, HookDeclaration, type HookProviderInput, type HookProviderResult, IconifyIntegration, InMemoryPendingGrantStore, IntegrationCallContext, IntegrationConfig, type IntegrationConstructor, IntegrationErrorCode, IntegrationFactory, IntegrationLogger, IntegrationParams, IntegrationResult, LLMIntegration, MLIntegration, MetaAdsIntegration, OAuthIntegration, OtelIntegration, type PendingGrantStore, PushIntegration, QueueIntegration, RedisIntegration, type RegisteredHookProvider, type RetryConfig, type SqlGuardResult, StorageIntegration, StripeIntegration, type StripePriceMap, TwilioIntegration, type UpdateSubscriptionInput, type VerifyAndParseInput, WebhookIntegration, WikimediaIntegration, YouTubeIntegration, allHookDeclarations, assertReadOnlySelect, getActiveFactory, getInstalledCredentialStore, getIntegration, getRegisteredIntegrations, googleCalendarHookProvider, installActiveFactory, installCredentialStore, installPendingGrantStore, isKnownIntegration, parseCalendarPushNotification, registerIntegration, registeredHookProviders, resolveCredentialRef, uninstallCredentialStore, verifyAndParseStripeEvent, withRetry };