@dewee/identity 0.0.0-stage → 0.1.0-beta.1

package/dist/exchange.js

@@ -0,0 +1,74 @@
+import { createAssertion, requireUuid } from "./assertion.js";
+import { DeweeIdentityError, invalidArgument } from "./errors.js";
+import { assertServer, gatewayRequest, requireString } from "./transport.js";
+/** Authorization scheme of partner server calls. */
+export const ASSERTION_AUTH_SCHEME = "Dewee-Assertion";
+/** Header that carries an identity session token on HTTP calls. */
+export const IDENTITY_SESSION_HEADER = "X-Dewee-Identity-Session";
+/** Bounds of an identity session lifetime. */
+export const MIN_SESSION_TTL_SECONDS = 60;
+export const MAX_SESSION_TTL_SECONDS = 43_200;
+function checkTtl(ttl) {
+    if (ttl === undefined)
+        return;
+    if (!Number.isInteger(ttl) || ttl < MIN_SESSION_TTL_SECONDS || ttl > MAX_SESSION_TTL_SECONDS) {
+        throw invalidArgument(`ttlSeconds must be an integer from ${MIN_SESSION_TTL_SECONDS} to ${MAX_SESSION_TTL_SECONDS}`);
+    }
+}
+/**
+ * Exchanges a partner proof of one user for a short-lived identity session bound to one agent
+ * (`POST /v1/identity/sessions/exchange`). The tenant and application come from the verified
+ * assertion; nothing in the request names a user, tenant or role.
+ */
+export async function exchangeSession(opts) {
+    assertServer();
+    if (opts === null || typeof opts !== "object")
+        throw invalidArgument("options are required");
+    if (typeof opts.agent !== "string" || opts.agent.trim() === "" || opts.agent.length > 255) {
+        throw invalidArgument("agent is required: the agent id or key");
+    }
+    checkTtl(opts.ttlSeconds);
+    let assertion;
+    const body = { agent_id: opts.agent.trim() };
+    if ("signer" in opts && opts.signer !== undefined) {
+        assertion = await createAssertion({ ...opts.signer, purpose: "session", subject: opts.subject });
+    }
+    else {
+        const withAssertion = opts;
+        if (typeof withAssertion.assertion !== "string" || withAssertion.assertion === "") {
+            throw invalidArgument("assertion is required (or pass signer and subject)");
+        }
+        assertion = withAssertion.assertion;
+        if (withAssertion.oidcApplicationId !== undefined) {
+            body.id_token = true;
+            body.application_id = requireUuid(withAssertion.oidcApplicationId, "oidcApplicationId");
+        }
+    }
+    if (opts.ttlSeconds !== undefined)
+        body.ttl_seconds = opts.ttlSeconds;
+    const path = "/v1/identity/sessions/exchange";
+    const { body: res } = await gatewayRequest(opts, {
+        method: "POST",
+        path,
+        headers: { Authorization: `${ASSERTION_AUTH_SCHEME} ${assertion}` },
+        body,
+    });
+    const expiresAt = new Date(requireString(res, "expires_at", path));
+    if (Number.isNaN(expiresAt.getTime())) {
+        throw new DeweeIdentityError({ code: "INVALID_RESPONSE", message: `INVALID_RESPONSE: ${path} answer has a bad expires_at` });
+    }
+    const session = {
+        sessionToken: requireString(res, "session_token", path),
+        header: typeof res.header === "string" && res.header !== "" ? res.header : IDENTITY_SESSION_HEADER,
+        sessionId: requireString(res, "session_id", path),
+        principalId: requireString(res, "principal_id", path),
+        applicationId: requireString(res, "application_id", path),
+        agentId: requireString(res, "agent_id", path),
+        expiresAt,
+        testMode: res.test_mode === true,
+    };
+    if (typeof res.test_mode_banner === "string" && res.test_mode_banner !== "") {
+        session.testModeBanner = res.test_mode_banner;
+    }
+    return session;
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @dewee/identity: the server SDK of Dewee Connect.
+ *
+ * - {@link exchangeSession}: sign a user in to a Dewee agent (widget session).
+ * - {@link createConnectRedirect}: answer the hosted-link handoff of Dewee Connect.
+ * - {@link verifyTrustedUser}: inside your MCP server, read the verified user of a call.
+ *
+ * Server only: every entry point refuses to run where `window` exists.
+ */
+export { ASSERTION_TYPES, DEFAULT_ASSERTION_TTL_SECONDS, MAX_ASSERTION_TTL_SECONDS, MIN_SECRET_LENGTH, applicationAudience, createAssertion, type AssertionPurpose, type AssertionSigner, type AsymmetricAlgorithm, type CreateAssertionOptions, type LifecycleEvent, } from "./assertion.js";
+export { DeweeIdentityError, GATEWAY_ERROR_CODES, IDENTITY_ERROR_CODES, IDENTITY_ERROR_HINTS, REMEDIATION_ACTIONS, REMEDIATION_AUDIENCES, SDK_ERROR_CODES, isIdentityErrorCode, type DeweeIdentityErrorCode, type GatewayErrorCode, type IdentityErrorCode, type Remediation, type RemediationAction, type RemediationAudience, type SdkErrorCode, type TrustedUserRefusal, } from "./errors.js";
+export { ASSERTION_AUTH_SCHEME, IDENTITY_SESSION_HEADER, MAX_SESSION_TTL_SECONDS, MIN_SESSION_TTL_SECONDS, exchangeSession, type ExchangeSessionOptions, type ExchangeWithAssertion, type ExchangeWithSigner, type IdentitySession, } from "./exchange.js";
+export { lifecycle, logout, revokeSession, type LifecycleOptions, type LifecycleResult, type LogoutOptions, type RevokeSessionOptions, } from "./lifecycle.js";
+export { CONNECT_RETURN_PATH, checkConnectRequest, createConnectRedirect, readConnectRequest, startLink, type ConnectRedirect, type ConnectRequest, type CreateConnectRedirectOptions, type LinkTarget, type ReadConnectRequestOptions, type StartLinkOptions, type StartedLink, } from "./links.js";
+export { type GatewayOptions } from "./transport.js";
+export { MemoryReplayGuard, TRUSTED_USER_CLOCK_SKEW_SECONDS, TRUSTED_USER_ISSUER_PREFIX, TRUSTED_USER_TOKEN_TTL_SECONDS, TRUSTED_USER_TOKEN_TYPE, extractTrustedUserToken, verifyTrustedUser, type ReplayGuard, type TrustedUser, type VerifyTrustedUserOptions, } from "./verify-trusted-user.js";

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @dewee/identity: the server SDK of Dewee Connect.
+ *
+ * - {@link exchangeSession}: sign a user in to a Dewee agent (widget session).
+ * - {@link createConnectRedirect}: answer the hosted-link handoff of Dewee Connect.
+ * - {@link verifyTrustedUser}: inside your MCP server, read the verified user of a call.
+ *
+ * Server only: every entry point refuses to run where `window` exists.
+ */
+export { ASSERTION_TYPES, DEFAULT_ASSERTION_TTL_SECONDS, MAX_ASSERTION_TTL_SECONDS, MIN_SECRET_LENGTH, applicationAudience, createAssertion, } from "./assertion.js";
+export { DeweeIdentityError, GATEWAY_ERROR_CODES, IDENTITY_ERROR_CODES, IDENTITY_ERROR_HINTS, REMEDIATION_ACTIONS, REMEDIATION_AUDIENCES, SDK_ERROR_CODES, isIdentityErrorCode, } from "./errors.js";
+export { ASSERTION_AUTH_SCHEME, IDENTITY_SESSION_HEADER, MAX_SESSION_TTL_SECONDS, MIN_SESSION_TTL_SECONDS, exchangeSession, } from "./exchange.js";
+export { lifecycle, logout, revokeSession, } from "./lifecycle.js";
+export { CONNECT_RETURN_PATH, checkConnectRequest, createConnectRedirect, readConnectRequest, startLink, } from "./links.js";
+export { MemoryReplayGuard, TRUSTED_USER_CLOCK_SKEW_SECONDS, TRUSTED_USER_ISSUER_PREFIX, TRUSTED_USER_TOKEN_TTL_SECONDS, TRUSTED_USER_TOKEN_TYPE, extractTrustedUserToken, verifyTrustedUser, } from "./verify-trusted-user.js";

package/dist/job-access.d.ts

@@ -0,0 +1,26 @@
+export type JobAccessErrorCode = "INVALID_ARGUMENT" | "BROWSER_REQUIRED" | "POPUP_BLOCKED" | "POPUP_CLOSED" | "TIMEOUT" | "CANCELLED" | "IDENTITY_REQUIRED" | "LINK_EXPIRED" | "LINK_REVOKED" | "PERMISSION_DENIED" | "SOURCE_UNAVAILABLE" | "BOOTSTRAP_FAILED";
+/** Fixed, secret-free errors; remote error text is never copied. */
+export declare class JobAccessError extends Error {
+    readonly code: JobAccessErrorCode;
+    constructor(code: JobAccessErrorCode);
+    toJSON(): {
+        code: JobAccessErrorCode;
+        message: string;
+    };
+}
+export interface OpenJobAccessOptions {
+    /** Public Gateway origin, HTTPS (HTTP is allowed only on localhost). */
+    gatewayUrl: string;
+    /** Original verified identity session, held in memory. Never a visitor or Gateway token. */
+    identitySession: string;
+    /** Cancels only this launch, not an already opened authenticated page. */
+    signal?: AbortSignal;
+    /** Handshake deadline, 1–120 seconds. Default 30 seconds. */
+    timeoutMs?: number;
+}
+/**
+ * Call directly from a human click. Opens the fixed hosted page synchronously;
+ * resolves after authenticated bootstrap, before any separate grant consent.
+ * No token is put in a URL, storage, DOM, logs or the returned value.
+ */
+export declare function openJobAccess(options: OpenJobAccessOptions): Promise<void>;

package/dist/job-access.js

@@ -0,0 +1,182 @@
+const messages = {
+    INVALID_ARGUMENT: "Valid gateway origin and identity session are required.",
+    BROWSER_REQUIRED: "Open job access from a browser.",
+    POPUP_BLOCKED: "Allow popups, then open job access again.",
+    POPUP_CLOSED: "Job access was closed. Open it again to continue.",
+    TIMEOUT: "Job access did not respond. Open it again to retry.",
+    CANCELLED: "Opening job access was cancelled.",
+    IDENTITY_REQUIRED: "Sign in again, then open job access.",
+    LINK_EXPIRED: "Your sign-in expired. Sign in again, then open job access.",
+    LINK_REVOKED: "Your sign-in was revoked. Sign in again, then open job access.",
+    PERMISSION_DENIED: "This account cannot open job access.",
+    SOURCE_UNAVAILABLE: "Job access is temporarily unavailable. Try again later.",
+    BOOTSTRAP_FAILED: "Job access could not be opened. Try again.",
+};
+/** Fixed, secret-free errors; remote error text is never copied. */
+export class JobAccessError extends Error {
+    code;
+    constructor(code) {
+        super(messages[code]);
+        this.name = "JobAccessError";
+        this.code = code;
+    }
+    toJSON() {
+        return { code: this.code, message: this.message };
+    }
+}
+const remoteCodes = new Set([
+    "IDENTITY_REQUIRED", "LINK_EXPIRED", "LINK_REVOKED", "PERMISSION_DENIED",
+    "SOURCE_UNAVAILABLE", "BOOTSTRAP_FAILED",
+]);
+function exactKeys(data, keys) {
+    return Object.keys(data).length === keys.length && keys.every((key) => Object.hasOwn(data, key));
+}
+/**
+ * Call directly from a human click. Opens the fixed hosted page synchronously;
+ * resolves after authenticated bootstrap, before any separate grant consent.
+ * No token is put in a URL, storage, DOM, logs or the returned value.
+ */
+export function openJobAccess(options) {
+    return new Promise((resolve, reject) => {
+        const fail = (code) => reject(new JobAccessError(code));
+        if (typeof window === "undefined") {
+            fail("BROWSER_REQUIRED");
+            return;
+        }
+        if (!options || typeof options !== "object") {
+            fail("INVALID_ARGUMENT");
+            return;
+        }
+        let token = options.identitySession;
+        const signal = options.signal;
+        const timeoutMs = options.timeoutMs ?? 30_000;
+        let origin;
+        try {
+            const url = new URL(options.gatewayUrl);
+            const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+            if ((url.protocol !== "https:" && !(url.protocol === "http:" && local)) ||
+                url.username || url.password || url.search || url.hash || url.pathname !== "/" ||
+                typeof token !== "string" || !token.trim() || token.length > 16_384 ||
+                (signal !== undefined && (typeof AbortSignal === "undefined" || !(signal instanceof AbortSignal))) ||
+                !Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 120_000) {
+                fail("INVALID_ARGUMENT");
+                return;
+            }
+            origin = url.origin;
+        }
+        catch {
+            fail("INVALID_ARGUMENT");
+            return;
+        }
+        if (signal?.aborted) {
+            token = undefined;
+            fail("CANCELLED");
+            return;
+        }
+        let popup;
+        try {
+            popup = window.open(`${origin}/identity/job-access?launch=1`, "_blank", "popup,width=720,height=800");
+        }
+        catch {
+            token = undefined;
+            fail("POPUP_BLOCKED");
+            return;
+        }
+        if (!popup) {
+            token = undefined;
+            fail("POPUP_BLOCKED");
+            return;
+        }
+        const target = popup;
+        let nonce;
+        let settled = false;
+        let interval;
+        let timeout;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            token = undefined;
+            nonce = undefined;
+            clearInterval(interval);
+            clearTimeout(timeout);
+            window.removeEventListener("message", receive);
+            window.removeEventListener("pagehide", cancel);
+            try {
+                signal?.removeEventListener("abort", cancel);
+            }
+            catch { /* Best-effort cancellation cleanup. */ }
+            if (code) {
+                try {
+                    target.close();
+                }
+                catch { /* Cleanup cannot override the safe error. */ }
+                fail(code);
+            }
+            else
+                resolve();
+        };
+        const cancel = () => finish("CANCELLED");
+        const receive = (event) => {
+            if (settled || event.source !== target || event.origin !== origin ||
+                !event.data || typeof event.data !== "object" || Array.isArray(event.data))
+                return;
+            const data = event.data;
+            if (data.version !== 1)
+                return;
+            if (!nonce && data.type === "dewee.job-access.ready" &&
+                exactKeys(data, ["type", "version", "nonce"]) && typeof data.nonce === "string" &&
+                /^[A-Za-z0-9_-]{22,128}$/.test(data.nonce)) {
+                nonce = data.nonce;
+                try {
+                    target.postMessage({ type: "dewee.job-access.session", version: 1, nonce, identitySession: token }, origin);
+                }
+                catch {
+                    finish("BOOTSTRAP_FAILED");
+                }
+                token = undefined;
+                return;
+            }
+            if (!nonce || data.type !== "dewee.job-access.result" || data.nonce !== nonce)
+                return;
+            if (data.status === "ready" && exactKeys(data, ["type", "version", "nonce", "status"]))
+                finish();
+            else if (data.status === "error" && exactKeys(data, ["type", "version", "nonce", "status", "code"]) &&
+                typeof data.code === "string" && remoteCodes.has(data.code)) {
+                finish(data.code);
+            }
+        };
+        const hello = () => {
+            if (settled)
+                return;
+            if (target.closed) {
+                finish("POPUP_CLOSED");
+                return;
+            }
+            if (!nonce) {
+                try {
+                    target.postMessage({ type: "dewee.job-access.hello", version: 1 }, origin);
+                }
+                catch {
+                    finish("BOOTSTRAP_FAILED");
+                }
+            }
+        };
+        window.addEventListener("message", receive);
+        window.addEventListener("pagehide", cancel);
+        try {
+            signal?.addEventListener("abort", cancel, { once: true });
+        }
+        catch {
+            finish("INVALID_ARGUMENT");
+            return;
+        }
+        if (signal?.aborted) {
+            finish("CANCELLED");
+            return;
+        }
+        interval = setInterval(hello, 200);
+        timeout = setTimeout(() => finish("TIMEOUT"), timeoutMs);
+        hello();
+    });
+}

