@picked/app-kit 0.0.117-next.2 → 0.0.117

package/dist/cjs/client.d.ts

@@ -0,0 +1,145 @@
+import type { AdminApiRequestOptions, TadaDocumentNode } from '@picked/admin-api-client';
+import { type InstallationRef } from '@picked/app-protocol';
+/** How to read a label's `value`. */
+export type AppLabelType = 'text' | 'number' | 'boolean' | 'json';
+/** A label the app keeps for an installation, as Picked's `Label` type describes it. */
+export interface AppLabel {
+    namespace: string;
+    key: string;
+    type: AppLabelType;
+    /** The value, as a string to read through `type`; a secret label's value included. */
+    value: string;
+    /** Whether the value is kept in Vault. */
+    secret: boolean;
+    /** When the label expires, or null. */
+    expiresAt: string | null;
+    updatedAt: string;
+}
+/**
+ * A label to set, as Picked's `LabelInput` takes it. A namespace and a key are each 1-64
+ * lowercase letters, digits, underscores or hyphens; a value holds at most 64 KiB, and an
+ * installation holds at most 100 labels.
+ */
+export interface AppLabelInput {
+    namespace: string;
+    key: string;
+    type: AppLabelType;
+    /** The value, as a string that parses as `type`. */
+    value?: string;
+    /** What to add to a `number` label, in place of `value`. */
+    increment?: number;
+    /** Seconds until the label expires, from 1 to 31536000. */
+    expiresIn?: number;
+    /** Writes only when no live label has this namespace and key. */
+    onlyIfAbsent?: boolean;
+    /** Keeps the value in Vault: a `text` or `json` value, with no `increment` or `onlyIfAbsent`. */
+    secret?: boolean;
+}
+/** A label to remove, as Picked's `LabelIdentifierInput` takes it. */
+export interface AppLabelIdentifier {
+    namespace: string;
+    key: string;
+    /** Removes the label only while it holds this value. */
+    ifValue?: string;
+}
+/** A refused label write, as Picked's `LabelUserError` describes it. */
+export interface AppLabelUserError {
+    field: string[];
+    message: string;
+    code: string;
+}
+/** A label write Picked refused, carrying its user errors. */
+export declare class LabelWriteError extends Error {
+    readonly userErrors: readonly AppLabelUserError[];
+    /**
+     * Builds the error from Picked's user errors.
+     *
+     * @param {readonly AppLabelUserError[]} userErrors - Why Picked refused the write.
+     * @example new LabelWriteError([{ field: ['labels', '0', 'key'], message: 'Key is invalid.', code: 'KEY_INVALID' }])
+     */
+    constructor(userErrors: readonly AppLabelUserError[]);
+}
+/** The labels an app keeps for one installation in Picked, which the installation owns. */
+export interface InstallationLabels {
+    /** Every live label, secret values included. */
+    list: () => Promise<AppLabel[]>;
+    /** One live label, or undefined when none has the namespace and key. */
+    get: (namespace: string, key: string) => Promise<AppLabel | undefined>;
+    /**
+     * Creates or replaces labels, as `labelsSet` does, throwing {@link LabelWriteError} when
+     * Picked refuses one. `skipped` holds the live labels an `onlyIfAbsent` label left in place.
+     */
+    set: (labels: readonly AppLabelInput[], options?: {
+        atomic?: boolean;
+    }) => Promise<{
+        labels: AppLabel[];
+        skipped: AppLabel[];
+    }>;
+    /** Removes labels, as `labelsDelete` does, returning the ids removed. */
+    delete: (labels: readonly AppLabelIdentifier[]) => Promise<string[]>;
+}
+/** Calls Picked as one installation. */
+export interface InstallationClient {
+    /** The installation's labels. */
+    labels: InstallationLabels;
+    /**
+     * A short-lived token carrying the installation's scopes: the one Picked sent with the
+     * request being answered, or one minted with an app assertion, which Picked grants an app with
+     * offline access, or one answering a dashboard user's session. Renewed before it expires.
+     */
+    token: () => Promise<string>;
+    /**
+     * Runs a typed document with the installation's token and returns its `data`. Build the
+     * document with `graphql` from `@picked/admin-api-client`.
+     *
+     * @throws {Error} An `AdminApiResponseError` when Picked answers with GraphQL errors, and a
+     *   plain `Error` on a network failure, a timeout, or a response without GraphQL errors.
+     */
+    request: <Result, Variables extends Record<string, unknown>>(document: TadaDocumentNode<Result, Variables>, variables: Variables, options?: AdminApiRequestOptions) => Promise<Result>;
+}
+/** Where and as whom an installation client calls Picked. */
+export interface InstallationClientOptions {
+    /** The Picked API origin, as the request from Picked names it in `apiUrl`. */
+    apiUrl: string;
+    /** The installation. */
+    installationId: string;
+    /** The app's Ed25519 private key, as the base64 of its PKCS#8 DER or a PKCS#8 PEM. */
+    privateKey: string;
+    /** A token Picked sent with the request being answered, used until it nears expiry. */
+    token?: string;
+    /** When `token` expires. */
+    tokenExpiresAt?: string;
+    /**
+     * The session token of the dashboard user a page request comes from, which lets an app
+     * without offline access mint a token while it answers that user.
+     */
+    sessionToken?: string;
+    /** The fetch to send with; the global one by default. */
+    fetch?: typeof fetch;
+}
+/**
+ * Builds a client that calls Picked as one installation.
+ *
+ * @param {InstallationClientOptions} options - Where and as whom.
+ * @returns {InstallationClient} The client.
+ * @example createInstallationClient({ ...event, privateKey })
+ */
+export declare function createInstallationClient(options: InstallationClientOptions): InstallationClient;
+/**
+ * Builds the client for the installation a request names: with the token Picked sent, and for a
+ * page request, the session token the frame forwarded.
+ *
+ * @param {Pick<InstallationRef, 'apiUrl' | 'installationId' | 'token' | 'tokenExpiresAt'>} ref - The installation, as the request names it.
+ * @param {object} options - As whom and how.
+ * @param {string} options.privateKey - The app's private key.
+ * @param {string | null} [options.sessionToken] - The session token of a page request.
+ * @param {typeof fetch} [options.fetch] - The fetch to send with.
+ * @returns {InstallationClient} The client.
+ * @example installationClientFor(event, { privateKey: environment.privateKey })
+ */
+export declare function installationClientFor(ref: Pick<InstallationRef, 'apiUrl' | 'installationId' | 'token' | 'tokenExpiresAt'>, options: {
+    privateKey: string;
+    sessionToken?: string | null;
+    fetch?: typeof fetch;
+}): InstallationClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

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

