@executor-js/sdk 0.0.1 → 0.0.2

package/dist/oauth-discovery.d.ts

@@ -0,0 +1,138 @@
+import { Effect, Schema } from "effect";
+import { createPkceCodeChallenge } from "./oauth-helpers";
+declare const OAuthDiscoveryError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "OAuthDiscoveryError";
+} & Readonly<A>;
+/** Separate tag from `OAuth2Error` so callers can distinguish discovery
+ *  / DCR failures (happen once, before any token round-trips) from
+ *  token-endpoint failures. A plugin's refresh path should never have
+ *  to inspect error messages to tell "metadata drifted, re-discover"
+ *  apart from "refresh token is no longer honoured". */
+export declare class OAuthDiscoveryError extends OAuthDiscoveryError_base<{
+    readonly message: string;
+    readonly status?: number;
+    readonly cause?: unknown;
+}> {
+}
+export declare const OAuthProtectedResourceMetadataSchema: Schema.Struct<{
+    readonly resource: Schema.optional<Schema.String>;
+    readonly authorization_servers: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly scopes_supported: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly bearer_methods_supported: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly resource_documentation: Schema.optional<Schema.String>;
+}>;
+export type OAuthProtectedResourceMetadata = typeof OAuthProtectedResourceMetadataSchema.Type;
+export declare const OAuthAuthorizationServerMetadataSchema: Schema.Struct<{
+    readonly issuer: Schema.String;
+    readonly authorization_endpoint: Schema.String;
+    readonly token_endpoint: Schema.String;
+    readonly registration_endpoint: Schema.optional<Schema.String>;
+    readonly scopes_supported: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly response_types_supported: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly grant_types_supported: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly code_challenge_methods_supported: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly token_endpoint_auth_methods_supported: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly revocation_endpoint: Schema.optional<Schema.String>;
+    readonly introspection_endpoint: Schema.optional<Schema.String>;
+    readonly userinfo_endpoint: Schema.optional<Schema.String>;
+    readonly id_token_signing_alg_values_supported: Schema.optional<Schema.$Array<Schema.String>>;
+}>;
+export type OAuthAuthorizationServerMetadata = typeof OAuthAuthorizationServerMetadataSchema.Type;
+export type DynamicClientMetadata = {
+    readonly client_name?: string;
+    readonly redirect_uris: readonly string[];
+    readonly grant_types?: readonly string[];
+    readonly response_types?: readonly string[];
+    readonly token_endpoint_auth_method?: "none" | "client_secret_basic" | "client_secret_post" | "private_key_jwt";
+    readonly scope?: string;
+    readonly application_type?: "web" | "native";
+    readonly client_uri?: string;
+    readonly logo_uri?: string;
+    readonly contacts?: readonly string[];
+    readonly software_id?: string;
+    readonly software_version?: string;
+    /** Escape hatch for provider-specific extensions; merged last. */
+    readonly extra?: Readonly<Record<string, unknown>>;
+};
+export declare const OAuthClientInformationSchema: Schema.Struct<{
+    readonly client_id: Schema.String;
+    readonly client_secret: Schema.optional<Schema.String>;
+    readonly client_id_issued_at: Schema.optional<Schema.Number>;
+    readonly client_secret_expires_at: Schema.optional<Schema.Number>;
+    readonly registration_access_token: Schema.optional<Schema.String>;
+    readonly registration_client_uri: Schema.optional<Schema.String>;
+    readonly token_endpoint_auth_method: Schema.optional<Schema.String>;
+    readonly grant_types: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly response_types: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly redirect_uris: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly client_name: Schema.optional<Schema.String>;
+    readonly scope: Schema.optional<Schema.String>;
+}>;
+export type OAuthClientInformation = typeof OAuthClientInformationSchema.Type;
+export interface DiscoveryRequestOptions {
+    /** Injected for tests. Defaults to the global `fetch`. */
+    readonly fetch?: typeof fetch;
+    /** Abort the request after this many ms. Default 20000. */
+    readonly timeoutMs?: number;
+    /** Send `MCP-Protocol-Version: <value>` on every request. Harmless
+     *  for non-MCP servers; required by the MCP authorization spec. */
+    readonly mcpProtocolVersion?: string;
+    /** Credentials needed to reach the protected resource itself. These
+     *  are intentionally used only for resource-side probes, never for
+     *  authorization-server metadata, DCR, authorization, or token calls. */
+    readonly resourceHeaders?: Readonly<Record<string, string>>;
+    readonly resourceQueryParams?: Readonly<Record<string, string>>;
+}
+export declare const discoverProtectedResourceMetadata: (resourceUrl: string, options?: DiscoveryRequestOptions) => Effect.Effect<{
+    readonly metadataUrl: string;
+    readonly metadata: OAuthProtectedResourceMetadata;
+} | null, OAuthDiscoveryError>;
+export declare const discoverAuthorizationServerMetadata: (issuer: string, options?: DiscoveryRequestOptions) => Effect.Effect<{
+    readonly metadataUrl: string;
+    readonly metadata: OAuthAuthorizationServerMetadata;
+} | null, OAuthDiscoveryError>;
+export interface RegisterDynamicClientInput {
+    readonly registrationEndpoint: string;
+    readonly metadata: DynamicClientMetadata;
+    readonly initialAccessToken?: string | null;
+}
+export declare const registerDynamicClient: (input: RegisterDynamicClientInput, options?: DiscoveryRequestOptions) => Effect.Effect<OAuthClientInformation, OAuthDiscoveryError>;
+export interface DynamicAuthorizationState {
+    readonly resourceMetadata: OAuthProtectedResourceMetadata | null;
+    readonly resourceMetadataUrl: string | null;
+    readonly authorizationServerUrl: string;
+    readonly authorizationServerMetadataUrl: string;
+    readonly authorizationServerMetadata: OAuthAuthorizationServerMetadata;
+    readonly clientInformation: OAuthClientInformation;
+}
+export interface DynamicAuthorizationStartResult {
+    readonly authorizationUrl: string;
+    readonly codeVerifier: string;
+    readonly state: DynamicAuthorizationState;
+}
+export interface BeginDynamicAuthorizationInput {
+    readonly endpoint: string;
+    readonly redirectUrl: string;
+    /** RFC 6749 `state` — callers typically pass a per-session random id. */
+    readonly state: string;
+    /** Defaults: `redirect_uris=[redirectUrl]`, `token_endpoint_auth_method="none"`
+     *  (public client + PKCE). */
+    readonly clientMetadata?: Partial<DynamicClientMetadata>;
+    /** Scopes to request. Defaults to `scopes_supported`; omitted if
+     *  neither is set. */
+    readonly scopes?: readonly string[];
+    /** Pre-existing state from a previous flow. When provided, the
+     *  matching discovery / DCR step is skipped so multi-user sign-ins
+     *  against the same source don't re-pay those costs. */
+    readonly previousState?: {
+        readonly authorizationServerUrl?: string | null;
+        readonly authorizationServerMetadata?: OAuthAuthorizationServerMetadata | null;
+        readonly authorizationServerMetadataUrl?: string | null;
+        readonly resourceMetadata?: OAuthProtectedResourceMetadata | null;
+        readonly resourceMetadataUrl?: string | null;
+        readonly clientInformation?: OAuthClientInformation | null;
+    };
+}
+export declare const beginDynamicAuthorization: (input: BeginDynamicAuthorizationInput, options?: DiscoveryRequestOptions) => Effect.Effect<DynamicAuthorizationStartResult, OAuthDiscoveryError>;
+export { createPkceCodeChallenge };
+//# sourceMappingURL=oauth-discovery.d.ts.map

