@powerhousedao/reactor-workflow 6.2.3-dev.82 → 6.2.3-dev.84

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -341,6 +341,22 @@ The engine's own blocks are the built-in piece `@powerhousedao/piece-core`, in
341
341
  or `false` by its result.
342
342
  - The triggers are fed by the host: `reactor/schedule.ts`, `reactor/webhook.ts`
343
343
  and the `fire` mutation. Their hooks are never called.
344
+ - `manual` takes optional `inputs`, shaped after Activepieces' web form
345
+ fields: per field a payload key (`name`), `displayName`, `type` (`text`,
346
+ `text_area`, `number`, `toggle`, `date`, `dropdown`, `json`), `required`,
347
+ `defaultValue` and `description`. A dropdown's `options` is one per line,
348
+ either a bare value or `Label = value` (split at the first `=` with a space
349
+ on each side); the Run form shows the label and the payload carries the
350
+ value, which is what the fire checks. Its `defaultValue` is a value, or an
351
+ option's label. A caller's
352
+ `fire` checks its payload against the published trigger's inputs
353
+ (`coerceManualPayload` in `@powerhousedao/pieces-framework/workflow`):
354
+ defaults fill missing fields, values are coerced (`"42"` to 42, `"true"` to
355
+ true, a date to ISO 8601), keys no field declares pass through, and a
356
+ missing required field or a bad value refuses the fire with a
357
+ `ManualPayloadError` naming each field, before any run row. Reruns and
358
+ other trigger kinds are not checked. The inputs also type
359
+ `{{trigger.payload.<name>}}` in the expression picker.
344
360
 
345
361
  ## Block resolution
346
362
 
@@ -728,7 +744,7 @@ more trusted than one that arrived inside a package.
728
744
 
729
745
  ## OAuth2 connections
730
746
 
731
- An OAUTH2 connection brings its own app. `startOAuth` (`reactor/oauth.ts`)
747
+ An OAUTH2 connection brings its own app, or names a publisher's (below). `startOAuth` (`reactor/oauth.ts`)
732
748
  builds the provider's authorize URL from the piece's `PieceAuth.OAuth2`
733
749
  (`{prop}` placeholders filled from the connection's config, PKCE when the
734
750
  piece asks for it) and records a pending attempt in the `oauth` namespace,
@@ -743,6 +759,62 @@ Token requests leave from the reactor process, so they are held to the egress
743
759
  policy pieces run under: `https` to a public address, or an address named in
744
760
  `PH_WORKFLOWS_EGRESS_ALLOW_ADDRESSES`, over `http` too.
745
761
 
762
+ ### Publisher apps and the relay
763
+
764
+ A connection may instead name a publisher's app (`oauth_app` in its config),
765
+ configured once per host in `workflows.oauthApps`:
766
+
767
+ ```json
768
+ {
769
+ "id": "sektar-google",
770
+ "clients": { "desktop": "desktop.json", "web": "web.json" },
771
+ "relay": {
772
+ "clientId": "<the web client's id>",
773
+ "redirectUri": "https://sektar.io/api/oauth/callback",
774
+ "tokenUrl": "https://sektar.io/api/oauth/token"
775
+ }
776
+ }
777
+ ```
778
+
779
+ `clients` are the provider's client files (relative to the config file). A
780
+ host may pass the same list programmatically (Switchboard's
781
+ `workflows.oauthApps` option), which wins over the config file. `startOAuth`
782
+ picks, for the redirect it is given (`oauthSignInFor` in
783
+ `reactor/oauth-apps.ts`, also answered by the `oauthSignIn` query as
784
+ `DESKTOP | WEB | RELAY | NONE`):
785
+
786
+ - a loopback callback: the **desktop** client, always with PKCE;
787
+ - any other callback: the **web** client when the host has its file, sending
788
+ the provider the host's own callback, exactly as without a relay;
789
+ - any other callback, no web client file, a `relay`: the **relay**;
790
+ - otherwise none, and `startOAuth` refuses.
791
+
792
+ The relay is a token broker the publisher runs and that alone holds the web
793
+ client's secret. Its one `redirectUri` is registered with the provider, so
794
+ hosts whose own callback is not (a cloud environment per hostname) need no
795
+ provider change. A relayed sign-in:
796
+
797
+ - sends the provider `redirect_uri` = `relay.redirectUri`, `client_id` =
798
+ `relay.clientId`, PKCE whatever the piece says;
799
+ - sets `state` to `<nonce>.<base64url(own callback)>`: the nonce is the usual
800
+ base64url of 32 random bytes (no dots), the callback the redirect the host
801
+ passed, base64url without padding. The relay forwards the provider's
802
+ parameters unchanged to that callback, which runs `completeOAuth` as ever;
803
+ the whole string is the attempt's key;
804
+ - records the attempt with `relay.redirectUri` and `relay.tokenUrl` and no
805
+ client secret ref (`client_secret_ref` null);
806
+ - exchanges the code at `relay.tokenUrl` with `client_id`, `code_verifier`
807
+ and `redirect_uri`, no secret; the broker adds it and answers with the
808
+ provider's token response;
809
+ - stores the token set with `relayed: true`, its `token_url` the relay's: every
810
+ refresh posts `grant_type=refresh_token`, the refresh token and `client_id`
811
+ there, again without a secret, whatever the config says by then.
812
+
813
+ A relay needs a `clientId` and two absolute `https` URLs without credentials;
814
+ otherwise it is dropped with a warning and the app kept without it. The
815
+ relay's token URL is held to the egress policy above, which a public `https`
816
+ host passes.
817
+
746
818
  ## Files and attachments