package/dist/lifecycle.d.ts

@@ -0,0 +1,50 @@
+import { type AssertionSigner, type LifecycleEvent } from "./assertion.js";
+import { type GatewayOptions } from "./transport.js";
+/** Options of every partner call made with a lifecycle assertion. */
+interface PartnerCall extends GatewayOptions {
+    signer: AssertionSigner;
+    /** The user the call is about: your stable user id, as in the session assertion. */
+    subject: string;
+}
+export interface LifecycleOptions extends PartnerCall {
+    event: LifecycleEvent;
+    /** With `scopes_changed` only: the user's complete new scope list. */
+    scopes?: string[];
+}
+export interface LifecycleResult {
+    principalId: string;
+    event: string;
+    status: "active" | "suspended" | "deleted";
+    grantVersion: number;
+    sessionsRevoked: number;
+    bindingsRevoked: number;
+}
+/**
+ * Reports a lifecycle event of one of your users (`POST /v1/identity/principals/lifecycle`):
+ * `suspend` and `delete` revoke the user's sessions at once and `delete` also unlinks every chat
+ * account; `scopes_changed` replaces the scopes. Repeating an event already applied is a no-op, so
+ * a retry is safe. The event and scopes travel inside the signed assertion, not in the body.
+ */
+export declare function lifecycle(opts: LifecycleOptions): Promise<LifecycleResult>;
+export interface RevokeSessionOptions extends PartnerCall {
+    /** The `sessionId` of an issued session of `subject`. */
+    sessionId: string;
+}
+/**
+ * Revokes one identity session of your user (`POST /v1/identity/sessions/{id}/revoke`). A session
+ * of another user, or of another application, answers `NOT_FOUND`.
+ */
+export declare function revokeSession(opts: RevokeSessionOptions): Promise<{
+    sessionId: string;
+    revoked: boolean;
+}>;
+export interface LogoutOptions extends PartnerCall {
+    /** The `principalId` Dewee returned with the user's session. */
+    principalId: string;
+}
+/** Revokes every identity session of your user (`POST /v1/identity/principals/{id}/logout`). */
+export declare function logout(opts: LogoutOptions): Promise<{
+    principalId: string;
+    sessionsRevoked: number;
+}>;
+export {};