package/dist/cjs/frame.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @file The handshake between an app's iframe and the dashboard hosting it.
+ *
+ * The frame posts `picked:ready`; the dashboard answers `picked:context` with where the
+ * frame renders and a session token the frame forwards to its own server. The frame can
+ * post `picked:resize` to set its height. Each `picked:ready` gets a context with a new session
+ * token, which `keepConnected` uses to renew the token before it expires.
+ */
+import type { AppSlotLocation } from '@picked/app-protocol';
+/** What the dashboard tells a frame. */
+export interface FrameContext {
+    installationId: string;
+    organizationId: string;
+    organizationSlug: string;
+    projectId: string;
+    /** The slot the frame renders in. */
+    location: AppSlotLocation;
+    /** The installation's pinned app version. */
+    appVersion: number;
+    /** A short-lived token asserting the user and installation; verify it with `readSession`. */
+    sessionToken: string;
+    /** The dashboard's colour scheme. */
+    theme: 'light' | 'dark';
+}
+/** A message the frame posts to the dashboard. */
+export type FrameToHostMessage = {
+    type: 'picked:ready';
+} | {
+    type: 'picked:resize';
+    height: number;
+};
+/** A message the dashboard posts to the frame. */
+export interface HostToFrameMessage {
+    type: 'picked:context';
+    context: FrameContext;
+}
+/**
+ * Connects to the dashboard and resolves with the frame's context. Call once on load. It
+ * works only in a page the Picked dashboard frames: it rejects in a top-level window, and
+ * accepts the context only from the frame's parent window on the dashboard's origin.
+ *
+ * @param {object} [options] - Connection options.
+ * @param {string} [options.dashboardOrigin] - The dashboard origin to accept and post to; the referrer's when absent.
+ * @returns {Promise<FrameContext>} Where the frame renders and who is looking.
+ * @example const context = await connect()
+ */
+export declare function connect(options?: {
+    dashboardOrigin?: string;
+}): Promise<FrameContext>;
+/** A connection to the dashboard that renews its session token before the token expires. */
+export interface FrameConnection {
+    /**
+     * Returns the newest context the dashboard sent. Read it for each request and each
+     * `authorizeInPopup`, so they carry a session token that has not expired.
+     */
+    context: () => FrameContext;
+    /** Stops renewing the session token. */
+    stop: () => void;
+}
+/**
+ * Connects to the dashboard as `connect` does, then asks the dashboard for a new context two
+ * minutes before each session token expires and at most four minutes after the last one. It
+ * checks the clock every 15 seconds and when the frame regains focus or visibility, and asks
+ * again 15 seconds after a renewal the dashboard leaves unanswered for 10 seconds. Call once
+ * on load, in place of `connect`.
+ *
+ * @param {object} [options] - Connection options.
+ * @param {string} [options.dashboardOrigin] - The dashboard origin to accept and post to; the referrer's when absent.
+ * @returns {Promise<FrameConnection>} The connection, once the dashboard sends the first context.
+ * @example const connection = await keepConnected()
+ */
+export declare function keepConnected(options?: {
+    dashboardOrigin?: string;
+}): Promise<FrameConnection>;
+/**
+ * Sets the frame's height in the dashboard.
+ *
+ * @param {number} height - The height in pixels.
+ * @returns {void}
+ * @example resize(document.body.scrollHeight)
+ */
+export declare function resize(height: number): void;
+/**
+ * Keeps the frame's height matched to its content.
+ *
+ * @returns {() => void} Stops observing.
+ * @example const stop = autoResize()
+ */
+export declare function autoResize(): () => void;
+/** How an authorization the frame opened in a popup ended. */
+export interface AuthorizationResult {
+    ok: boolean;
+    message: string;
+}
+/** What the frame starts an authorization with. */
+export interface AuthorizationRequest {
+    /** The session token from the frame's context, which the popup's start request carries. */
+    sessionToken: string;
+    /** What the app's `/oauth/start` hands its `authorize` as `params`, such as a data centre. */
+    params?: unknown;
+    /**
+     * Reads whether the app now holds the connection, answering the message to show when it
+     * does and null when it does not. Once the popup reads as closed without reporting back,
+     * the frame asks it every second for thirty seconds and settles on the first message.
+     */
+    connected?: () => Promise<string | null>;
+}
+/**
+ * Runs an OAuth authorization in a popup. Call it from a click handler: the popup opens at
+ * once on the app's `/oauth/start`, which asks for the session, and this frame answers that
+ * popup alone with the session token and params. It accepts messages only from that popup, on
+ * the app's own origin. The start binds the authorization to the browser with a cookie and
+ * goes on to the provider. The promise settles when the app's
+ * callback page reports back, or once the popup reads as closed and this frame has focus. A
+ * popup a provider's `Cross-Origin-Opener-Policy` separates from this frame reads as closed
+ * while the user may still be connecting in it, so the frame waits for the user to come back,
+ * then asks `connected` until the app holds the connection the popup saves.
+ *
+ * @param {AuthorizationRequest} request - The session token and the start's params.
+ * @returns {Promise<AuthorizationResult>} How the authorization ended.
+ * @example button.onclick = async () => show(await authorizeInPopup({ sessionToken: context.sessionToken }))
+ */
+export declare function authorizeInPopup(request: AuthorizationRequest): Promise<AuthorizationResult>;
+//# sourceMappingURL=frame.d.ts.map