package/dist/oauth-discovery.d.ts.map

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

package/dist/oauth-discovery.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=oauth-discovery.test.d.ts.map

package/dist/oauth-discovery.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-discovery.test.d.ts","sourceRoot":"","sources":["../src/oauth-discovery.test.ts"],"names":[],"mappings":""}

package/dist/oauth-helpers.d.ts

@@ -0,0 +1,89 @@
+import { Effect } from "effect";
+declare const OAuth2Error_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "OAuth2Error";
+} & Readonly<A>;
+export declare class OAuth2Error extends OAuth2Error_base<{
+    readonly message: string;
+    /**
+     * RFC 6749 §5.2 error code, when the token endpoint returned one
+     * (`invalid_grant`, `invalid_client`, `unauthorized_client`, ...).
+     * Callers use this to distinguish terminal failures (a refresh token
+     * the AS no longer honours → re-auth required) from transient ones.
+     */
+    readonly error?: string;
+    readonly cause?: unknown;
+}> {
+}
+export type OAuth2TokenResponse = {
+    readonly access_token: string;
+    readonly token_type?: string;
+    readonly refresh_token?: string;
+    readonly expires_in?: number;
+    readonly scope?: string;
+};
+/** Refresh tokens this many ms before expiry to avoid mid-request expiration. */
+export declare const OAUTH2_REFRESH_SKEW_MS = 60000;
+/** Default token-endpoint timeout. */
+export declare const OAUTH2_DEFAULT_TIMEOUT_MS = 20000;
+export declare const createPkceCodeVerifier: () => string;
+export declare const createPkceCodeChallenge: (verifier: string) => Promise<string>;
+export type BuildAuthorizationUrlInput = {
+    readonly authorizationUrl: string;
+    readonly clientId: string;
+    readonly redirectUrl: string;
+    readonly scopes: readonly string[];
+    readonly state: string;
+    /** Pre-computed base64url S256 challenge (from `createPkceCodeChallenge`). */
+    readonly codeChallenge: string;
+    /** Separator between scopes. RFC 6749 says space; some providers use comma. */
+    readonly scopeSeparator?: string;
+    /** Provider-specific extras (e.g. Google's `access_type=offline`). */
+    readonly extraParams?: Readonly<Record<string, string>>;
+};
+/** Build an RFC 6749 §4.1.1 authorization URL. Sync; pre-computed
+ *  challenge lets this stay out of the Promise world. */
+export declare const buildAuthorizationUrl: (input: BuildAuthorizationUrlInput) => string;
+export type ClientAuthMethod = "body" | "basic";
+export type ExchangeAuthorizationCodeInput = {
+    readonly tokenUrl: string;
+    readonly issuerUrl?: string | null;
+    readonly clientId: string;
+    readonly clientSecret?: string | null;
+    readonly redirectUrl: string;
+    readonly codeVerifier: string;
+    readonly code: string;
+    readonly clientAuth?: ClientAuthMethod;
+    readonly idTokenSigningAlgValuesSupported?: readonly string[];
+    readonly timeoutMs?: number;
+};
+export declare const exchangeAuthorizationCode: (input: ExchangeAuthorizationCodeInput) => Effect.Effect<OAuth2TokenResponse, OAuth2Error>;
+export type ExchangeClientCredentialsInput = {
+    readonly tokenUrl: string;
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly scopes?: readonly string[];
+    readonly scopeSeparator?: string;
+    readonly clientAuth?: ClientAuthMethod;
+    readonly timeoutMs?: number;
+};
+export declare const exchangeClientCredentials: (input: ExchangeClientCredentialsInput) => Effect.Effect<OAuth2TokenResponse, OAuth2Error>;
+export type RefreshAccessTokenInput = {
+    readonly tokenUrl: string;
+    readonly issuerUrl?: string | null;
+    readonly clientId: string;
+    readonly clientSecret?: string | null;
+    readonly refreshToken: string;
+    readonly scopes?: readonly string[];
+    readonly scopeSeparator?: string;
+    readonly clientAuth?: ClientAuthMethod;
+    readonly idTokenSigningAlgValuesSupported?: readonly string[];
+    readonly timeoutMs?: number;
+};
+export declare const refreshAccessToken: (input: RefreshAccessTokenInput) => Effect.Effect<OAuth2TokenResponse, OAuth2Error>;
+export declare const shouldRefreshToken: (input: {
+    readonly expiresAt: number | null;
+    readonly now?: number;
+    readonly skewMs?: number;
+}) => boolean;
+export {};
+//# sourceMappingURL=oauth-helpers.d.ts.map