package/dist/lifecycle.js

@@ -0,0 +1,67 @@
+import { createAssertion, requireUuid } from "./assertion.js";
+import { invalidArgument } from "./errors.js";
+import { ASSERTION_AUTH_SCHEME } from "./exchange.js";
+import { assertServer, gatewayRequest } from "./transport.js";
+async function lifecycleAuthorization(opts, event, scopes) {
+    const assertion = await createAssertion({ ...opts.signer, purpose: "lifecycle", subject: opts.subject, event, scopes });
+    return `${ASSERTION_AUTH_SCHEME} ${assertion}`;
+}
+/**
+ * Reports a lifecycle event of one of your users (`POST /v1/identity/principals/lifecycle`):
+ * `suspend` and `delete` revoke the user's sessions at once and `delete` also unlinks every chat
+ * account; `scopes_changed` replaces the scopes. Repeating an event already applied is a no-op, so
+ * a retry is safe. The event and scopes travel inside the signed assertion, not in the body.
+ */
+export async function lifecycle(opts) {
+    assertServer();
+    if (opts === null || typeof opts !== "object")
+        throw invalidArgument("options are required");
+    if (opts.event === undefined)
+        throw invalidArgument("event is required");
+    const authorization = await lifecycleAuthorization(opts, opts.event, opts.scopes);
+    const { body } = await gatewayRequest(opts, {
+        method: "POST",
+        path: "/v1/identity/principals/lifecycle",
+        headers: { Authorization: authorization },
+    });
+    const status = body.status;
+    return {
+        principalId: String(body.principal_id ?? ""),
+        event: String(body.event ?? opts.event),
+        status: status === "suspended" || status === "deleted" ? status : "active",
+        grantVersion: Number(body.grant_version ?? 0),
+        sessionsRevoked: Number(body.sessions_revoked ?? 0),
+        bindingsRevoked: Number(body.bindings_revoked ?? 0),
+    };
+}
+/**
+ * Revokes one identity session of your user (`POST /v1/identity/sessions/{id}/revoke`). A session
+ * of another user, or of another application, answers `NOT_FOUND`.
+ */
+export async function revokeSession(opts) {
+    assertServer();
+    if (opts === null || typeof opts !== "object")
+        throw invalidArgument("options are required");
+    const id = requireUuid(opts.sessionId, "sessionId");
+    const authorization = await lifecycleAuthorization(opts);
+    const { body } = await gatewayRequest(opts, {
+        method: "POST",
+        path: `/v1/identity/sessions/${id}/revoke`,
+        headers: { Authorization: authorization },
+    });
+    return { sessionId: String(body.session_id ?? id), revoked: body.revoked === true };
+}
+/** Revokes every identity session of your user (`POST /v1/identity/principals/{id}/logout`). */
+export async function logout(opts) {
+    assertServer();
+    if (opts === null || typeof opts !== "object")
+        throw invalidArgument("options are required");
+    const id = requireUuid(opts.principalId, "principalId");
+    const authorization = await lifecycleAuthorization(opts);
+    const { body } = await gatewayRequest(opts, {
+        method: "POST",
+        path: `/v1/identity/principals/${id}/logout`,
+        headers: { Authorization: authorization },
+    });
+    return { principalId: String(body.principal_id ?? id), sessionsRevoked: Number(body.sessions_revoked ?? 0) };
+}

