@marktiderman/genesis-connect 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,307 @@
+import { Secrets } from './secrets.js';
+export { DeriveSecretKeyOptions, KEY_ID, Keyring, KeyringInput, Salt, SecretError, SecretErrorCode, SecretsOptions, WebCryptoKey, createSecrets, deriveSecretKey, isSecretError, openWithKey, parseKeyring, sealWithKey, secretKeyBytes } from './secrets.js';
+
+/**
+ * An OAuth 2.0 provider is plain data: where to send the person, where to
+ * trade codes and refresh tokens, where to revoke. Google is built in; any
+ * other authorization-code provider is an object of the same shape.
+ */
+interface OAuthProvider {
+    /** A short id, used in the default cookie name and the state key's derivation: `"google"`. */
+    readonly id: string;
+    /** The authorization endpoint the browser is sent to. */
+    readonly authorizeUrl: string;
+    /** The token endpoint (code and refresh-token grants). */
+    readonly tokenUrl: string;
+    /** The revocation endpoint (RFC 7009), when the provider has one. */
+    readonly revokeUrl?: string | undefined;
+    /** Scopes asked for when neither the connector nor `start` names any. */
+    readonly defaultScopes?: readonly string[] | undefined;
+    /**
+     * Extra authorization parameters, such as Google's `access_type=offline`
+     * and `prompt=consent` (which is what makes it send a refresh token).
+     */
+    readonly authorizeParams?: Readonly<Record<string, string>> | undefined;
+    /**
+     * How the client authenticates at the token endpoint: in the form body
+     * (`client_secret_post`, the default) or with HTTP Basic (`client_secret_basic`).
+     */
+    readonly tokenAuth?: "client_secret_post" | "client_secret_basic" | undefined;
+    /** Whether the revocation request also carries the client's credentials. Default false. */
+    readonly revokeWithClientAuth?: boolean | undefined;
+    /** How the provider joins scopes. Default a space (RFC 6749). */
+    readonly scopeSeparator?: string | undefined;
+    /**
+     * Shorthand scopes the provider answers with their full name, so the
+     * granted-scope check compares like with like: Google grants `email` as
+     * `https://www.googleapis.com/auth/userinfo.email`. Both what is asked
+     * for and what is granted are mapped through it.
+     */
+    readonly scopeAliases?: Readonly<Record<string, string>> | undefined;
+}
+/** Google's OAuth 2.0 endpoints, asking for offline access (a refresh token) every time. */
+declare const googleProvider: OAuthProvider;
+/** Google scopes apps commonly connect with. Prefer the narrowest. */
+declare const GOOGLE_SCOPES: {
+    /** OpenID Connect: an ID token naming the account. */
+    readonly openid: "openid";
+    /** The account's email address (Google grants it as `…/auth/userinfo.email`). */
+    readonly email: "email";
+    /** The account's name and picture (granted as `…/auth/userinfo.profile`). */
+    readonly profile: "profile";
+    /** Files the person picked or created through the app, and nothing else. */
+    readonly driveFile: "https://www.googleapis.com/auth/drive.file";
+    /** Every spreadsheet the person can reach. Prefer `driveFile`. */
+    readonly spreadsheets: "https://www.googleapis.com/auth/spreadsheets";
+    /** Events on the person's calendars. */
+    readonly calendarEvents: "https://www.googleapis.com/auth/calendar.events";
+    /** Send mail as the person. */
+    readonly gmailSend: "https://www.googleapis.com/auth/gmail.send";
+};
+
+/** How a connection attempt ended, as the `connect` query parameter on the way back. */
+type ConnectResult = 
+/** Connected; the app's `store` kept the account. */
+"connected"
+/** The signed state was missing, forged or too old: start again. */
+ | "expired"
+/** The browser that came back is not the one that started (no or another cookie). */
+ | "browser"
+/** The person said no at the provider (or it sent no code). */
+ | "denied"
+/** The person unticked a scope the app needs. */
+ | "scope"
+/** The provider or the app's `store` failed. */
+ | "failed";
+/** Every result `callback` can send back with. */
+declare const CONNECT_RESULTS: readonly ConnectResult[];
+/** What went wrong outside the callback, for code to branch on. */
+type ConnectErrorCode = 
+/** The connector is set up wrong (a missing secret, a bad origin). */
+"config"
+/** A call was given something it can't use (no subject, an absolute returnTo). */
+ | "usage"
+/** The grant is gone (`invalid_grant`): access was removed. Connect again. */
+ | "revoked"
+/** The provider is down, limiting, or timed out. Worth retrying. */
+ | "unavailable"
+/** The provider refused for another reason. */
+ | "failed";
+/** A failure with a message safe to show and log: never a token, a code or a secret. */
+declare class ConnectError extends Error {
+    name: string;
+    readonly code: ConnectErrorCode;
+    readonly retryable: boolean;
+    readonly status: number | undefined;
+    readonly retryAfterSeconds: number | undefined;
+    /**
+     * Set when the provider rotated the refresh token but it could not be
+     * handed over (no `onRotate`, or `onRotate` threw): the new one, sealed to
+     * the same row. Store it in place of the old one, or the grant is lost.
+     */
+    readonly sealedRefreshToken: string | undefined;
+    constructor(code: ConnectErrorCode, message: string, options?: {
+        status?: number | undefined;
+        retryAfterSeconds?: number | undefined;
+        sealedRefreshToken?: string | undefined;
+    });
+}
+/**
+ * Whether `error` is a `ConnectError`, by its name and code rather than
+ * `instanceof`, so it also matches a copy from another bundle.
+ */
+declare function isConnectError(error: unknown): error is ConnectError;
+/** Small app data carried in the signed state. Signed, not encrypted: never put a secret in it. */
+type StateData = Readonly<Record<string, string | number | boolean | null>>;
+/** What `start` is told about this attempt. */
+interface StartOptions<D extends StateData = StateData> {
+    /**
+     * Who is connecting: the app's verified user id. Handed back to `store`.
+     * The state is signed, not encrypted, so this is readable in the sign-in
+     * URL (and by the provider): prefer an opaque id over an email address.
+     */
+    subject: string;
+    /** What the connection is for, app-defined (`"sheets"`, `"calendar"`). At most 64 characters. */
+    intent?: string | undefined;
+    /**
+     * Where to come back to: a path on the app (`"/settings/integrations"`),
+     * never a full URL. The result is added as `?connect=…`.
+     */
+    returnTo: string;
+    /** Scopes for this attempt, instead of the connector's. */
+    scopes?: readonly string[] | undefined;
+    /** Small app data to have back in `store` (a form id, a chosen file). Not secret. */
+    data?: D | undefined;
+    /** Extra authorization parameters (`login_hint`). The flow's own can't be overridden. */
+    params?: Readonly<Record<string, string>> | undefined;
+}
+/** `start`'s answer: send the browser to `url` with `setCookie` set. */
+interface StartResult {
+    /** The provider's sign-in URL. */
+    url: string;
+    /** The `Set-Cookie` header value holding the nonce and the PKCE verifier. */
+    setCookie: string;
+    /** A 303 to `url` with the cookie: for a start reached by a link or a form post. */
+    redirect(): Response;
+    /** `{ url }` as JSON with the cookie: for a start the page calls with fetch, then navigates. */
+    json(): Response;
+}
+/** What `store` is handed: the new account, its refresh token already sealed. */
+interface ConnectedAccount<D extends StateData = StateData> {
+    /** A new id for this grant (a UUID): the row to keep it under. */
+    id: string;
+    /** The associated data the refresh token is sealed to (`aad(id)`): pass it to `accessToken` and `revoke`. */
+    aad: string;
+    /** The refresh token, sealed with the keyring. Store it; it never needs opening by the app. */
+    sealedRefreshToken: string;
+    /** A fresh access token, to look the account up now (an email, a file). Don't store it. */
+    accessToken: string;
+    /** Seconds the access token is good for. */
+    expiresIn: number;
+    /** The granted scopes, as the provider joined them. */
+    scope: string;
+    /** The granted scopes. */
+    scopes: string[];
+    /** The OpenID Connect ID token, when the provider sent one (an `openid` scope). */
+    idToken?: string | undefined;
+    /** From `start`. */
+    subject: string;
+    intent: string;
+    returnTo: string;
+    data: D;
+}
+/** What `store` may add to the way back, as query parameters (a grant id to finish with). */
+type StoreResult = void | undefined | Readonly<Record<string, string>>;
+/** A safe log line: never a token, a code, a secret or a provider's error text. */
+interface ConnectLogEvent {
+    step: "callback" | "refresh" | "revoke";
+    result: ConnectResult | ConnectErrorCode | "revoked";
+    /** A short, safe reason: "token endpoint answered 400", "store threw". */
+    detail?: string | undefined;
+}
+/** Options shared by the requests the connector makes. */
+interface HttpOptions {
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof fetch | undefined;
+    /** Per request, in milliseconds. Default 10 000. */
+    timeoutMs?: number | undefined;
+}
+interface ConnectorConfig<D extends StateData = StateData> extends HttpOptions {
+    provider: OAuthProvider;
+    /** The app's OAuth client. Server side only. */
+    clientId: string;
+    clientSecret: string;
+    /** 32 random bytes, base64 (`openssl rand -base64 32`): signs the state. Not the keyring's key. */
+    stateSecret: string | Uint8Array;
+    /** Seals refresh tokens (`createSecrets(keyring, { purpose: "google-refresh-token" })`). */
+    secrets: Secrets;
+    /** The callback's path on the app (`"/api/connect/google/callback"`). Register `<origin><path>` with the provider. */
+    callbackPath: string;
+    /** Scopes asked for when `start` names none. Default the provider's `defaultScopes`. */
+    scopes?: readonly string[] | undefined;
+    /**
+     * The one origin the provider sends everyone back to (`https://app.example.com`),
+     * when the app runs on many. Without it, each request's own origin.
+     */
+    redirectOrigin?: string | undefined;
+    /**
+     * The parent domain the PKCE cookie is shared on (`example.com`), so a flow
+     * started on `team.example.com` can finish on the pinned `app.example.com`
+     * and come back to `team.example.com`. Only https origins on it are ever
+     * returned to. Leave it out to keep the cookie on one host.
+     */
+    sharedDomain?: string | undefined;
+    /** The cookie's name. Default `genesis_connect_<provider id>`. */
+    cookieName?: string | undefined;
+    /** The cookie's path. Default `callbackPath`, so it is only ever sent to the callback. */
+    cookiePath?: string | undefined;
+    /** How long the trip to the provider and back may take. Default 600 seconds, at most 3600. */
+    stateTtlSeconds?: number | undefined;
+    /** The query parameter the result comes back in. Default `"connect"`. */
+    resultParam?: string | undefined;
+    /** Where to go back to when the state can't be read (so there is no `returnTo`). Default `"/"`. */
+    fallbackPath?: string | undefined;
+    /** The associated data a grant's refresh token is sealed to. Default `<provider id>-grant:<id>`. */
+    aad?: ((id: string) => string) | undefined;
+    /** Fail with `failed` when the provider sends no refresh token. Default true. */
+    requireRefreshToken?: boolean | undefined;
+    /**
+     * Keeps the new account: the app's row, under `account.id`, for
+     * `account.subject` (the user who started). Use that, never a session read
+     * from the callback's request: the callback is a top-level navigation the
+     * provider sends, and the session there may be another one. May return
+     * query parameters for the way back. Throwing ends the attempt as `failed`.
+     */
+    store: (account: ConnectedAccount<D>, context: {
+        request: Request;
+    }) => StoreResult | Promise<StoreResult>;
+    /** Safe log lines (see `ConnectLogEvent`). */
+    log?: ((event: ConnectLogEvent) => void) | undefined;
+    /**
+     * Whether a domain is a public suffix (where a cookie would be dropped), for
+     * the `sharedDomain` check: pass a Public Suffix List lookup to cover every
+     * suffix. The built-in list only knows common hosting suffixes.
+     */
+    isPublicSuffix?: ((domain: string) => boolean) | undefined;
+    now?: (() => number) | undefined;
+    randomId?: (() => string) | undefined;
+}
+/** A fresh access token, and the refresh token again when the provider rotated it. */
+interface RefreshedToken {
+    accessToken: string;
+    expiresIn: number;
+    scope: string;
+    /** Set when the provider sent a new refresh token: store it in place of the old one. */
+    sealedRefreshToken?: string | undefined;
+}
+interface TokenCallOptions {
+    /** Aborts the request. Concurrent `accessToken` calls share one refresh: the first caller's signal aborts it. */
+    signal?: AbortSignal | undefined;
+    /**
+     * Stores the new sealed refresh token when the provider rotates it (some
+     * do on every refresh; Google does not). `accessToken` needs it for such a
+     * provider: a rotation without it throws a `usage` `ConnectError` carrying
+     * the new token on `sealedRefreshToken`, so it is never silently lost. If
+     * it throws, a `failed` `ConnectError` carries the token the same way. The
+     * access token is cached before it runs.
+     */
+    onRotate?: ((sealedRefreshToken: string) => void | Promise<void>) | undefined;
+}
+interface Connector<D extends StateData = StateData> {
+    readonly provider: OAuthProvider;
+    /** The redirect URI for a request: `<redirectOrigin or the request's origin><callbackPath>`. */
+    redirectUri(request: Request): string;
+    /** Begins a connection (see the module comment). The app checks who is signed in first. */
+    start(request: Request, options: StartOptions<D>): Promise<StartResult>;
+    /** Finishes one: always a 303 back to the app, with the result and a cleared cookie. */
+    callback(request: Request): Promise<Response>;
+    /**
+     * A fresh access token for a sealed refresh token, cached until a minute
+     * before it expires; concurrent calls for one grant share one refresh.
+     * Needs `onRotate` for providers that rotate refresh tokens.
+     */
+    accessToken(sealedRefreshToken: string, aad: string, options?: TokenCallOptions): Promise<string>;
+    /**
+     * Trades a sealed refresh token for an access token, uncached. A rotated
+     * refresh token comes back sealed on the result (and goes to `onRotate`).
+     */
+    refresh(sealedRefreshToken: string, aad: string, options?: TokenCallOptions): Promise<RefreshedToken>;
+    /**
+     * Revokes the grant at the provider and forgets its cached access token.
+     * True when it is gone (revoked now, or already); false when the provider
+     * could not be reached or has no revocation endpoint. Some providers
+     * (Google) end every token of the person's grant to this client, so call
+     * it only when the app no longer uses any.
+     */
+    revoke(sealedRefreshToken: string, aad: string, options?: {
+        signal?: AbortSignal | undefined;
+    }): Promise<boolean>;
+}
+/** Whether `origin` is exactly an https origin on `domain`, so it is safe to send the browser back to. */
+declare function isSafeReturnOrigin(origin: string, domain: string): boolean;
+/** Forgets every cached access token (tests, or after a key or client change). */
+declare function clearAccessTokenCache(): void;
+/** Sets up a connector for one provider. Checks its config now, so a mistake shows at boot. */
+declare function createConnector<D extends StateData = StateData>(config: ConnectorConfig<D>): Connector<D>;
+
+export { CONNECT_RESULTS, ConnectError, type ConnectErrorCode, type ConnectLogEvent, type ConnectResult, type ConnectedAccount, type Connector, type ConnectorConfig, GOOGLE_SCOPES, type HttpOptions, type OAuthProvider, type RefreshedToken, Secrets, type StartOptions, type StartResult, type StateData, type StoreResult, type TokenCallOptions, clearAccessTokenCache, createConnector, googleProvider, isConnectError, isSafeReturnOrigin };