package/dist/oauth-helpers.d.ts.map

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

package/dist/oauth-helpers.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=oauth-helpers.test.d.ts.map

package/dist/oauth-helpers.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-helpers.test.d.ts","sourceRoot":"","sources":["../src/oauth-helpers.test.ts"],"names":[],"mappings":""}

package/dist/oauth-popup-types.d.ts

@@ -0,0 +1,14 @@
+/** Message type literal used to identify our popup results. */
+export declare const OAUTH_POPUP_MESSAGE_TYPE: "executor:oauth-result";
+export type OAuthPopupResult<TAuth> = ({
+    readonly type: typeof OAUTH_POPUP_MESSAGE_TYPE;
+    readonly ok: true;
+    readonly sessionId: string;
+} & TAuth) | {
+    readonly type: typeof OAUTH_POPUP_MESSAGE_TYPE;
+    readonly ok: false;
+    readonly sessionId: string | null;
+    readonly error: string;
+};
+export declare const isOAuthPopupResult: <TAuth>(value: unknown) => value is OAuthPopupResult<TAuth>;
+//# sourceMappingURL=oauth-popup-types.d.ts.map

package/dist/oauth-popup-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-popup-types.d.ts","sourceRoot":"","sources":["../src/oauth-popup-types.ts"],"names":[],"mappings":"AAQA,+DAA+D;AAC/D,eAAO,MAAM,wBAAwB,EAAG,uBAAgC,CAAC;AAEzE,MAAM,MAAM,gBAAgB,CAAC,KAAK,IAC9B,CAAC;IACC,QAAQ,CAAC,IAAI,EAAE,OAAO,wBAAwB,CAAC;IAC/C,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,GAAG,KAAK,CAAC,GACV;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,wBAAwB,CAAC;IAC/C,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AAEN,eAAO,MAAM,kBAAkB,GAAI,KAAK,EACtC,OAAO,OAAO,KACb,KAAK,IAAI,gBAAgB,CAAC,KAAK,CAG+B,CAAC"}