package/dist/cjs/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../src/frame.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAE3D,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,MAAM,CAAA;IACtB,cAAc,EAAE,MAAM,CAAA;IACtB,gBAAgB,EAAE,MAAM,CAAA;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,qCAAqC;IACrC,QAAQ,EAAE,eAAe,CAAA;IACzB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAA;IAClB,6FAA6F;IAC7F,YAAY,EAAE,MAAM,CAAA;IACpB,qCAAqC;IACrC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAA;CACxB;AAED,kDAAkD;AAClD,MAAM,MAAM,kBAAkB,GAC5B;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtE,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,CAAA;IACtB,OAAO,EAAE,YAAY,CAAA;CACtB;AAqFD;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAKzF;AAsED,4FAA4F;AAC5F,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,EAAE,MAAM,YAAY,CAAA;IAC3B,wCAAwC;IACxC,IAAI,EAAE,MAAM,IAAI,CAAA;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAA;CAAO,GACzC,OAAO,CAAC,eAAe,CAAC,CAoC1B;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,MAAM,IAAI,CAKvC;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,mDAAmD;AACnD,MAAM,WAAW,oBAAoB;IACnC,2FAA2F;IAC3F,YAAY,EAAE,MAAM,CAAA;IACpB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CACzC;AAoCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA6D5F"}