747
819
 
748
820
  Bytes never cross the worker's IPC channel; host and worker share
package/dist/index.d.ts CHANGED
@@ -65,21 +65,61 @@ interface OAuthAppClient {
65
65
  interface OAuthAppRegistry {
66
66
  client(appId: string, kind: OAuthClientKind): OAuthAppClient | undefined;
67
67
  clients(appId: string): OAuthAppClient[];
68
+ /** The app's relay, or undefined when it has none. */
69
+ relay(appId: string): OAuthAppRelay | undefined;
68
70
  }
69
71
  /** One app as a host configures it: per client kind, the provider's client file. */
70
72
  interface OAuthAppDefinition {
71
73
  id: string;
72
74
  /** Paths to the provider's downloaded client files (Google's client_secret_*.json). */
73
75
  clients: Partial<Record<OAuthClientKind, string>>;
76
+ /**
77
+ * The broker a web sign-in goes through when the host has no web client
78
+ * file. Absent, a web sign-in needs the web client.
79
+ */
80
+ relay?: OAuthAppRelay;
81
+ }
82
+ /**
83
+ * A token broker for an app's web client: the provider sends the browser to
84
+ * `redirectUri`, which forwards to the callback the state names; `tokenUrl`
85
+ * takes the code exchange and every refresh, with `clientId` and no secret.
86
+ */
87
+ interface OAuthAppRelay {
88
+ clientId: string;
89
+ redirectUri: string;
90
+ tokenUrl: string;
74
91
  }
92
+ /**
93
+ * A relay as configured, or the reason it cannot be used: it needs a client
94
+ * id and two absolute https URLs without credentials.
95
+ */
96
+ export declare function parseRelay(raw: unknown): OAuthAppRelay | string;
75
97
  export declare class StaticOAuthAppRegistry implements OAuthAppRegistry {
76
98
  private readonly entries;
77
- constructor(entries: readonly OAuthAppClient[]);
99
+ private readonly relays;
100
+ constructor(entries: readonly OAuthAppClient[], relays?: ReadonlyMap<string, OAuthAppRelay>);
78
101
  client(appId: string, kind: OAuthClientKind): OAuthAppClient | undefined;
79
102
  clients(appId: string): OAuthAppClient[];
103
+ relay(appId: string): OAuthAppRelay | undefined;
80
104
  }
81
105
  /** Desktop for a callback to this machine, web for one the provider reaches over the internet. */
82
106
  export declare function clientKindFor(redirectUri: string): OAuthClientKind;
107
+ /**
108
+ * How this host signs in with a publisher's app for a callback: the
109
+ * desktop client for one to this machine; else the web client when the host
110
+ * has its file; else the app's relay; else not at all.
111
+ */
112
+ type OAuthSignIn = {
113
+ mode: "desktop" | "web";
114
+ client: OAuthAppClient;
115
+ } | {
116
+ mode: "relay";
117
+ relay: OAuthAppRelay;
118
+ } | {
119
+ mode: "none";
120
+ kind: OAuthClientKind;
121
+ };
122
+ export declare function oauthSignInFor(apps: OAuthAppRegistry, appId: string, redirectUri: string): OAuthSignIn;
83
123
  /**
84
124
  * Config key the runtime writes after a sign-in: the scopes the provider
85
125
  * granted (its token response's `scope`, else the ones asked for). A
@@ -103,11 +143,14 @@ export declare function parseClientFile(text: string): {
103
143
  * Reads each configured client file and keeps its secret in the store under a
104
144
  * fixed label: created the first time, rotated when the file changed, left
105
145
  * alone otherwise. A client whose file cannot be read is skipped with the
106
- * reason, so one bad file does not take the others down.
146
+ * reason, so one bad file does not take the others down. A relay without a
147
+ * client id or with a URL that is not absolute https is dropped with the
148
+ * reason.
107
149
  */
108
150
  export declare function loadOAuthApps(definitions: readonly OAuthAppDefinition[], store: SecretStore, options?: {
109
151
  read?: (path: string) => Promise<string>;
110
152
  onSkip?: (appId: string, kind: OAuthClientKind, reason: string) => void;
153
+ onRelayDropped?: (appId: string, reason: string) => void;
111
154
  }): Promise<StaticOAuthAppRegistry>;
112
155
  //#endregion
113
156
  //#region src/reactor/run-scope.d.ts
@@ -19634,6 +19677,7 @@ export declare class WorkflowRuntimeService {
19634
19677
  checkConnection(connectionId: string, ctx?: WorkflowCaller): Promise<ConnectionCheckResult>;
19635
19678
  private connectionDocument;
19636
19679
  private checkConnectionDocument;
19680
+ oauthSignInMode(appId: string, redirectUri: string): Promise<OAuthSignIn["mode"]>;
19637
19681
  startOAuth(connectionId: string, ctx: WorkflowCaller | undefined, options: {
19638
19682
  redirectUri: string;
19639
19683
  returnUrl?: string;
@@ -19930,6 +19974,6 @@ interface WebhookPayload {
19930
19974
  body: unknown;
19931
19975
  }
19932
19976
  //#endregion
19933
- export { type AcquireSingletonOptions, type AttachmentClientLike, type AttachmentReadRequest, type BlockResolutionRecord, CORE_PIECE_NAME, type ConnectionCheckResult, type ConnectionSummary, type HostIdentity, type OAuthAppClient, type OAuthAppDefinition, type OAuthAppRegistry, type OAuthAttemptStatus, type OAuthAttemptView, type OAuthClientKind, type OAuthStart, type OutputTree, type OutputTreeNode, type PersistedRunResult, PieceRegistry, type PieceStoreRow, type PieceTriggerBinding, type RunPage, type RunRecord, type RunRow, type RunsArgs, type RunsPageArgs, type ScheduleTriggerBinding, type StepExecutionRow, type StepTestResult, TELEMETRY_SCOPE, type TriggerBinding, type TriggerDedupeRow, type TriggerStateRow, type WebhookConfig, type WebhookPayload, type WorkflowAccessOptions, type WorkflowCaller, type WorkflowHealth, type WorkflowHealthReader, type WorkflowRuntimeDB, type WorkflowRuntimeHostDeps, type WorkflowSingletonLease, type WorkflowSingletonLoss, type WorkflowTelemetryOptions, packagePieces };
19977
+ export { type AcquireSingletonOptions, type AttachmentClientLike, type AttachmentReadRequest, type BlockResolutionRecord, CORE_PIECE_NAME, type ConnectionCheckResult, type ConnectionSummary, type HostIdentity, type OAuthAppClient, type OAuthAppDefinition, type OAuthAppRegistry, type OAuthAppRelay, type OAuthAttemptStatus, type OAuthAttemptView, type OAuthClientKind, type OAuthSignIn, type OAuthStart, type OutputTree, type OutputTreeNode, type PersistedRunResult, PieceRegistry, type PieceStoreRow, type PieceTriggerBinding, type RunPage, type RunRecord, type RunRow, type RunsArgs, type RunsPageArgs, type ScheduleTriggerBinding, type StepExecutionRow, type StepTestResult, TELEMETRY_SCOPE, type TriggerBinding, type TriggerDedupeRow, type TriggerStateRow, type WebhookConfig, type WebhookPayload, type WorkflowAccessOptions, type WorkflowCaller, type WorkflowHealth, type WorkflowHealthReader, type WorkflowRuntimeDB, type WorkflowRuntimeHostDeps, type WorkflowSingletonLease, type WorkflowSingletonLoss, type WorkflowTelemetryOptions, packagePieces };
19934
19978
  export {};
19935
19979
  //# sourceMappingURL=index.d.ts.map