package/dist/oauth-service.d.ts

@@ -0,0 +1,33 @@
+import { Effect } from "effect";
+import type { DBAdapter, StorageFailure, TypedAdapter } from "@executor-js/storage-core";
+import { CreateConnectionInput, type ConnectionProvider, type ConnectionRef } from "./connections";
+import type { ConnectionProviderNotRegisteredError } from "./errors";
+import type { CoreSchema } from "./core-schema";
+import { SetSecretInput, type SecretRef } from "./secrets";
+import { type OAuthService } from "./oauth";
+export interface OAuthServiceDeps {
+    /** Typed core-schema adapter. Already scope-wrapped upstream so reads
+     *  fall through the scope stack; writes stamp the scope the caller
+     *  named (`tokenScope` on start input). */
+    readonly adapter: TypedAdapter<CoreSchema>;
+    /** Raw adapter for opening transactions — the typed one doesn't expose
+     *  `.transaction` directly. */
+    readonly rawAdapter: DBAdapter;
+    /** Resolves client-id / client-secret refs at start + refresh time.
+     *  A `null` return means "secret row is gone" and aborts the flow. */
+    readonly secretsGet: (id: string) => Effect.Effect<string | null, StorageFailure>;
+    readonly secretsSet: (input: SetSecretInput) => Effect.Effect<SecretRef, StorageFailure>;
+    /** Mints the Connection row + backing secret rows. Called from
+     *  `complete` (and from `start` for `client-credentials`). */
+    readonly connectionsCreate: (input: CreateConnectionInput) => Effect.Effect<ConnectionRef, ConnectionProviderNotRegisteredError | StorageFailure>;
+    /** Random session id generator. Tests override to make outputs
+     *  deterministic. */
+    readonly newSessionId?: () => string;
+    /** `Date.now()` substitute — tests override to drive TTL behavior. */
+    readonly now?: () => number;
+}
+export declare const makeOAuth2Service: (deps: OAuthServiceDeps) => {
+    readonly service: OAuthService;
+    readonly connectionProvider: ConnectionProvider;
+};
+//# sourceMappingURL=oauth-service.d.ts.map

