@kottera/tera-web 0.1.0-rc.3 → 0.1.0-rc.5

package/README.md

@@ -10,9 +10,11 @@ author's — and has no runtime dependencies. It is not yet published.
 | Path | What it holds |
 |------|---------------|
 | `src/index.ts` | The package's one entry point. Everything public is re-exported here. |
-| `src/routes.ts` | The route prefix and `routePath`. |
+| `src/routes.ts` | The route prefix, `routePath`, and the app's base (`appBase`, `underBase`) every route and the sign-out are reached under. |
 | `src/client.ts` | `TeraClient`, the typed client over D3's routes (D4 items 1, 3 and 4): `me()`, `invoke(capability, params)`, `feed(options)` (a `FeedConnection` read with the client's fetch), `upload(file, options)` with progress, and `signOut()`. A kit refusal throws `KitRequestError`; a verb's refusal answers as its verdict. |
-| `src/generated/` | The contract, generated from the committed schemas under `sdk/plugin/webui/schema/`, `sdk/workorder/schema/` and `sdk/feed/schema/` (D4 item 1): one type per schema, the kit's route table as `KIT_ROUTE_TABLE`, and the maps from a route or a feed event to the type it carries. Never hand-edited, and never hand-write a type it declares: `make web-types` regenerates it, and `TestWebTypes_MatchCommitted` (`cmd/internal/genwebtypes`) fails on a hand edit or a stale generation. |
+| `src/phone.ts` | `phoneURL(me, location, base?)`, the "Open on your phone" link (ADR-177 D4): `me().phone_path` resolved against the app's base (`/` by default, `/plugins/<name>/` on a path-based installation), with `next` set to `location.href`, fragment included. tera's proxy sends it on to tera's phone page, which draws the page's URL as a QR code, so the page needs no knowledge of tera's URL. A `phone_path` that is not relative to the base throws. |
+| `src/stepup.ts` | A person's step-up from the page's side (ADR-173 D11): the step-up header, the `return_to` the navigation fallback carries, and `StepUpError`. Every `TeraClient` request — `me()`, `invoke()`, `upload()` and `fetch(path)` to the plugin's own routes — has the person confirm a `step_up_required` and sends the request once more; `stepUp(id)` reads `GET /tera/v1/step-ups/{id}`. |
+| `src/generated/` | The contract, generated from the committed schemas under `sdk/plugin/webui/schema/`, `sdk/workorder/schema/`, `sdk/feed/schema/` and `sdk/shares/schema/` (D4 item 1; the share types, ADR-174 D14): one type per schema, the kit's route table as `KIT_ROUTE_TABLE`, and the maps from a route or a feed event to the type it carries. Never hand-edited, and never hand-write a type it declares: `make web-types` regenerates it, and `TestWebTypes_MatchCommitted` (`cmd/internal/genwebtypes`) fails on a hand edit or a stale generation. |
 | `src/feed/` | The stream connection (D4 item 2). |
 | `src/**/*.test.ts` | The suite, beside what it tests. |
 
@@ -36,3 +38,16 @@ is here for an author with one, `tsc -p sdk/web`. What the gate does run over
 the generated types is `src/contract.test.ts`: every committed schema has a
 generated type, the route table is the committed one, and a fixture of each
 D3 shape, annotated with its generated type, is valid against its schema.
+
+## Open on your phone
+
+```ts
+const me = await client.me();
+link.href = phoneURL(me, window.location, "/plugins/wb/"); // omit the base at the root of the plugin's own origin
+```
+
+The link is the plugin's own `_tera/phone`, under its base. tera's proxy
+redirects it to tera's `/oauth/phone` only for a page under this
+installation's own base, and to the app's base for any other. The fragment
+rides along, but survives on the phone only when no sign-in intervenes, so a
+deep link a phone must open on its first visit routes by path or query.

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import { FeedConnection, type FeedConnectionOptions } from "./feed/connection.ts";
-import type { KitError, KitInvokeResponse, KitMeResponse, KitUploadResponse } from "./generated/kit.ts";
+import type { KitError, KitInvokeResponse, KitMeResponse, KitStepUpResponse, KitUploadResponse } from "./generated/kit.ts";
+import { type StepUpChallenge, type StepUpOptions } from "./stepup.ts";
 /** The body of a kit failure: the envelope's `error` member. */
 export type KitErrorBody = KitError["error"];
 /** A verb's refusal, as the kit passed it through: the reply envelope's `error` member. */