package/dist/cjs/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file `@picked/app-kit`: the app manifest and the protocol Picked speaks to apps, re-exported
+ * from `@picked/app-protocol`.
+ *
+ * `@picked/app-kit/server` builds an app's endpoint, `@picked/app-kit/node` serves it, and
+ * `@picked/app-kit/frame` runs inside a dashboard slot's iframe.
+ */
+export * from '@picked/app-protocol';
+export type { FrameContext, FrameToHostMessage, HostToFrameMessage } from './frame.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,sBAAsB,CAAA;AACpC,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA"}

package/dist/cjs/link.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @file The dashboard link that opens the installation a label names, for an app to send a
+ * person from its own site back to the right project in Picked.
+ */
+/**
+ * Tells whether a value has the shape of an app ID.
+ *
+ * @param {string} value - The value.
+ * @returns {boolean} Whether it is `app_` and lowercase letters and digits.
+ * @example isAppId('app_k3v9x2m1q8zt') // true
+ */
+export declare function isAppId(value: string): boolean;
+/** What a link to an installation names. */
+export interface InstallationLink {
+    /** The dashboard's origin, such as `https://app.picked.app`. A path on it is ignored. */
+    dashboardOrigin: string;
+    /**
+     * The app's ID on that dashboard's Picked, such as `app_k3v9x2m1q8zt`, which
+     * `picked app deploy` prints. Each Picked environment gives the app its own ID.
+     */
+    appId: string;
+    /** The namespace of a plain label the app keeps on the installation. */
+    namespace: string;
+    /** The label's key within its namespace. */
+    key: string;
+    /** The value the installation's label holds. */
+    value: string;
+}
+/**
+ * Builds the dashboard URL that opens the installation of an app holding a plain label with a
+ * value: `/apps/<app ID>/open?label=<namespace>.<key>&value=<value>`. The dashboard opens the
+ * one installation the signed-in person can see, or offers a choice of several. A secret label
+ * never matches.
+ *
+ * @param {InstallationLink} link - The dashboard, app, label and value.
+ * @returns {string} The URL.
+ * @throws {TypeError} When the app ID, namespace or key is not one Picked holds, or the origin is not a URL.
+ * @example installationLinkUrl({ dashboardOrigin: 'https://app.picked.app', appId: 'app_k3v9x2m1q8zt', namespace: 'vercel', key: 'configuration-id', value: 'icfg_123' })
+ */
+export declare function installationLinkUrl(link: InstallationLink): string;
+//# sourceMappingURL=link.d.ts.map

package/dist/cjs/link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/link.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9C;AAKD,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,yFAAyF;IACzF,eAAe,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAA;IACjB,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAA;IACX,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAUlE"}

package/dist/cjs/node.d.ts