package/dist/oauth-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-service.d.ts","sourceRoot":"","sources":["../src/oauth-service.ts"],"names":[],"mappings":"AAqCA,OAAO,EAAE,MAAM,EAAU,MAAM,QAAQ,CAAC;AAExC,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACd,YAAY,EACb,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAEL,qBAAqB,EAErB,KAAK,kBAAkB,EAGvB,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EACV,oCAAoC,EACrC,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAgBL,KAAK,YAAY,EAGlB,MAAM,SAAS,CAAC;AAmMjB,MAAM,WAAW,gBAAgB;IAC/B;;+CAE2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;IAC3C;mCAC+B;IAC/B,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B;0EACsE;IACtE,QAAQ,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,EAAE,cAAc,CAAC,CAAC;IAClF,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IACzF;kEAC8D;IAC9D,QAAQ,CAAC,iBAAiB,EAAE,CAC1B,KAAK,EAAE,qBAAqB,KACzB,MAAM,CAAC,MAAM,CAChB,aAAa,EACb,oCAAoC,GAAG,cAAc,CACtD,CAAC;IACF;yBACqB;IACrB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,MAAM,CAAC;IACrC,sEAAsE;IACtE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAyCD,eAAO,MAAM,iBAAiB,GAC5B,MAAM,gBAAgB,KACrB;IAAE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAA;CAq7BnF,CAAC"}

package/dist/oauth.d.ts