@@ -89,19 +90,34 @@ export interface UploadRequest {
     };
 }
 export interface TeraClientOptions {
+    /**
+     * The path the app is served under on its origin: `/`, the default, on a
+     * plugin's own origin, and `/plugins/<name>/` on an installation that serves
+     * plugins by path. Every route, and the sign-out, is reached under it.
+     */
+    base?: string;
     /** The fetch every route but the upload is read with; the page's own when absent. */
     fetch?: typeof fetch;
     /** Makes the upload's request; `new XMLHttpRequest()` when absent. */
     uploadRequest?: () => UploadRequest;
-    /** Sends the page to a path; `location.assign` when absent. */
+    /** Sends the page to a path or URL; `location.assign` when absent. */
     navigate?: (path: string) => void;
+    /** How a step-up is confirmed: the window, the page's URL and the polling. */
+    stepUp?: StepUpOptions;
 }
 /** The options of {@link TeraClient.feed}: a {@link FeedConnection}'s, with the opener the client's own. */
-export type FeedOptions = Omit<FeedConnectionOptions, "open">;
+export type FeedOptions = Omit<FeedConnectionOptions, "open" | "base">;
 export declare class TeraClient {
+    private readonly base;
     private readonly fetchFn;
     private readonly uploadRequest;
     private readonly navigate;
+    private readonly openWindow;
+    private readonly pageURL;
+    private readonly sleep;
+    private readonly pollMs;
+    /** Whether the step-up the page was loaded back with has been taken up. */
+    private resumeTaken;
     constructor(options?: TeraClientOptions);
     /** `GET /tera/v1/me`: who is signed in, and where to send them to sign out. */
     me(): Promise<KitMeResponse>;
@@ -115,6 +131,7 @@ export declare class TeraClient {
      *     if (got.status === "success") show(got.result);
      */
     invoke<Result = unknown, Params = unknown>(capability: string, params?: Params): Promise<InvokeVerdict<Result>>;
+    private invokeOnce;
     /**
      * A {@link FeedConnection} over `GET /tera/v1/feeds/{feed}`, read with this
      * client's fetch. It is not started: call `start()` on it, and `stop()` when
@@ -128,11 +145,48 @@ export declare class TeraClient {
      * route's headers, and `onProgress` reports the body as it is sent.
      */
     upload(file: Blob, options?: UploadOptions): Promise<KitUploadResponse>;
+    private uploadOnce;
+    /**
+     * `GET /tera/v1/step-ups/{id}`: where one of the person's own step-ups is in
+     * its life. A step-up that is not theirs is thrown as tera's 404, as an id
+     * no step-up carries is.
+     */
+    stepUp(id: string): Promise<KitStepUpResponse>;
+    /**
+     * A request to one of the plugin's own routes, `path` relative to the app's
+     * base (`reviews/7/finish`), same-origin. A `step_up_required` answer in the
+     * kit's envelope — what `webui.RequireStepUp` writes — is confirmed by the
+     * person and the request sent once more with `Tera-Step-Up`; any other
+     * answer, a success or a refusal, is returned as it arrived. A body sent
+     * again must be one that can be: a string, a `Blob`, `FormData` or a
+     * buffer, never a stream.
+     */
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Has the person confirm the step-up `challenge` names, and answers its id
+     * once it is satisfied, to send the act again with. It opens the step-up's
+     * page in a new window, or navigates to it with a `return_to` naming this
+     * page when the browser opens none, and reads its state every poll interval
+     * until it is satisfied, declined or expired, closing the window it opened.
+     *
+     * Rejects with a {@link StepUpError} when the step-up ends unconfirmed, the
+     * person closes its window while it still waits, or the page navigated away
+     * to confirm it. A page loaded back from that navigation carries the id, and
+     * the first step-up it is asked for resumes that one when it is satisfied.
+     */
+    confirmStepUp(challenge: StepUpChallenge): Promise<string>;
+    /** The step-up this page was loaded back with, once. */
+    private takeResumed;
+    private fetchSameOrigin;
     /**
      * Signs the person out: navigates to the `signout_path` `me()` answers,
-     * tera's own path, which ends their session for every plugin. A path that
-     * is not one on this origin is refused rather than followed.
+     * tera's own sign-out, resolved against the app's base. A `signout_path`
+     * that is not a path relative to the base — a root-absolute path, or one
+     * naming another origin — is refused rather than followed.
      */
     signOut(): Promise<void>;
+    /** A kit route's path under the app's base. */
+    private route;
     private json;
+    private jsonOnce;
 }

package/dist/client.js

@@ -23,7 +23,8 @@
  *
  * # Same origin
  *
- * Every request is to a path under the kit's prefix on the page's own origin,
+ * Every request is to a path under the kit's prefix, below the app's base
+ * ({@link TeraClientOptions.base}), on the page's own origin,
  * with `credentials: "same-origin"`; a fetch is also `mode: "same-origin"`, so
  * a page that somehow aimed one elsewhere is refused by the browser rather
  * than sent. The browser then marks it `Sec-Fetch-Site: same-origin`, which is
@@ -31,12 +32,25 @@
  * claims it: a page cannot set `Sec-Fetch-*` or `Origin`, and the rule rests
  * on that.
  *
- * It is a plain class with an injected fetch, request factory and navigation,
- * so its tests drive it against a fake and no network.
+ * # A step-up
+ *
+ * Every request it makes handles a `step_up_required` refusal that names a
+ * page to confirm the act on (ADR-173 D11): the kit's envelope from a kit
+ * route or from the plugin's own route ({@link TeraClient.fetch}), and a Work
+ * Order verb's refusal relayed by {@link TeraClient.invoke}. It has the person
+ * confirm it ({@link TeraClient.confirmStepUp}) and sends the identical request
+ * once more, with `Tera-Step-Up: <id>`, or with `step_up` in an invoke's
+ * params. A step-up the person declines, lets expire or walks away from
+ * rejects with a {@link StepUpError}, and the request is not sent again.
+ *
+ * It is a plain class with an injected fetch, request factory, navigation,
+ * window opener and timer, so its tests drive it against a fake and no
+ * network.
  */
-import { routePath } from "./routes.js";
+import { appBase, isBaseRelative, routePath, underBase } from "./routes.js";
 import { FeedConnection } from "./feed/connection.js";
 import { fetchOpener } from "./feed/sse.js";
+import { STEP_UP_HEADER, STEP_UP_POLL_MS, StepUpError, defaultOpenWindow, defaultSleep, resumedStepUp, stepUpChallengeOf, stepUpPageURL, } from "./stepup.js";
 /**
  * The `code` of a {@link KitRequestError} whose answer was not the kit's
  * envelope — a proxy's page, a dropped body, a success that is not the
@@ -78,17 +92,30 @@ export class KitRequestError extends Error {
 }
 const JSON_TYPE = "application/json";
 export class TeraClient {
+    base;
     fetchFn;
     uploadRequest;
     navigate;
+    openWindow;
+    pageURL;
+    sleep;
+    pollMs;
+    /** Whether the step-up the page was loaded back with has been taken up. */
+    resumeTaken = false;
     constructor(options = {}) {
+        this.base = appBase(options.base);
         this.fetchFn = options.fetch ?? ((...args) => globalThis.fetch(...args));
         this.uploadRequest = options.uploadRequest ?? (() => new XMLHttpRequest());
         this.navigate = options.navigate ?? ((path) => globalThis.location.assign(path));
+        const stepUp = options.stepUp ?? {};
+        this.openWindow = stepUp.openWindow ?? defaultOpenWindow;
+        this.pageURL = stepUp.pageURL ?? (() => globalThis.location.href);
+        this.sleep = stepUp.sleep ?? defaultSleep;
+        this.pollMs = stepUp.pollIntervalMs ?? STEP_UP_POLL_MS;
     }
     /** `GET /tera/v1/me`: who is signed in, and where to send them to sign out. */
     async me() {
-        return this.json(routePath("me"), { method: "GET" });
+        return this.json(this.route("me"), { method: "GET" });
     }
     /**
      * `POST /tera/v1/invoke/{capability}`: invokes one capability as the
@@ -100,7 +127,17 @@ export class TeraClient {
      *     if (got.status === "success") show(got.result);
      */
     async invoke(capability, params) {
-        const url = routePath("invoke", capability);
+        const verdict = await this.invokeOnce(capability, params);
+        if (verdict.status !== "error")
+            return verdict;
+        const challenge = stepUpChallengeOf(verdict.error.code, verdict.error.data?.step_up);
+        if (challenge === null || !isParamsObject(params))
+            return verdict;
+        const id = await this.confirmStepUp(challenge);
+        return this.invokeOnce(capability, { ...(params ?? {}), step_up: id });
+    }
+    async invokeOnce(capability, params) {
+        const url = this.route("invoke", capability);
         const reply = await this.json(url, {
             method: "POST",
             headers: { "Content-Type": JSON_TYPE },
@@ -120,7 +157,7 @@ export class TeraClient {
      * the page no longer wants it.
      */
     feed(options) {
-        return new FeedConnection({ ...options, open: fetchOpener(this.fetchFn) });
+        return new FeedConnection({ ...options, base: this.base, open: fetchOpener(this.fetchFn) });
     }
     /**
      * `POST /tera/v1/uploads`: sends one file as the signed-in person and
@@ -128,13 +165,24 @@ export class TeraClient {
      * name. Its name and description travel percent-encoded (UTF-8) in the
      * route's headers, and `onProgress` reports the body as it is sent.
      */
-    upload(file, options = {}) {
+    async upload(file, options = {}) {
+        try {
+            return await this.uploadOnce(file, options, null);
+        }
+        catch (err) {
+            const challenge = err instanceof KitRequestError ? stepUpChallengeOf(err.code, err.envelope?.step_up) : null;
+            if (challenge === null)
+                throw err;
+            return this.uploadOnce(file, options, await this.confirmStepUp(challenge));
+        }
+    }
+    uploadOnce(file, options, stepUpId) {
         const filename = options.filename ?? file.name ?? "";
         if (filename === "") {
             return Promise.reject(new TypeError("upload: a filename is required: pass a File, or options.filename"));
         }
         const contentType = options.contentType || file.type || "application/octet-stream";
-        const url = routePath("uploads");
+        const url = this.route("uploads");
         const { signal, onProgress } = options;
         if (signal?.aborted)
             return Promise.reject(abortError());
@@ -151,6 +199,8 @@ export class TeraClient {
                 xhr.setRequestHeader("Tera-Upload-Description", encodeURIComponent(options.description));
             }
             xhr.setRequestHeader("Accept", JSON_TYPE);
+            if (stepUpId !== null)
+                xhr.setRequestHeader(STEP_UP_HEADER, stepUpId);
             if (onProgress !== undefined) {
                 xhr.upload.onprogress = (ev) => onProgress({ loaded: ev.loaded, total: ev.lengthComputable ? ev.total : file.size });
             }
@@ -181,22 +231,138 @@ export class TeraClient {
             }
         });
     }
+    /**
+     * `GET /tera/v1/step-ups/{id}`: where one of the person's own step-ups is in
+     * its life. A step-up that is not theirs is thrown as tera's 404, as an id
+     * no step-up carries is.
+     */
+    async stepUp(id) {
+        return this.json(this.route("step-ups", id), { method: "GET" }, false);
+    }
+    /**
+     * A request to one of the plugin's own routes, `path` relative to the app's
+     * base (`reviews/7/finish`), same-origin. A `step_up_required` answer in the
+     * kit's envelope — what `webui.RequireStepUp` writes — is confirmed by the
+     * person and the request sent once more with `Tera-Step-Up`; any other
+     * answer, a success or a refusal, is returned as it arrived. A body sent
+     * again must be one that can be: a string, a `Blob`, `FormData` or a
+     * buffer, never a stream.
+     */
+    async fetch(path, init = {}) {
+        const url = underBase(this.base, path);
+        const first = await this.fetchSameOrigin(url, init, null);
+        const challenge = await stepUpRefusalOf(first);
+        if (challenge === null)
+            return first;
+        return this.fetchSameOrigin(url, init, await this.confirmStepUp(challenge));
+    }
+    /**
+     * Has the person confirm the step-up `challenge` names, and answers its id
+     * once it is satisfied, to send the act again with. It opens the step-up's
+     * page in a new window, or navigates to it with a `return_to` naming this
+     * page when the browser opens none, and reads its state every poll interval
+     * until it is satisfied, declined or expired, closing the window it opened.
+     *
+     * Rejects with a {@link StepUpError} when the step-up ends unconfirmed, the
+     * person closes its window while it still waits, or the page navigated away
+     * to confirm it. A page loaded back from that navigation carries the id, and
+     * the first step-up it is asked for resumes that one when it is satisfied.
+     */
+    async confirmStepUp(challenge) {
+        const resumed = this.takeResumed();
+        if (resumed !== null) {
+            const state = await this.stepUp(resumed).then((s) => s.state, () => null);
+            if (state === "satisfied")
+                return resumed;
+        }
+        const win = this.openWindow(challenge.url);
+        if (win === null) {
+            this.navigate(stepUpPageURL(challenge.url, challenge.id, this.pageURL()));
+            throw new StepUpError(challenge.id, "navigated", "the browser opened no window, so the page went to tera's to confirm the act");
+        }
+        let closedSeen = false;
+        for (;;) {
+            await this.sleep(this.pollMs);
+            let state;
+            try {
+                state = (await this.stepUp(challenge.id)).state;
+            }
+            catch (err) {
+                win.close();
+                throw err;
+            }
+            if (state === "satisfied") {
+                win.close();
+                return challenge.id;
+            }
+            if (state !== "pending") {
+                win.close();
+                throw new StepUpError(challenge.id, state, `the step-up was ${state === "spent" ? "spent by another request" : state}, and the act was not sent again`);
+            }
+            // One more read after the person closes the window, in case they
+            // confirmed it just before; then it is abandoned.
+            if (win.closed) {
+                if (closedSeen) {
+                    throw new StepUpError(challenge.id, "abandoned", "the step-up's window was closed before it was confirmed");
+                }
+                closedSeen = true;
+            }
+        }
+    }
+    /** The step-up this page was loaded back with, once. */
+    takeResumed() {
+        if (this.resumeTaken)
+            return null;
+        this.resumeTaken = true;
+        try {
+            return resumedStepUp(this.pageURL());
+        }
+        catch {
+            return null;
+        }
+    }
+    fetchSameOrigin(url, init, stepUpId) {
+        const headers = new Headers(init.headers);
+        if (stepUpId !== null)
+            headers.set(STEP_UP_HEADER, stepUpId);
+        return this.fetchFn(url, { ...init, headers, credentials: "same-origin", mode: "same-origin" });
+    }
     /**
      * Signs the person out: navigates to the `signout_path` `me()` answers,
-     * tera's own path, which ends their session for every plugin. A path that
-     * is not one on this origin is refused rather than followed.
+     * tera's own sign-out, resolved against the app's base. A `signout_path`
+     * that is not a path relative to the base — a root-absolute path, or one
+     * naming another origin — is refused rather than followed.
      */
     async signOut() {
         const { signout_path: path } = await this.me();
-        if (typeof path !== "string" || !path.startsWith("/") || path.startsWith("//") || path.startsWith("/\\")) {
-            throw new KitRequestError(200, null, `${routePath("me")} answered a signout_path that is not a path on this origin: ${JSON.stringify(path)}`);
+        if (!isBaseRelative(path)) {
+            throw new KitRequestError(200, null, `${this.route("me")} answered a signout_path that is not a path relative to the app's base: ${JSON.stringify(path)}`);
         }
-        this.navigate(path);
+        this.navigate(underBase(this.base, path));
+    }
+    /** A kit route's path under the app's base. */
+    route(...segments) {
+        return underBase(this.base, routePath(...segments));
     }
-    async json(url, init) {
+    async json(url, init, stepUp = true) {
+        try {
+            return await this.jsonOnce(url, init, null);
+        }
+        catch (err) {
+            const challenge = stepUp && err instanceof KitRequestError ? stepUpChallengeOf(err.code, err.envelope?.step_up) : null;
+            if (challenge === null)
+                throw err;
+            return this.jsonOnce(url, init, await this.confirmStepUp(challenge));
+        }
+    }
+    async jsonOnce(url, init, stepUpId) {
         const response = await this.fetchFn(url, {
             ...init,
-            headers: { Accept: JSON_TYPE, ...init.headers },
+            headers: {
+                Accept: JSON_TYPE,
+                ...init.headers,
+                ...(stepUpId === null ? {} : { [STEP_UP_HEADER]: stepUpId }),
+            },
             credentials: "same-origin",
             mode: "same-origin",
             cache: "no-store",
@@ -233,6 +399,27 @@ function answer(url, status, contentType, text) {
     }
     throw new KitRequestError(status, envelopeOf(body), `${url} answered HTTP ${status} (${contentType || "no content type"})`);
 }
+/** Whether `params` can carry `step_up` beside what it holds: absent, or a plain object. */
+function isParamsObject(params) {
+    return params === undefined || params === null || (typeof params === "object" && !Array.isArray(params));
+}
+/** The step-up a response to the plugin's own route needs confirmed, read from a copy of it. */
+async function stepUpRefusalOf(response) {
+    if (response.status !== 403)
+        return null;
+    const type = (response.headers.get("content-type") ?? "").toLowerCase().split(";")[0].trim();
+    if (type !== JSON_TYPE)
+        return null;
+    let body;
+    try {
+        body = JSON.parse(await response.clone().text());
+    }
+    catch {
+        return null;
+    }
+    const e = envelopeOf(body);
+    return e === null ? null : stepUpChallengeOf(e.code, e.step_up);
+}
 /** The envelope's `error` member, when `body` is a kit envelope; null otherwise. */
 function envelopeOf(body) {
     if (typeof body !== "object" || body === null)

package/dist/feed/connection.d.ts

@@ -79,6 +79,8 @@ export declare function defaultOrderKey(record: FeedFrameRecord): number | undef
 export interface FeedConnectionOptions {
     /** The feed's name, as the plugin's manifest declares it. */
     feed: string;
+    /** The path the app is served under on its origin, as a client's `base` option names it; `/` when absent. */
+    base?: string;
     /** Narrows the feed to these of its topic filters (the feed's `topics` parameter). */
     topics?: readonly string[];
     /** Each record not already delivered, in order. */

package/dist/feed/connection.js

@@ -63,7 +63,7 @@
  * It is a plain class with an injected clock, opener and signals, so its tests
  * drive it with fake timers and a scripted stream and no network.
  */
-import { routePath } from "../routes.js";
+import { routePath, underBase, ROOT_BASE } from "../routes.js";
 import { fetchOpener, isRefusal } from "./sse.js";
 export const BASE_DELAY_MS = 1_000;
 export const MAX_DELAY_MS = 30_000;
@@ -164,7 +164,7 @@ export class FeedConnection {
         for (const topic of this.options.topics ?? [])
             query.append("topics", topic);
         query.set("backfill", "all");
-        return routePath("feeds", this.options.feed) + "?" + query.toString();
+        return underBase(this.options.base ?? ROOT_BASE, routePath("feeds", this.options.feed)) + "?" + query.toString();
     }
     /** Opens the first stream. Nothing delivered before is remembered. */
     start() {

package/dist/generated/kit.d.ts

@@ -6,7 +6,7 @@ import type { FeedFrameRecord, FeedFrameStatus } from "./feed.ts";
  *
  * Schema: sdk/plugin/webui/schema/v1/error-code.json
  */
-export type KitErrorCode = "unauthenticated" | "cross_origin" | "route_not_found" | "method_not_allowed" | "route_not_served" | "invalid_request" | "exchange_refused" | "tera_unavailable";
+export type KitErrorCode = "unauthenticated" | "cross_origin" | "route_not_found" | "method_not_allowed" | "route_not_served" | "invalid_request" | "exchange_refused" | "tera_unavailable" | "step_up_required";
 /**
  * Kit error envelope.
  *
@@ -27,6 +27,14 @@ export type KitError = {
         retry_after_ms?: number;
         /** Structured detail the refusing verb attached, whose shape the verb decides. The kit's own refusals attach none. */
         data?: unknown;
+        /** The step-up a step_up_required, step_up_pending or step_up_mismatch refusal of the kit's is about. On a step-up just begun it carries the id, the page (url) the person confirms it on, its expiry and the methods the act accepts: open the page, poll the step-up route until it is satisfied, declined or expired, and send the identical request again with the Tera-Step-Up header set to the id. */
+        step_up?: {
+            id: string;
+            url?: string;
+            methods?: string[];
+            expires_at?: string;
+            state?: string;
+        };
     };
 };
 /**
@@ -75,8 +83,39 @@ export type KitInvokeResponse = {
 export type KitMeResponse = {
     /** The signed-in person, as tera's caller assertion names them: spelled as a Work Order that person filed would name them. */
     subject: string;
-    /** Where to send the person to sign out: tera's own path, which ends their session for every plugin. */
+    /** Where to send the person to sign out: tera's own sign-out, as a path relative to the app's base, which a page resolves against that base (/ on the plugin's own origin, /plugins/<name>/ on a path-based installation). It is never root-absolute. */
     signout_path: string;
+    /** Where to send the person to open a page on their phone: tera's proxy's redirect to tera's phone page, given the page's own URL as the next query parameter. A path relative to the app's base, resolved as signout_path is. It is never root-absolute. */
+    phone_path: string;
+    /** What to call the signed-in person, as tera's record of them holds it; absent when it holds none. Presentation only: subject is the identity, and nothing is decided by this. */
+    display_name?: string;
+    /** The address tera's record of the signed-in person holds; absent when it holds none. Presentation only: subject is the identity, and nothing is decided by this. */
+    email?: string;
+};
+/**
+ * GET /tera/v1/step-ups/{id} response.
+ *
+ * Where one of the person's own step-ups is in its life (ADR-173 D11).
+ *
+ * Schema: sdk/plugin/webui/schema/v1/step-up.response.json
+ */
+export type KitStepUpResponse = {
+    /** The step-up's id. */
+    id: string;
+    /** Where the step-up is in its life: pending until the person confirms or declines it, satisfied once confirmed, spent once the act used it, declined, or expired. A reader polls until it is satisfied, declined or expired. */
+    state: "pending" | "satisfied" | "spent" | "declined" | "expired";
+    /** tera's own text for the act the step-up confirms. */
+    display: string;
+    /** The methods the act accepts: passkey, and email_code when the act accepts it. */
+    methods: string[] | null;
+    /** When the step-up stops waiting, in RFC 3339. */
+    expires_at: string;
+    /** What satisfied it, passkey or email_code; absent until it is satisfied. */
+    method?: string;
+    /** For a passkey, the kind of sign-in that registered it; a passkey anchored on email_code is worth an email code. Absent otherwise. */
+    anchor?: string;
+    /** When the person confirmed it, in RFC 3339; absent until then. */
+    satisfied_at?: string;
 };
 /**
  * POST /tera/v1/uploads response.
@@ -111,16 +150,20 @@ export declare const KIT_SCHEMAS: {
     readonly KitFeedEventReauthenticate: "sdk/plugin/webui/schema/v1/feed.event.reauthenticate.json";
     readonly KitInvokeResponse: "sdk/plugin/webui/schema/v1/invoke.response.json";
     readonly KitMeResponse: "sdk/plugin/webui/schema/v1/me.response.json";
+    readonly KitStepUpResponse: "sdk/plugin/webui/schema/v1/step-up.response.json";
     readonly KitUploadResponse: "sdk/plugin/webui/schema/v1/upload.response.json";
 };
-/** The prefix every kit route is served under (ADR-162 D3). */
+/** The prefix every kit route is served under (ADR-162 D3), below the app's base. */
 export declare const KIT_ROUTE_PREFIX = "/tera/v1/";
-/** tera's own sign-out path, which `GET /tera/v1/me` answers as signout_path. */
-export declare const KIT_SIGNOUT_PATH = "/_tera/signout";
+/** tera's own sign-out path, which `GET /tera/v1/me` answers as signout_path: relative, resolved against the app's base. */
+export declare const KIT_SIGNOUT_PATH = "_tera/signout";
+/** tera's proxy's phone path, which `GET /tera/v1/me` answers as phone_path: relative, resolved against the app's base. */
+export declare const KIT_PHONE_PATH = "_tera/phone";
 /** The kit's route table (ADR-162 D3), as sdk/plugin/webui declares it. */
 export declare const KIT_ROUTE_TABLE: {
     readonly prefix: "/tera/v1/";
-    readonly signout_path: "/_tera/signout";
+    readonly signout_path: "_tera/signout";
+    readonly phone_path: "_tera/phone";
     readonly same_origin: "A route marked same_origin refuses a request unless it is same-origin: when the request carries Sec-Fetch-Site, that header must be same-origin; when it does not, its Origin must equal the request's own (scheme http or https, and the Host the request was sent to). The refusal is 403 cross_origin.";
     readonly public: "None. Every route under the prefix refuses a request with no verified caller, 401 unauthenticated, before anything else is decided. Only the app's assets, outside the prefix, are served to an anonymous request.";
     readonly error: {
@@ -132,7 +175,7 @@ export declare const KIT_ROUTE_TABLE: {
         readonly name: "me";
         readonly method: "GET";
         readonly path: "/tera/v1/me";
-        readonly summary: "Who is signed in, and where to send them to sign out.";
+        readonly summary: "Who is signed in, where to send them to sign out, and where to send them to open a page on their phone.";
         readonly same_origin: false;
         readonly response: {
             readonly media_type: "application/json";
@@ -223,6 +266,22 @@ export declare const KIT_ROUTE_TABLE: {
             readonly schema: "https://kottera.dev/schemas/plugin/webui/upload.response/v1";
             readonly description: "The staged artifact.";
         };
+    }, {
+        readonly name: "step_up";
+        readonly method: "GET";
+        readonly path: "/tera/v1/step-ups/{id}";
+        readonly summary: "Read one of the person's own step-ups as the person (ADR-173 D11): what a page polls, after opening the step-up's url, until it is satisfied, declined or expired. A step-up that is not the person's is tera's 404, the same as an id no step-up carries.";
+        readonly same_origin: false;
+        readonly path_params: readonly [{
+            readonly name: "id";
+            readonly description: "The step-up's id, as a step_up_required refusal's step_up names it.";
+            readonly required: true;
+        }];
+        readonly response: {
+            readonly media_type: "application/json";
+            readonly schema: "https://kottera.dev/schemas/plugin/webui/step-up.response/v1";
+            readonly description: "The step-up's state.";
+        };
     }];
 };
 /** The name of a route in KIT_ROUTE_TABLE. */
@@ -235,6 +294,7 @@ export type KitRouteResponses = {
     me: KitMeResponse;
     invoke: KitInvokeResponse;
     upload: KitUploadResponse;
+    step_up: KitStepUpResponse;
 };
 /** The data of each server-sent event a feed stream carries, by event name. */
 export type KitFeedEvents = {