package/dist/links.d.ts

@@ -0,0 +1,99 @@
+import { type AssertionSigner } from "./assertion.js";
+import { type GatewayOptions } from "./transport.js";
+/** Path of the hosted Connect page that receives the partner handoff. */
+export declare const CONNECT_RETURN_PATH = "/connect/return";
+export interface ConnectRequest {
+    /** The ceremony reference; it is the nonce the handoff assertion must carry. */
+    deweeTxn: string;
+    /** Where to send the user back: always `{connectBaseUrl}/connect/return`. */
+    returnTo: string;
+}
+export interface ReadConnectRequestOptions {
+    /** Your Dewee Connect origin (`GOCLAW_IDENTITY_CONNECT_BASE_URL`, else the gateway public URL). */
+    connectBaseUrl: string;
+    /** Allow a plain-http connect origin that is not loopback (private networks only). */
+    allowInsecureHttp?: boolean;
+}
+/**
+ * Checks the two values Dewee sends to your connect start URL. `return_to` must be exactly your
+ * Dewee Connect page: anything else is refused, so a crafted link can never make your server hand
+ * a signed assertion to another site.
+ */
+export declare function checkConnectRequest(input: {
+    deweeTxn: unknown;
+    returnTo: unknown;
+}, opts: ReadConnectRequestOptions): ConnectRequest;
+/** Reads and checks `dewee_txn` and `return_to` from the URL of a request to your connect start URL. */
+export declare function readConnectRequest(requestUrl: string | URL, opts: ReadConnectRequestOptions): ConnectRequest;
+export interface CreateConnectRedirectOptions extends ReadConnectRequestOptions {
+    signer: AssertionSigner;
+    /** The signed-in user on your side: your stable user id. */
+    subject: string;
+    /** From {@link readConnectRequest}. */
+    deweeTxn: string;
+    /** From {@link readConnectRequest}. */
+    returnTo: string;
+    /** Assertion lifetime in seconds (default 60, at most 300). */
+    ttlSeconds?: number;
+    /**
+     * The nonce of your page's `Content-Security-Policy` (`script-src 'nonce-…'`). Without it a
+     * strict CSP blocks the inline auto-submit and the user presses the Continue button instead.
+     */
+    cspNonce?: string;
+}
+export interface ConnectRedirect {
+    /** POST target: your Dewee Connect return page. */
+    action: string;
+    method: "POST";
+    /** Form fields to POST (the signed handoff assertion). */
+    fields: {
+        assertion: string;
+    };
+    /**
+     * A complete HTML page that POSTs the fields (scripted submit, with a button as fallback). Send it
+     * with `Cache-Control: no-store` and `Referrer-Policy: no-referrer`. Under a strict CSP pass
+     * `cspNonce`, or the user has to press the button.
+     */
+    html: string;
+    /**
+     * GET fallback URL with the assertion in the query. Prefer the POST form: a URL can end up in
+     * logs and history.
+     */
+    location: string;
+}
+/**
+ * Builds the hosted-link handoff: signs a handoff assertion for the signed-in user, bound to this
+ * ceremony (`nonce` = `dewee_txn`), and returns the POST form that sends the user back to Dewee
+ * Connect. Dewee then shows the consent screen and the chat proof step.
+ */
+export declare function createConnectRedirect(opts: CreateConnectRedirectOptions): Promise<ConnectRedirect>;
+export interface StartLinkOptions extends GatewayOptions {
+    /** The user's identity session token (from {@link exchangeSession}). */
+    sessionToken: string;
+    /** Makes a retry return the same ceremony instead of starting a second one. */
+    idempotencyKey?: string;
+}
+export interface LinkTarget {
+    channelType: string;
+    channelInstanceId: string;
+    name: string;
+    displayName?: string;
+}
+export interface StartedLink {
+    transactionId: string;
+    kind: string;
+    state: string;
+    /** Show it to the user exactly as given; they send it in a direct chat from the account to link. */
+    proofCode: string;
+    expiresAt: Date;
+    /** false when `idempotencyKey` replayed an earlier start. */
+    created: boolean;
+    /** The chat accounts the code can be sent to. */
+    deepLinks: LinkTarget[];
+}
+/**
+ * Starts a web-first link for a signed-in user (`POST /v1/identity/links`): Dewee returns a proof
+ * code the user sends from the chat account to link. The user never types an id; Dewee checks both
+ * sides and links on its own.
+ */
+export declare function startLink(opts: StartLinkOptions): Promise<StartedLink>;