@@ -0,0 +1,275 @@
+import { Effect, Schema } from "effect";
+import type { StorageFailure } from "@executor-js/storage-core";
+import { ConnectionId } from "./ids";
+/** RFC 9728 + RFC 8414 + RFC 7591 + PKCE: discover protected-resource
+ *  metadata, discover the authorization server, dynamically register a
+ *  client, then PKCE-encode the authorization URL. Zero pre-configured
+ *  credentials — the user just pastes a resource URL. */
+export declare const OAuthDynamicDcrStrategy: Schema.Struct<{
+    readonly kind: Schema.Literal<"dynamic-dcr">;
+    /** Scopes to request. Defaults to whatever `scopes_supported`
+     *  advertises; caller can narrow or extend. */
+    readonly scopes: Schema.optional<Schema.$Array<Schema.String>>;
+}>;
+export type OAuthDynamicDcrStrategy = typeof OAuthDynamicDcrStrategy.Type;
+/** RFC 6749 authorization code + PKCE with pre-configured endpoints +
+ *  client_id. Used when the caller has out-of-band-registered an OAuth
+ *  app (Google via Cloud Console, GitHub via developer portal, etc.) or
+ *  when the auth-server URL is declared in an OpenAPI `securityScheme`. */
+export declare const OAuthAuthorizationCodeStrategy: Schema.Struct<{
+    readonly kind: Schema.Literal<"authorization-code">;
+    readonly authorizationEndpoint: Schema.String;
+    readonly tokenEndpoint: Schema.String;
+    /** Expected authorization-server issuer for ID token validation. Some
+     *  providers use a token endpoint host that differs from issuer, or a
+     *  path-scoped issuer such as Okta custom authorization servers. */
+    readonly issuerUrl: Schema.optional<Schema.NullOr<Schema.String>>;
+    /** Secret id holding the `client_id`. Using a secret row rather than
+     *  an inline string so the value lives at the scope where the caller
+     *  configured it and shadowing behaves consistently. */
+    readonly clientIdSecretId: Schema.String;
+    /** Secret id for `client_secret`. Null for public clients using
+     *  PKCE without a confidential secret. */
+    readonly clientSecretSecretId: Schema.NullOr<Schema.String>;
+    readonly scopes: Schema.$Array<Schema.String>;
+    /** Separator between scopes. RFC 6749 says space; some providers
+     *  (GitHub classic) use comma. */
+    readonly scopeSeparator: Schema.optional<Schema.String>;
+    /** Provider-specific params injected at authorization URL build time
+     *  (Google's `access_type=offline`, `prompt=consent`, ...). */
+    readonly extraAuthorizationParams: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    /** `"body"` (default) sends client creds in the form body; `"basic"`
+     *  uses HTTP Basic auth. Stripe-style servers require basic. */
+    readonly clientAuth: Schema.optional<Schema.Literals<readonly ["body", "basic"]>>;
+}>;
+export type OAuthAuthorizationCodeStrategy = typeof OAuthAuthorizationCodeStrategy.Type;
+/** RFC 6749 §4.4 client credentials — no user redirect, no PKCE. Used
+ *  for server-to-server integrations where the plugin has both
+ *  `client_id` and `client_secret` and the server will mint tokens
+ *  directly on the token endpoint. */
+export declare const OAuthClientCredentialsStrategy: Schema.Struct<{
+    readonly kind: Schema.Literal<"client-credentials">;
+    readonly tokenEndpoint: Schema.String;
+    readonly clientIdSecretId: Schema.String;
+    readonly clientSecretSecretId: Schema.String;
+    readonly scopes: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly scopeSeparator: Schema.optional<Schema.String>;
+    readonly clientAuth: Schema.optional<Schema.Literals<readonly ["body", "basic"]>>;
+}>;
+export type OAuthClientCredentialsStrategy = typeof OAuthClientCredentialsStrategy.Type;
+/** Tagged union of every start-time strategy shape. A new strategy (e.g.
+ *  device-code) is added here; the service's start/complete routes on
+ *  `kind`. */
+export declare const OAuthStrategy: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"dynamic-dcr">;
+    /** Scopes to request. Defaults to whatever `scopes_supported`
+     *  advertises; caller can narrow or extend. */
+    readonly scopes: Schema.optional<Schema.$Array<Schema.String>>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"authorization-code">;
+    readonly authorizationEndpoint: Schema.String;
+    readonly tokenEndpoint: Schema.String;
+    /** Expected authorization-server issuer for ID token validation. Some
+     *  providers use a token endpoint host that differs from issuer, or a
+     *  path-scoped issuer such as Okta custom authorization servers. */
+    readonly issuerUrl: Schema.optional<Schema.NullOr<Schema.String>>;
+    /** Secret id holding the `client_id`. Using a secret row rather than
+     *  an inline string so the value lives at the scope where the caller
+     *  configured it and shadowing behaves consistently. */
+    readonly clientIdSecretId: Schema.String;
+    /** Secret id for `client_secret`. Null for public clients using
+     *  PKCE without a confidential secret. */
+    readonly clientSecretSecretId: Schema.NullOr<Schema.String>;
+    readonly scopes: Schema.$Array<Schema.String>;
+    /** Separator between scopes. RFC 6749 says space; some providers
+     *  (GitHub classic) use comma. */
+    readonly scopeSeparator: Schema.optional<Schema.String>;
+    /** Provider-specific params injected at authorization URL build time
+     *  (Google's `access_type=offline`, `prompt=consent`, ...). */
+    readonly extraAuthorizationParams: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    /** `"body"` (default) sends client creds in the form body; `"basic"`
+     *  uses HTTP Basic auth. Stripe-style servers require basic. */
+    readonly clientAuth: Schema.optional<Schema.Literals<readonly ["body", "basic"]>>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"client-credentials">;
+    readonly tokenEndpoint: Schema.String;
+    readonly clientIdSecretId: Schema.String;
+    readonly clientSecretSecretId: Schema.String;
+    readonly scopes: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly scopeSeparator: Schema.optional<Schema.String>;
+    readonly clientAuth: Schema.optional<Schema.Literals<readonly ["body", "basic"]>>;
+}>]>;
+export type OAuthStrategy = typeof OAuthStrategy.Type;
+/** Discriminator mirrors `OAuthStrategy["kind"]`. Refresh reads
+ *  `tokenEndpoint` + `clientAuth` + client id/secret refs directly and
+ *  never re-runs discovery. */
+export declare const OAuthProviderState: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"dynamic-dcr">;
+    readonly tokenEndpoint: Schema.String;
+    readonly issuerUrl: Schema.optional<Schema.NullOr<Schema.String>>;
+    readonly authorizationServerUrl: Schema.optional<Schema.NullOr<Schema.String>>;
+    readonly authorizationServerMetadataUrl: Schema.NullOr<Schema.String>;
+    readonly idTokenSigningAlgValuesSupported: Schema.optional<Schema.$Array<Schema.String>>;
+    /** DCR-minted client_id. Embedded inline (not a secret) — DCR
+     *  clients are public-ish by design; the secret part (if the AS
+     *  issued one) is a separate secret row. */
+    readonly clientId: Schema.String;
+    readonly clientSecretSecretId: Schema.NullOr<Schema.String>;
+    readonly clientAuth: Schema.Literals<readonly ["body", "basic"]>;
+    readonly scopes: Schema.withDecodingDefaultType<Schema.$Array<Schema.String>>;
+    readonly scopeSeparator: Schema.optional<Schema.String>;
+    readonly scope: Schema.NullOr<Schema.String>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"authorization-code">;
+    readonly tokenEndpoint: Schema.String;
+    readonly issuerUrl: Schema.optional<Schema.NullOr<Schema.String>>;
+    readonly clientIdSecretId: Schema.String;
+    readonly clientSecretSecretId: Schema.NullOr<Schema.String>;
+    readonly clientAuth: Schema.Literals<readonly ["body", "basic"]>;
+    readonly scopes: Schema.withDecodingDefaultType<Schema.$Array<Schema.String>>;
+    readonly scopeSeparator: Schema.optional<Schema.String>;
+    readonly scope: Schema.NullOr<Schema.String>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"client-credentials">;
+    readonly tokenEndpoint: Schema.String;
+    readonly clientIdSecretId: Schema.String;
+    readonly clientSecretSecretId: Schema.String;
+    readonly scopes: Schema.$Array<Schema.String>;
+    readonly scopeSeparator: Schema.optional<Schema.String>;
+    readonly clientAuth: Schema.Literals<readonly ["body", "basic"]>;
+    readonly scope: Schema.NullOr<Schema.String>;
+}>]>;
+export type OAuthProviderState = typeof OAuthProviderState.Type;
+/** The canonical refresh handler key. Every OAuth2-minted connection
+ *  registers under this single value; the handler switches on
+ *  `providerState.kind`. Historical per-plugin keys (`mcp:oauth2`,
+ *  `openapi:oauth2`, `google-discovery:google`) are aliased to this
+ *  during migration. */
+export declare const OAUTH2_PROVIDER_KEY: "oauth2";
+export interface OAuthProbeInput {
+    readonly endpoint: string;
+    readonly headers?: Record<string, string>;
+    readonly queryParams?: Record<string, string>;
+}
+export interface OAuthProbeResult {
+    /** RFC 9728 resource metadata the server advertises, if any. */
+    readonly resourceMetadata: Record<string, unknown> | null;
+    readonly resourceMetadataUrl: string | null;
+    /** RFC 8414 / OIDC metadata for the authorization server tied to the
+     *  resource, if the server advertised one and we could fetch it. */
+    readonly authorizationServerMetadata: Record<string, unknown> | null;
+    readonly authorizationServerMetadataUrl: string | null;
+    readonly authorizationServerUrl: string | null;
+    /** True iff the AS advertises `registration_endpoint` and
+     *  `token_endpoint_auth_methods_supported` includes `"none"` (public
+     *  client + PKCE). A `false` value here doesn't mean OAuth is
+     *  unavailable — just that the dynamic-DCR strategy can't run and the
+     *  caller must fall back to `authorization-code` with user-supplied
+     *  client credentials. */
+    readonly supportsDynamicRegistration: boolean;
+    /** True iff an unauth POST to the endpoint responded with `401` and
+     *  an MCP-shaped `WWW-Authenticate: Bearer` challenge (RFC 6750).
+     *  MCP-only signal; non-MCP OAuth-protected APIs usually encode auth
+     *  failures inside their own protocol envelope and never surface
+     *  this flag. */
+    readonly isBearerChallengeEndpoint: boolean;
+}
+export interface OAuthStartInput {
+    /** Resource URL the caller wants a token for. For `dynamic-dcr` this
+     *  is the probe target; for `authorization-code` it's stored only so
+     *  the UI can display "signed in to X." */
+    readonly endpoint: string;
+    readonly headers?: Record<string, string>;
+    readonly queryParams?: Record<string, string>;
+    /** Pre-decided `Connection.id`. Writing it before the flow starts
+     *  lets callers stamp `{kind:"oauth2", connectionId}` onto a source
+     *  row atomically with the start call. Convention:
+     *  `${pluginId}-oauth2-${namespace}`. */
+    readonly connectionId: string;
+    /** Scope where the resulting `Connection` + its backing secrets
+     *  land. Innermost scope for per-user sign-ins. */
+    readonly tokenScope: string;
+    /** Redirect URL the authorization server will bounce back to. For
+     *  strategies that don't redirect (`client-credentials`) pass a
+     *  placeholder; it's persisted but unused. */
+    readonly redirectUrl: string;
+    readonly strategy: OAuthStrategy;
+    /** Which plugin is initiating the flow. Persisted on the session +
+     *  stamped on the minted Connection's identity label for UI. */
+    readonly pluginId: string;
+    /** Optional human label for the minted Connection, e.g. "Spotify OAuth". */
+    readonly identityLabel?: string;
+}
+export interface OAuthStartResult {
+    readonly sessionId: string;
+    /** Present for user-interactive strategies. `null` for
+     *  `client-credentials`, which skips straight to a Connection write
+     *  inside `start`. */
+    readonly authorizationUrl: string | null;
+    /** For strategies that don't redirect, the Connection has already
+     *  been minted. Surfaced so callers can stamp the source row
+     *  immediately without waiting on a completion callback. */
+    readonly completedConnection: {
+        readonly connectionId: string;
+    } | null;
+}
+export interface OAuthCompleteInput {
+    /** RFC 6749 `state` parameter — maps to a session row id. */
+    readonly state: string;
+    readonly code?: string;
+    /** RFC 6749 `error` parameter — set when the AS redirected back with
+     *  a failure. The service surfaces this as a tagged error. */
+    readonly error?: string;
+}
+export interface OAuthCompleteResult {
+    readonly connectionId: string;
+    readonly expiresAt: number | null;
+    readonly scope: string | null;
+}
+declare const OAuthProbeError_base: Schema.Class<OAuthProbeError, Schema.TaggedStruct<"OAuthProbeError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class OAuthProbeError extends OAuthProbeError_base {
+    static annotations: {
+        httpApiStatus: number;
+    };
+}
+declare const OAuthStartError_base: Schema.Class<OAuthStartError, Schema.TaggedStruct<"OAuthStartError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class OAuthStartError extends OAuthStartError_base {
+    static annotations: {
+        httpApiStatus: number;
+    };
+}
+declare const OAuthCompleteError_base: Schema.Class<OAuthCompleteError, Schema.TaggedStruct<"OAuthCompleteError", {
+    readonly message: Schema.String;
+    /** RFC 6749 §5.2 error code, when the token endpoint returned one.
+     *  Callers distinguish terminal failures (`invalid_grant` ⇒
+     *  re-auth required) from transient ones. */
+    readonly code: Schema.optional<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+export declare class OAuthCompleteError extends OAuthCompleteError_base {
+    static annotations: {
+        httpApiStatus: number;
+    };
+}
+declare const OAuthSessionNotFoundError_base: Schema.Class<OAuthSessionNotFoundError, Schema.TaggedStruct<"OAuthSessionNotFoundError", {
+    readonly sessionId: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class OAuthSessionNotFoundError extends OAuthSessionNotFoundError_base {
+    static annotations: {
+        httpApiStatus: number;
+    };
+}
+export interface OAuthService {
+    readonly probe: (input: OAuthProbeInput) => Effect.Effect<OAuthProbeResult, OAuthProbeError>;
+    readonly start: (input: OAuthStartInput) => Effect.Effect<OAuthStartResult, OAuthStartError | StorageFailure>;
+    readonly complete: (input: OAuthCompleteInput) => Effect.Effect<OAuthCompleteResult, OAuthCompleteError | OAuthSessionNotFoundError | StorageFailure>;
+    /** Drop an in-flight session without completing — used when the
+     *  user cancels the popup or the source is deleted mid-onboarding. */
+    readonly cancel: (sessionId: string, tokenScope?: string) => Effect.Effect<void, StorageFailure>;
+}
+export declare const OAUTH2_SESSION_TTL_MS: number;
+export { ConnectionId };
+//# sourceMappingURL=oauth.d.ts.map

package/dist/oauth.d.ts.map

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