@almadar/integrations 2.38.0 → 2.39.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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-CWdas-N_.js';
 export { b as IntegrationError, f as IntegrationParamValue, U as UnknownActionError, V as ValidationError, i as ValidationResult, j as getIntegrationFactory, r as resetIntegrationFactory, v as validateParams } from './BaseIntegration-CWdas-N_.js';
-import { e as CredentialStore, d as CredentialPersistence, H as HookDeclaration } from './store-RNvxZO-q.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 allCredentialEnvVars, t as declaredCredentialEnvVars, u as serviceHooks } from './store-RNvxZO-q.js';
+import { e as CredentialStore, d as CredentialPersistence, H as HookDeclaration } from './store-DG5OGiuQ.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 allCredentialEnvVars, t as declaredCredentialEnvVars, u as serviceHooks } from './store-DG5OGiuQ.js';
 import { LogMeta, EntityRow, EventPayload } from '@almadar/core';
 export { GitHubIntegration } from './integrations/github/index.js';
 
@@ -766,11 +766,44 @@ declare class OtelIntegration extends BaseIntegration {
 
 /** Supported OAuth providers */
 type OAuthProvider = 'google' | 'github' | 'auth0';
+/** `token` result: the grant's tokens plus the scopes granted and the subject bound at `authorize`. */
+interface OAuthTokenResult {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    tokenType: 'bearer';
+    scope: string[];
+    subject?: string;
+}
+/** `authorize` input: `subject` is the opaque id of whoever starts the flow, handed back by `token`. */
+interface OAuthAuthorizeInput {
+    provider: OAuthProvider;
+    scopes: string[];
+    redirectUri: string;
+    subject?: string;
+}
+/** `token` input: the provider's code, the `state` returned by `authorize`, and who is completing. */
+interface OAuthTokenInput {
+    code: string;
+    state: string;
+    /** Must equal the grant's bound subject; checked before any code exchange. */
+    subject?: string;
+}
+/** No pending grant for this `state`: never issued, already used, or expired. */
+declare class OAuthGrantNotFoundError extends Error {
+    constructor(state: string);
+}
+/** The completing subject is not the one bound at `authorize`; the grant is consumed, nothing exchanged. */
+declare class OAuthSubjectMismatchError extends Error {
+    constructor();
+}
 /** Server-held per-authorization state (never leaves the process). */
 interface PendingAuthorization {
     provider: OAuthProvider;
     redirectUri: string;
     pkceVerifier: string;
+    /** Opaque id the host bound at `authorize` (the verified user who started); `token` returns it. */
+    subject?: string;
 }
 /**
  * Where pending OIDC authorizations (PKCE verifier, redirect URI) live
@@ -814,7 +847,7 @@ declare function installPendingGrantStore(store: PendingGrantStore | null): void
  * and single-use.
  */
 declare class OAuthIntegration extends BaseIntegration {
-    /** Maps state token -> provider for pending MOCK authorization flows */
+    /** Maps state token -> pending MOCK authorization */
     private states;
     /** Maps access token -> token set (mock backend) */
     private tokens;
@@ -832,6 +865,13 @@ declare class OAuthIntegration extends BaseIntegration {
     private readonly real;
     constructor(config: IntegrationConfig);
     execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
+    /** Build the provider authorization URL and hold the pending grant (PKCE verifier, subject) under `state`. */
+    startAuthorization(input: OAuthAuthorizeInput): Promise<{
+        authUrl: string;
+        state: string;
+    }>;
+    /** Consume the pending grant once and exchange the code; throws on an unknown, replayed or expired `state`. */
+    completeAuthorization(input: OAuthTokenInput): Promise<OAuthTokenResult>;
     private issuerFor;
     private configurationFor;
     private oidcAuthorize;
@@ -1039,4 +1079,4 @@ declare class RiggerIntegration extends BaseIntegration {
     private generate;
 }
 
-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, RiggerIntegration, 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 };
+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, type OAuthAuthorizeInput, OAuthGrantNotFoundError, OAuthIntegration, type OAuthProvider, OAuthSubjectMismatchError, type OAuthTokenInput, type OAuthTokenResult, OtelIntegration, type PendingAuthorization, type PendingGrantStore, PushIntegration, QueueIntegration, RedisIntegration, type RegisteredHookProvider, type RetryConfig, RiggerIntegration, 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 };

package/dist/index.js

@@ -132,8 +132,8 @@ var serviceCredentials = {
     { envVar: "REDIS_URL", required: true, description: "Redis connection URL" }
   ],
   oauth: [
-    { envVar: "OAUTH_CLIENT_ID", required: true, description: "OIDC client ID" },
-    { envVar: "OAUTH_CLIENT_SECRET", required: true, description: "OIDC client secret" },
+    { envVar: "OAUTH_CLIENT_ID", required: true, description: "OAuth/OIDC client ID" },
+    { envVar: "OAUTH_CLIENT_SECRET", required: true, description: "OAuth/OIDC client secret" },
     { envVar: "OAUTH_REDIRECT_URI", required: false, description: "OIDC redirect URI (default per-call param)" },
     { envVar: "OIDC_ISSUER_URL", required: false, description: "OIDC issuer URL (default https://accounts.google.com)" }
   ],
@@ -4029,6 +4029,31 @@ var PROVIDER_AUTH_URLS = {
 var PROVIDER_ISSUERS = {
   google: "https://accounts.google.com"
 };
+var PROVIDER_SERVER_METADATA = {
+  github: {
+    issuer: "https://github.com",
+    authorization_endpoint: "https://github.com/login/oauth/authorize",
+    token_endpoint: "https://github.com/login/oauth/access_token"
+  }
+};
+var OAuthGrantNotFoundError = class extends Error {
+  constructor(state) {
+    super(`Invalid or expired state token: ${state}`);
+    this.name = "OAuthGrantNotFoundError";
+  }
+};
+var OAuthSubjectMismatchError = class extends Error {
+  constructor() {
+    super("OAuth completion refused: the completing subject is not the one that started the authorization");
+    this.name = "OAuthSubjectMismatchError";
+  }
+};
+function assertSubject(bound, completer) {
+  if (bound !== completer) throw new OAuthSubjectMismatchError();
+}
+function grantedScopes(scope) {
+  return (scope ?? "").split(/[\s,]+/).filter((s) => s.length > 0);
+}
 var PENDING_GRANT_TTL_MS = 10 * 60 * 1e3;
 var InMemoryPendingGrantStore = class {
   constructor() {
@@ -4057,7 +4082,7 @@ function installPendingGrantStore(store) {
 var OAuthIntegration = class extends BaseIntegration {
   constructor(config) {
     super(config);
-    /** Maps state token -> provider for pending MOCK authorization flows */
+    /** Maps state token -> pending MOCK authorization */
     this.states = /* @__PURE__ */ new Map();
     /** Maps access token -> token set (mock backend) */
     this.tokens = /* @__PURE__ */ new Map();
@@ -4086,12 +4111,25 @@ var OAuthIntegration = class extends BaseIntegration {
     try {
       let data;
       switch (action) {
-        case "authorize":
-          data = await this.executeWithRetry(() => this.real ? this.oidcAuthorize(params) : this.authorize(params));
+        case "authorize": {
+          const input = {
+            provider: params.provider,
+            scopes: params.scopes,
+            redirectUri: params.redirectUri,
+            ...params.subject === void 0 ? {} : { subject: params.subject }
+          };
+          data = await this.executeWithRetry(() => this.startAuthorization(input));
           break;
-        case "token":
-          data = await this.executeWithRetry(() => this.real ? this.oidcToken(params) : this.token(params));
+        }
+        case "token": {
+          const input = {
+            code: params.code,
+            state: params.state,
+            ...params.subject === void 0 ? {} : { subject: params.subject }
+          };
+          data = await this.executeWithRetry(() => this.completeAuthorization(input));
           break;
+        }
         case "refresh":
           data = await this.executeWithRetry(() => this.real ? this.oidcRefresh(params) : this.refresh(params));
           break;
@@ -4113,6 +4151,14 @@ var OAuthIntegration = class extends BaseIntegration {
       return this.handleError(action, error);
     }
   }
+  /** Build the provider authorization URL and hold the pending grant (PKCE verifier, subject) under `state`. */
+  async startAuthorization(input) {
+    return this.real ? this.oidcAuthorize(input) : this.authorize(input);
+  }
+  /** Consume the pending grant once and exchange the code; throws on an unknown, replayed or expired `state`. */
+  async completeAuthorization(input) {
+    return this.real ? this.oidcToken(input) : this.token(input);
+  }
   // ---------------------------------------------------------------------------
   // OIDC backend (openid-client)
   // ---------------------------------------------------------------------------
@@ -4128,6 +4174,19 @@ var OAuthIntegration = class extends BaseIntegration {
     return issuer;
   }
   async configurationFor(provider) {
+    const metadata = PROVIDER_SERVER_METADATA[provider];
+    if (metadata && !this.config.env.OIDC_ISSUER_URL) {
+      const cached2 = this.discovered.get(metadata.issuer);
+      if (cached2) return cached2;
+      const configuration2 = new oidc.Configuration(
+        metadata,
+        this.config.env.OAUTH_CLIENT_ID,
+        this.config.env.OAUTH_CLIENT_SECRET,
+        oidc.ClientSecretPost(this.config.env.OAUTH_CLIENT_SECRET)
+      );
+      this.discovered.set(metadata.issuer, configuration2);
+      return configuration2;
+    }
     const issuer = this.issuerFor(provider);
     const cached = this.discovered.get(issuer);
     if (cached) return cached;
@@ -4139,10 +4198,9 @@ var OAuthIntegration = class extends BaseIntegration {
     this.discovered.set(issuer, configuration);
     return configuration;
   }
-  async oidcAuthorize(params) {
-    const provider = params.provider;
-    const scopes = params.scopes;
-    const redirectUri = params.redirectUri || this.config.env.OAUTH_REDIRECT_URI;
+  async oidcAuthorize(input) {
+    const { provider, scopes, subject } = input;
+    const redirectUri = input.redirectUri || this.config.env.OAUTH_REDIRECT_URI;
     const configuration = await this.configurationFor(provider);
     const state = oidc.randomState();
     const pkceVerifier = oidc.randomPKCECodeVerifier();
@@ -4159,17 +4217,21 @@ var OAuthIntegration = class extends BaseIntegration {
       parameters.prompt = "consent";
     }
     const authUrl = oidc.buildAuthorizationUrl(configuration, parameters);
-    await this.pendingStore().put(state, { provider, redirectUri, pkceVerifier }, PENDING_GRANT_TTL_MS);
+    await this.pendingStore().put(
+      state,
+      { provider, redirectUri, pkceVerifier, ...subject === void 0 ? {} : { subject } },
+      PENDING_GRANT_TTL_MS
+    );
     void this.pendingStore().sweep();
     return { authUrl: authUrl.toString(), state };
   }
-  async oidcToken(params) {
-    const code = params.code;
-    const state = params.state;
+  async oidcToken(input) {
+    const { code, state } = input;
     const pendingAuth = await this.pendingStore().take(state);
     if (!pendingAuth) {
-      throw new Error(`Invalid or expired state token: ${state}`);
+      throw new OAuthGrantNotFoundError(state);
     }
+    assertSubject(pendingAuth.subject, input.subject);
     const configuration = await this.configurationFor(pendingAuth.provider);
     const callbackUrl = new URL(pendingAuth.redirectUri);
     callbackUrl.searchParams.set("code", code);
@@ -4186,7 +4248,9 @@ var OAuthIntegration = class extends BaseIntegration {
       accessToken: tokens.access_token,
       refreshToken: tokens.refresh_token ?? "",
       expiresIn: tokens.expires_in ?? 3600,
-      tokenType: "bearer"
+      tokenType: "bearer",
+      scope: grantedScopes(tokens.scope),
+      ...pendingAuth.subject === void 0 ? {} : { subject: pendingAuth.subject }
     };
   }
   async oidcRefresh(params) {
@@ -4249,13 +4313,11 @@ var OAuthIntegration = class extends BaseIntegration {
   // ---------------------------------------------------------------------------
   // Mock backend actions
   // ---------------------------------------------------------------------------
-  async authorize(params) {
-    const provider = params.provider;
-    const scopes = params.scopes;
-    const redirectUri = params.redirectUri;
+  async authorize(input) {
+    const { provider, scopes, redirectUri, subject } = input;
     this.logger.debug("OAuth AUTHORIZE", { provider, scopes: scopes.join(", "), redirectUri });
     const state = this.generateToken(16);
-    this.states.set(state, provider);
+    this.states.set(state, { provider, scopes, ...subject === void 0 ? {} : { subject } });
     const baseUrl = PROVIDER_AUTH_URLS[provider];
     const queryParams = new URLSearchParams({
       response_type: "code",
@@ -4267,17 +4329,15 @@ var OAuthIntegration = class extends BaseIntegration {
     const authUrl = `${baseUrl}?${queryParams.toString()}`;
     return { authUrl, state };
   }
-  async token(params) {
-    const code = params.code;
-    const state = params.state;
+  async token(input) {
+    const { code, state } = input;
     this.logger.debug("OAuth TOKEN", { code, state });
-    const provider = this.states.get(state);
-    if (!provider) {
-      throw new Error(
-        `Invalid or expired state token: ${state}`
-      );
+    const pending = this.states.get(state);
+    if (!pending) {
+      throw new OAuthGrantNotFoundError(state);
     }
     this.states.delete(state);
+    assertSubject(pending.subject, input.subject);
     const accessToken = this.generateToken(32);
     const refreshToken = this.generateToken(32);
     const expiresIn = 3600;
@@ -4289,8 +4349,15 @@ var OAuthIntegration = class extends BaseIntegration {
     this.tokens.set(accessToken, tokenSet);
     this.refreshIndex.set(refreshToken, accessToken);
     const sub = this.generateToken(8);
-    this.sessions.set(accessToken, this.generateMockUser(provider, sub));
-    return { accessToken, refreshToken, expiresIn, tokenType: "bearer" };
+    this.sessions.set(accessToken, this.generateMockUser(pending.provider, sub));
+    return {
+      accessToken,
+      refreshToken,
+      expiresIn,
+      tokenType: "bearer",
+      scope: pending.scopes,
+      ...pending.subject === void 0 ? {} : { subject: pending.subject }
+    };
   }
   async refresh(params) {
     const refreshToken = params.refreshToken;
@@ -5758,6 +5825,6 @@ var RiggerIntegration = class extends BaseIntegration {
 };
 registerIntegration("rigger", RiggerIntegration);
 
-export { AccountingIntegration, ArxivIntegration, BankingIntegration, BaseIntegration, CLIIntegration, CREDENTIALS_FILE_ENV, CREDENTIAL_ENTITY_TYPE, CREDENTIAL_MASTER_KEY_ENV, CalendarIntegration, ConsoleLogger, CredentialStore, CredentialsIntegration, DatabaseIntegration, DeepAgentIntegration, DockerIntegration, DriveIntegration, EmailIntegration, EsignIntegration, FileCredentialPersistence, GitHubIntegration, IconifyIntegration, InMemoryPendingGrantStore, IntegrationError, IntegrationFactory, LLMIntegration, MLIntegration, MetaAdsIntegration, OAuthIntegration, OtelIntegration, PushIntegration, QueueIntegration, RedisIntegration, RiggerIntegration, StorageIntegration, StripeIntegration, TwilioIntegration, UnknownActionError, WebhookIntegration, WikimediaIntegration, YouTubeIntegration, allCredentialEnvVars, allHookDeclarations, assertReadOnlySelect, declaredCredentialEnvVars, getActiveFactory, getInstalledCredentialStore, getIntegration, getIntegrationFactory, getRegisteredIntegrations, googleCalendarHookProvider, installActiveFactory, installCredentialStore, installPendingGrantStore, isKnownIntegration, parseCalendarPushNotification, registerIntegration, registeredHookProviders, resetIntegrationFactory, resolveCredentialRef, serviceHooks, uninstallCredentialStore, validateParams, verifyAndParseStripeEvent, withRetry };
+export { AccountingIntegration, ArxivIntegration, BankingIntegration, BaseIntegration, CLIIntegration, CREDENTIALS_FILE_ENV, CREDENTIAL_ENTITY_TYPE, CREDENTIAL_MASTER_KEY_ENV, CalendarIntegration, ConsoleLogger, CredentialStore, CredentialsIntegration, DatabaseIntegration, DeepAgentIntegration, DockerIntegration, DriveIntegration, EmailIntegration, EsignIntegration, FileCredentialPersistence, GitHubIntegration, IconifyIntegration, InMemoryPendingGrantStore, IntegrationError, IntegrationFactory, LLMIntegration, MLIntegration, MetaAdsIntegration, OAuthGrantNotFoundError, OAuthIntegration, OAuthSubjectMismatchError, OtelIntegration, PushIntegration, QueueIntegration, RedisIntegration, RiggerIntegration, StorageIntegration, StripeIntegration, TwilioIntegration, UnknownActionError, WebhookIntegration, WikimediaIntegration, YouTubeIntegration, allCredentialEnvVars, allHookDeclarations, assertReadOnlySelect, declaredCredentialEnvVars, getActiveFactory, getInstalledCredentialStore, getIntegration, getIntegrationFactory, getRegisteredIntegrations, googleCalendarHookProvider, installActiveFactory, installCredentialStore, installPendingGrantStore, isKnownIntegration, parseCalendarPushNotification, registerIntegration, registeredHookProviders, resetIntegrationFactory, resolveCredentialRef, serviceHooks, uninstallCredentialStore, validateParams, verifyAndParseStripeEvent, withRetry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map