@@ -0,0 +1,19 @@
+import type { Server } from 'node:http';
+/**
+ * Serves a handler on a port, logging each request's method, path and status.
+ *
+ * @param {(request: Request) => Promise<Response>} handler - The handler.
+ * @param {number} port - The port.
+ * @returns {Server} The listening server.
+ * @example serve(createAppHandler(options), 4100)
+ */
+export declare function serve(handler: (request: Request) => Promise<Response>, port: number): Server;
+/**
+ * Answers with the browser build of `@picked/app-kit/frame`, for an app's pages to import as
+ * `/app-kit/frame.js`.
+ *
+ * @returns {Promise<Response>} The script.
+ * @example if (path === '/app-kit/frame.js') return frameScript()
+ */
+export declare function frameScript(): Promise<Response>;
+//# sourceMappingURL=node.d.ts.map

package/dist/cjs/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/node.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAmB,MAAM,EAAkB,MAAM,WAAW,CAAA;AA0DxE;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAgB5F;AAGD;;;;;;GAMG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC,CAGrD"}

package/dist/cjs/oauth.d.ts

@@ -0,0 +1,128 @@
+/**
+ * @file OAuth authorization-code helpers for apps that connect an installation to a third
+ * party. The popup starts at the app's `/oauth/start`, which takes the dashboard session from
+ * the frame that opened it, sets a cookie holding a nonce, and sends the browser to the
+ * provider with a sealed `state` carrying the installation and that nonce. The provider's
+ * callback completes only in the browser whose cookie holds the state's nonce, and its page
+ * tells the frame how it went.
+ */
+import { type PublicKeySet, type SessionClaims } from '@picked/app-protocol';
+/** The message the callback page posts to the frame that opened it. */
+export declare const OAUTH_RESULT_MESSAGE = "picked-app:oauth-result";
+/** The message the start page posts to its opener once it can take the session. */
+export declare const OAUTH_START_READY_MESSAGE = "picked-app:oauth-start-ready";
+/** The message the opener answers the start page with: the session token and the start's params. */
+export declare const OAUTH_START_MESSAGE = "picked-app:oauth-start";
+/** The path an app serves the popup's start page (`GET`) and its start request (`POST`) at. */
+export declare const OAUTH_START_PATH = "/oauth/start";
+/** What the `state` parameter carries through the provider. */
+export interface OAuthState {
+    /** The installation being connected. */
+    installationId: string;
+    /** The Picked API the installation calls back. */
+    apiUrl: string;
+    /** Which connection this is, for an app with more than one provider or data centre. */
+    connection: string;
+    /**
+     * The session token of the dashboard user who started the connection, with which the
+     * callback mints a token to save it.
+     */
+    sessionToken: string;
+    /** Expiry, in unix seconds. */
+    exp: number;
+    /** The value of the cookie the start set in the browser that began the authorization. */
+    nonce: string;
+}
+/**
+ * Renders the page a provider's callback answers with. It posts the result to the frame that
+ * opened the popup, on the app's own origin, and closes. A popup whose opener is gone, as a
+ * provider's `Cross-Origin-Opener-Policy` can leave it, stays open showing the result.
+ *
+ * @param {object} result - How the authorization went.
+ * @param {boolean} result.ok - Whether the connection was saved.
+ * @param {string} result.message - What to tell the user.
+ * @returns {string} The page's HTML.
+ * @example oauthCallbackPage({ ok: true, message: 'Connected' })
+ */
+export declare function oauthCallbackPage(result: {
+    ok: boolean;
+    message: string;
+}): string;
+/**
+ * Renders the page the popup opens at. It tells the frame that opened it that it is ready,
+ * takes the session token and params that frame answers with, from that frame alone, and
+ * posts them to its own path. That answer sets the binding cookie and names the provider's
+ * URL, which the page goes to; a refusal goes to the frame as the result.
+ *
+ * @returns {string} The page's HTML.
+ * @example oauthStartPage()
+ */
+export declare function oauthStartPage(): string;
+/** An authorization the popup asked to start. */
+export interface AuthorizationStart {
+    /** The verified session of the dashboard user starting it. */
+    session: SessionClaims;
+    /** The raw session token, which an installation client passes on as `sessionToken`. */
+    sessionToken: string;
+    /** What the app's page passed `authorizeInPopup` as `params`, or null. */
+    params: unknown;
+    /**
+     * Seals the `state` for a connection of the session's installation, carrying the session
+     * token and the nonce of the cookie this start sets.
+     */
+    state: (connection: string) => Promise<string>;
+}
+/** What `startAuthorization` is given. */
+export interface StartAuthorizationOptions {
+    /** The app's private key, from which the state's key derives. */
+    privateKey: string;
+    /** Picked's public keys, which sign session tokens. */
+    pickedKeys: PublicKeySet;
+    /**
+     * Builds the provider's authorization URL with a `state` from `start.state`, or answers a
+     * refusal, which goes back to the frame and sets no cookie.
+     */
+    authorize: (start: AuthorizationStart) => Promise<string | Response>;
+}
+/**
+ * Answers the app's `/oauth/start`. `GET` serves the popup's page. `POST`, which that page
+ * sends with the session token as `Authorization: Bearer <token>` and the params as its JSON
+ * body, verifies the session, sets the binding cookie to a fresh nonce, and answers
+ * `{ url }`: the provider's URL `authorize` builds.
+ *
+ * @param {Request} request - The request to `/oauth/start`.
+ * @param {StartAuthorizationOptions} options - The app's keys and its provider's URL.
+ * @returns {Promise<Response>} The page, the provider's URL, or a refusal.
+ * @example if (pathname === OAUTH_START_PATH) return startAuthorization(request, { privateKey, pickedKeys, authorize })
+ */
+export declare function startAuthorization(request: Request, options: StartAuthorizationOptions): Promise<Response>;
+/** A provider's callback in the browser that started the authorization. */
+export interface OAuthCallback {
+    /** The state the start sealed. */
+    state: OAuthState;
+    /** The callback URL, carrying the provider's `code` or `error`. */
+    url: URL;
+}
+/** What `finishAuthorization` is given. */
+export interface FinishAuthorizationOptions {
+    /** The app's private key, from which the state's key derives. */
+    privateKey: string;
+    /** Exchanges the code and saves the connection, answering what the popup reports. */
+    complete: (callback: OAuthCallback) => Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+}
+/**
+ * Answers a provider's callback. It refuses a forged, changed or expired state, and a state
+ * whose nonce differs from the binding cookie the request carries, leaving that cookie in
+ * place. Otherwise it clears the cookie, so the callback completes once, and answers the page
+ * reporting what `complete` returns.
+ *
+ * @param {Request} request - The callback request.
+ * @param {FinishAuthorizationOptions} options - The app's key and its completion.
+ * @returns {Promise<Response>} The callback page.
+ * @example if (pathname === '/oauth/callback') return finishAuthorization(request, { privateKey, complete })
+ */
+export declare function finishAuthorization(request: Request, options: FinishAuthorizationOptions): Promise<Response>;
+//# sourceMappingURL=oauth.d.ts.map

package/dist/cjs/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/oauth.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAA;AAK7B,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,4BAA4B,CAAA;AAE7D,mFAAmF;AACnF,eAAO,MAAM,yBAAyB,iCAAiC,CAAA;AAEvE,oGAAoG;AACpG,eAAO,MAAM,mBAAmB,2BAA2B,CAAA;AAE3D,+FAA+F;AAC/F,eAAO,MAAM,gBAAgB,iBAAiB,CAAA;AAE9C,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAA;IACtB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAA;IACd,uFAAuF;IACvF,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAA;CACd;AAwHD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAkBlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,IAAI,MAAM,CA0CvC;AA4GD,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,OAAO,EAAE,aAAa,CAAA;IACtB,uFAAuF;IACvF,YAAY,EAAE,MAAM,CAAA;IACpB,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAA;IACf;;;OAGG;IACH,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC/C;AAED,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACxC,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAA;IAClB,uDAAuD;IACvD,UAAU,EAAE,YAAY,CAAA;IACxB;;;OAGG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAA;CACrE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,QAAQ,CAAC,CAiCnB;AAED,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,KAAK,EAAE,UAAU,CAAA;IACjB,mEAAmE;IACnE,GAAG,EAAE,GAAG,CAAA;CACT;AAED,2CAA2C;AAC3C,MAAM,WAAW,0BAA0B;IACzC,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAA;IAClB,qFAAqF;IACrF,QAAQ,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACjF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,QAAQ,CAAC,CAqBnB"}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}