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

package/README.md

@@ -10,9 +10,10 @@ 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/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. |
 

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, 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 (typeof path !== "string" || path === "" || path.startsWith("/") || /^[^/?#]*:/.test(path) || /[\\]/.test(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,37 @@ 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;
+    /** 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 +148,17 @@ 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";
 /** 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 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: {
@@ -223,6 +261,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 +289,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 = {

package/dist/generated/kit.js

@@ -10,16 +10,17 @@ export const KIT_SCHEMAS = {
     KitFeedEventReauthenticate: "sdk/plugin/webui/schema/v1/feed.event.reauthenticate.json",
     KitInvokeResponse: "sdk/plugin/webui/schema/v1/invoke.response.json",
     KitMeResponse: "sdk/plugin/webui/schema/v1/me.response.json",
+    KitStepUpResponse: "sdk/plugin/webui/schema/v1/step-up.response.json",
     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 const KIT_ROUTE_PREFIX = "/tera/v1/";
-/** tera's own sign-out path, which `GET /tera/v1/me` answers as signout_path. */
-export 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 const KIT_SIGNOUT_PATH = "_tera/signout";
 /** The kit's route table (ADR-162 D3), as sdk/plugin/webui declares it. */
 export const KIT_ROUTE_TABLE = {
     prefix: "/tera/v1/",
-    signout_path: "/_tera/signout",
+    signout_path: "_tera/signout",
     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.",
     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.",
     error: {
@@ -144,5 +145,24 @@ export const KIT_ROUTE_TABLE = {
                 description: "The staged artifact.",
             },
         },
+        {
+            name: "step_up",
+            method: "GET",
+            path: "/tera/v1/step-ups/{id}",
+            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.",
+            same_origin: false,
+            path_params: [
+                {
+                    name: "id",
+                    description: "The step-up's id, as a step_up_required refusal's step_up names it.",
+                    required: true,
+                },
+            ],
+            response: {
+                media_type: "application/json",
+                schema: "https://kottera.dev/schemas/plugin/webui/step-up.response/v1",
+                description: "The step-up's state.",
+            },
+        },
     ],
 };

package/dist/generated/shares.d.ts

@@ -0,0 +1,196 @@
+/**
+ * An ended share.
+ *
+ * The result of api.v1.shares.delete and api.v1.shares.leave: what the act ended. An ended share decides nothing and is not listed.
+ *
+ * Schema: sdk/shares/schema/v1/ended.json
+ */
+export type SharesEnded = {
+    /** The ended share's id. */
+    id: string;
+    /** The installation whose resource was shared, <vault>/plugins/<installation>. */
+    installation: string;
+    /** The resource that was shared. */
+    resource: string;
+    /** The grantee person's id. */
+    grantee: string;
+    /** The sharer person's id. */
+    sharer: string;
+    /** How the share ended, as its record holds it: revoked or left. */
+    ended: "revoked" | "left";
+};
+/**
+ * Extend a share.
+ *
+ * The params of api.v1.shares.patch, PATCH /api/v1/shares/{id} (ADR-174 D11).
+ *
+ * Schema: sdk/shares/schema/v1/extend.request.json
+ */
+export type SharesExtendRequest = {
+    /** The share's id, a UUIDv7. */
+    id: string;
+    /** The new expiry: later than the share's, at most the installation's max_expiry from now. Absent takes the kind's default_expiry from now, clamped to max_expiry. */
+    expires_at?: string;
+};
+/**
+ * Name one share.
+ *
+ * The params of api.v1.shares.get, api.v1.shares.delete and api.v1.shares.leave: the {id} of /api/v1/shares/{id}.
+ *
+ * Schema: sdk/shares/schema/v1/id.request.json
+ */
+export type SharesIdRequest = {
+    /** The share's id, a UUIDv7. */
+    id: string;
+};
+/**
+ * A list of shares.
+ *
+ * The result of api.v1.shares.list.
+ *
+ * Schema: sdk/shares/schema/v1/list.json
+ */
+export type SharesList = {
+    /** The shares, each with whether it decides now. */
+    shares: {
+        /** The share's id, a UUIDv7. */
+        id: string;
+        /** The installation whose resource is shared, <vault>/plugins/<installation>. */
+        installation: string;
+        /** The resource shared, plugins/<vault>/<installation>/<kind>/<id>. */
+        resource: string;
+        /** The shared verbs. */
+        verbs: string[] | null;
+        /** What the grantee is: person. */
+        grantee_kind: string;
+        /** The grantee person's id. */
+        grantee: string;
+        /** The id of the person who made the share. */
+        sharer: string;
+        /** The plugin principal that made the share for its sharer; absent when the sharer made it directly. */
+        created_via?: string;
+        /** When the share was made. */
+        created_at: string;
+        /** When the share stops deciding. */
+        expires_at: string;
+        /** When the share was last extended; absent if never. */
+        extended_at?: string;
+        /** Whether the share decides at least one of its verbs on the grantee's next request, computed from what decides now. */
+        deciding: boolean;
+        /** When deciding is false, the one reason why. Absent while the share decides. */
+        not_deciding?: "sharer_lost_access" | "sharing_disabled" | "installation_not_standing" | "verb_no_longer_shareable" | "pending_invitation";
+    }[] | null;
+};
+/**
+ * List shares.
+ *
+ * The params of api.v1.shares.list, the query of GET /api/v1/shares. At most one member is named; with none, the caller's own live shares as grantee and as sharer.
+ *
+ * Schema: sdk/shares/schema/v1/list.request.json
+ */
+export type SharesListRequest = {
+    /** An installation, <vault>/plugins/<name>: every share on it. Needs the shares admin grant (api/v1/shares/admin). */
+    installation?: string;
+    /** One resource, plugins/<vault>/<installation>/<kind>/<id>: every share on it when the caller's own grants include its share-conferring verb, else the caller's own shares on it. */
+    resource?: string;
+    /** A grantee's person id; someone else's needs the shares admin grant. */
+    grantee?: string;
+    /** A sharer's person id; someone else's needs the shares admin grant. */
+    sharer?: string;
+};
+/**
+ * Make a share.
+ *
+ * The params of api.v1.shares.create, the body of POST /api/v1/shares (ADR-174 D6).
+ *
+ * Schema: sdk/shares/schema/v1/make.request.json
+ */
+export type SharesMakeRequest = {
+    /** The one resource shared, plugins/<vault>/<installation>/<kind>/<id>. */
+    resource: string;
+    /** The shared verbs: a non-empty subset of the kind's sharing { verbs }, never its share-conferring verb. */
+    verbs: string[];
+    /** The grantee person's id. Exactly one of grantee and grantee_address names the grantee. */
+    grantee?: string;
+    /** An email address the directory resolves to the grantee. An address no person holds is invited, and the share is pending until they sign in, on a kind whose effective grantee class is addresses; otherwise it is refused share_grantee_not_admitted. */
+    grantee_address?: string;
+    /** The share's expiry, at most the installation's max_expiry from now. Absent takes the kind's default_expiry, clamped to max_expiry. */
+    expires_at?: string;
+};
+/**
+ * The vocabulary of the share acts' refusal codes (sdk/shares.Codes).
+ *
+ * Every stable code a share act is refused with. A code is never renamed; a new refusal is a new code, so a reader keeps a code it does not know as it arrived. share_not_found answers a share the caller may not see exactly as an id no share has. share_grantee_not_admitted answers an address no person holds on a kind whose effective grantee class is not addresses; on one that is, the address is invited and the share is pending until the invitee signs in.
+ *
+ * Schema: sdk/shares/schema/v1/refusal-code.json
+ */
+export type SharesRefusalCode = "share_sharer_not_a_person" | "share_sharing_disabled" | "share_resource_not_shareable" | "share_resource_unknown" | "share_actor_other_installation" | "share_verb_not_shareable" | "share_verb_confers_sharing" | "share_verb_not_held" | "share_grantee_not_admitted" | "share_guest_cannot_invite" | "share_invitation_refused" | "share_grantee_is_sharer" | "share_expiry_beyond_max" | "share_cap_active" | "share_cap_pending_invitations" | "share_exists" | "share_caller_not_a_person" | "share_not_found" | "share_sharer_lost_access" | "share_expiry_not_later" | "share_admin_required" | "share_list_query" | "shares_unavailable";
+/**
+ * A share act refused.
+ *
+ * A share act tera refused, as the shares client answers it: the route's stable code and its words, unchanged, and the detail the code declares.
+ *
+ * Schema: sdk/shares/schema/v1/refusal.json
+ */
+export type SharesRefusal = {
+    /** The route's stable code. A code a reader does not know is kept as it arrived. */
+    code: string;
+    /** The route's words for a person, unchanged. */
+    message: string;
+    /** On share_verb_not_held, share_verb_not_shareable and share_verb_confers_sharing, the verb refused. */
+    verb?: string;
+    /** On share_exists, the id of the share already there. */
+    existing?: string;
+    /** On share_invitation_refused, why the address was not invited (inviter_limited, email_unavailable, ...). */
+    invitation?: string;
+};
+/**
+ * A share.
+ *
+ * One live share, with whether it decides now: the result of api.v1.shares.create, api.v1.shares.get and api.v1.shares.patch, and each member of a list (ADR-174 D14).
+ *
+ * Schema: sdk/shares/schema/v1/share.json
+ */
+export type SharesShare = {
+    /** The share's id, a UUIDv7. */
+    id: string;
+    /** The installation whose resource is shared, <vault>/plugins/<installation>. */
+    installation: string;
+    /** The resource shared, plugins/<vault>/<installation>/<kind>/<id>. */
+    resource: string;
+    /** The shared verbs. */
+    verbs: string[] | null;
+    /** What the grantee is: person. */
+    grantee_kind: string;
+    /** The grantee person's id. */
+    grantee: string;
+    /** The id of the person who made the share. */
+    sharer: string;
+    /** The plugin principal that made the share for its sharer; absent when the sharer made it directly. */
+    created_via?: string;
+    /** When the share was made. */
+    created_at: string;
+    /** When the share stops deciding. */
+    expires_at: string;
+    /** When the share was last extended; absent if never. */
+    extended_at?: string;
+    /** Whether the share decides at least one of its verbs on the grantee's next request, computed from what decides now. */
+    deciding: boolean;
+    /** When deciding is false, the one reason why. Absent while the share decides. */
+    not_deciding?: "sharer_lost_access" | "sharing_disabled" | "installation_not_standing" | "verb_no_longer_shareable" | "pending_invitation";
+};
+/**
+ * Every type this module declares, mapped to the repository path of the schema
+ * it was generated from.
+ */
+export declare const SHARES_SCHEMAS: {
+    readonly SharesEnded: "sdk/shares/schema/v1/ended.json";
+    readonly SharesExtendRequest: "sdk/shares/schema/v1/extend.request.json";
+    readonly SharesIdRequest: "sdk/shares/schema/v1/id.request.json";
+    readonly SharesList: "sdk/shares/schema/v1/list.json";
+    readonly SharesListRequest: "sdk/shares/schema/v1/list.request.json";
+    readonly SharesMakeRequest: "sdk/shares/schema/v1/make.request.json";
+    readonly SharesRefusalCode: "sdk/shares/schema/v1/refusal-code.json";
+    readonly SharesRefusal: "sdk/shares/schema/v1/refusal.json";
+    readonly SharesShare: "sdk/shares/schema/v1/share.json";
+};

package/dist/generated/shares.js

@@ -0,0 +1,17 @@
+// Code generated by cmd/internal/genwebtypes from sdk/shares/schema/v1/; DO NOT EDIT.
+// Regenerate with `make web-types` (ADR-162 D4 item 1).
+/**
+ * Every type this module declares, mapped to the repository path of the schema
+ * it was generated from.
+ */
+export const SHARES_SCHEMAS = {
+    SharesEnded: "sdk/shares/schema/v1/ended.json",
+    SharesExtendRequest: "sdk/shares/schema/v1/extend.request.json",
+    SharesIdRequest: "sdk/shares/schema/v1/id.request.json",
+    SharesList: "sdk/shares/schema/v1/list.json",
+    SharesListRequest: "sdk/shares/schema/v1/list.request.json",
+    SharesMakeRequest: "sdk/shares/schema/v1/make.request.json",
+    SharesRefusalCode: "sdk/shares/schema/v1/refusal-code.json",
+    SharesRefusal: "sdk/shares/schema/v1/refusal.json",
+    SharesShare: "sdk/shares/schema/v1/share.json",
+};

package/dist/generated/workorder.d.ts

@@ -48,6 +48,8 @@ export type WorkOrderAnswerParams = {
     replace?: boolean;
     /** Cross ONE refusal: a select site where this Work Order's live step binding is running a candidate the new pin no longer offers (ADR-130 D5, ratified crossable 2026-09-20). The binding row is RETAINED at the same chain generation and the resume RE-SELECTS from the new candidate set, running the candidate loop against live capacity exactly as a first admission would. It does NOT preserve the candidate the run is on — that candidate is gone, which is why the refusal exists. It lifts nothing else: a capability or operation switch at a fixed site has no candidate to re-select, and a withdrawn `yields_turn` offer is frozen for the life of a pinned conversation (ADR-129 D9). Over a site whose candidate IS still offered, or a fixed site, it is a no-op and says so in the manifest rather than refusing. Only meaningful with `repin`. Authorized against `api/v1/workorders/repin/reselect` IN ADDITION to `api/v1/workorders/repin`. Pass `dry_run` first: the manifest's `would_reselect` names the site, the candidate being given up and the set the resume will choose from. */
     reselect?: boolean;
+    /** The id of the step-up a person confirmed this act with, when the Work Order's type requires one for it (ADR-173 D10): a review verdict, an answer, or an off-tera `complete` / `failed`. Call WITHOUT it first: the call is refused `step_up_required` and its error data names the step-up's `id` and the `url` the person opens to confirm it — show them that url; you cannot confirm it yourself. Then retry the IDENTICAL call with step_up = that id. `step_up_pending` means they have not confirmed yet: wait and retry the same call. A step-up confirms exactly one act with exactly this content, once. */
+    step_up?: string;
     /** The operator's exact prose. Interactive answers become one durable ledger message; other answers are wrapped as {"answer": "<text>"}. Ignored when `payload` is supplied. */
     text?: string;
 };
@@ -965,6 +967,13 @@ export type WorkOrderGetResult = {
             authorized_for?: string;
             plugin?: string;
             evidence_class?: string;
+            step_up?: {
+                id: string;
+                method: string;
+                anchor?: string;
+                at: string;
+            };
+            display_name?: string;
         };
     };
     question?: {
@@ -1217,10 +1226,22 @@ export type WorkOrderGetResult = {
         describe?: string;
         caller_is_person?: boolean;
         outcome_provenance?: string;
+        step_up?: {
+            id: string;
+            method: string;
+            anchor?: string;
+            at: string;
+        };
     };
     outcome?: {
         outcome_provenance: string;
         attested_by?: string;
+        step_up?: {
+            id: string;
+            method: string;
+            anchor?: string;
+            at: string;
+        };
     };
     relations: {
         relation: string;
@@ -1785,6 +1806,12 @@ export type WorkOrderListResult = {
             describe?: string;
             caller_is_person?: boolean;
             outcome_provenance?: string;
+            step_up?: {
+                id: string;
+                method: string;
+                anchor?: string;
+                at: string;
+            };
         };
     }[] | null;
 };
@@ -1818,6 +1845,12 @@ export type WorkOrderListOffTeraResult = {
             describe?: string;
             caller_is_person?: boolean;
             outcome_provenance?: string;
+            step_up?: {
+                id: string;
+                method: string;
+                anchor?: string;
+                at: string;
+            };
         };
         take_age_seconds?: number;
         /** On a held entry: the JSON Schema this Work Order was pinned to at its first take, which submit_result grades the record against. Absent on posted and taken entries, and when the type declares none. */
@@ -1840,6 +1873,12 @@ export type WorkOrderListOffTeraResult = {
             describe?: string;
             caller_is_person?: boolean;
             outcome_provenance?: string;
+            step_up?: {
+                id: string;
+                method: string;
+                anchor?: string;
+                at: string;
+            };
         };
         take_age_seconds?: number;
         /** On a held entry: the JSON Schema this Work Order was pinned to at its first take, which submit_result grades the record against. Absent on posted and taken entries, and when the type declares none. */
@@ -1862,6 +1901,12 @@ export type WorkOrderListOffTeraResult = {
             describe?: string;
             caller_is_person?: boolean;
             outcome_provenance?: string;
+            step_up?: {
+                id: string;
+                method: string;
+                anchor?: string;
+                at: string;
+            };
         };
         take_age_seconds?: number;
         /** On a held entry: the JSON Schema this Work Order was pinned to at its first take, which submit_result grades the record against. Absent on posted and taken entries, and when the type declares none. */
@@ -1962,6 +2007,12 @@ export type WorkOrderProgressResult = {
         describe?: string;
         caller_is_person?: boolean;
         outcome_provenance?: string;
+        step_up?: {
+            id: string;
+            method: string;
+            anchor?: string;
+            at: string;
+        };
     } | null;
     addressed_events: {
         id: number;
@@ -2550,6 +2601,8 @@ export type WorkOrderSubmitResultParams = {
     };
     /** The id of the last event you have processed on this Work Order. The response carries the events addressed to you after it (a repost, a cancel, a wake, an answer, posted guidance), at most 32 with `more` set when there were more, plus `newest_event_id`. The server keeps no cursor: omit it, or pass 0, for everything addressed so far. */
     seen_through?: number;
+    /** The id of the step-up a person confirmed this act with, when the Work Order's type requires one for it (ADR-173 D10): a review verdict, an answer, or an off-tera `complete` / `failed`. Call WITHOUT it first: the call is refused `step_up_required` and its error data names the step-up's `id` and the `url` the person opens to confirm it — show them that url; you cannot confirm it yourself. Then retry the IDENTICAL call with step_up = that id. `step_up_pending` means they have not confirmed yet: wait and retry the same call. A step-up confirms exactly one act with exactly this content, once. */
+    step_up?: string;
 };
 /**
  * `work_order.submit_result` result (v1).
@@ -2565,6 +2618,12 @@ export type WorkOrderSubmitResultResult = {
     outcome?: {
         outcome_provenance: string;
         attested_by?: string;
+        step_up?: {
+            id: string;
+            method: string;
+            anchor?: string;
+            at: string;
+        };
     };
     checks?: string;
     addressed_events: {
@@ -2612,6 +2671,12 @@ export type WorkOrderTakeResult = {
         describe?: string;
         caller_is_person?: boolean;
         outcome_provenance?: string;
+        step_up?: {
+            id: string;
+            method: string;
+            anchor?: string;
+            at: string;
+        };
     } | null;
     instructions: string;
     requirements?: string;
@@ -2675,6 +2740,8 @@ export type WorkOrderTransitionParams = {
     replace?: boolean;
     /** Cross ONE refusal: a select site where this Work Order's live step binding is running a candidate the new pin no longer offers (ADR-130 D5, ratified crossable 2026-09-20). The binding row is RETAINED at the same chain generation and the resume RE-SELECTS from the new candidate set, running the candidate loop against live capacity exactly as a first admission would. It does NOT preserve the candidate the run is on — that candidate is gone, which is why the refusal exists. It lifts nothing else: a capability or operation switch at a fixed site has no candidate to re-select, and a withdrawn `yields_turn` offer is frozen for the life of a pinned conversation (ADR-129 D9). Over a site whose candidate IS still offered, or a fixed site, it is a no-op and says so in the manifest rather than refusing. Only meaningful with `repin`. Authorized against `api/v1/workorders/repin/reselect` IN ADDITION to `api/v1/workorders/repin`. Pass `dry_run` first: the manifest's `would_reselect` names the site, the candidate being given up and the set the resume will choose from. */
     reselect?: boolean;
+    /** The id of the step-up a person confirmed this act with, when the Work Order's type requires one for it (ADR-173 D10): a review verdict, an answer, or an off-tera `complete` / `failed`. Call WITHOUT it first: the call is refused `step_up_required` and its error data names the step-up's `id` and the `url` the person opens to confirm it — show them that url; you cannot confirm it yourself. Then retry the IDENTICAL call with step_up = that id. `step_up_pending` means they have not confirmed yet: wait and retry the same call. A step-up confirms exactly one act with exactly this content, once. */
+    step_up?: string;
     /** action=answer only: the operator's answer text. Read work_order.get(id).question first — that is what is being asked. */
     text?: string;
 };
@@ -3102,6 +3169,12 @@ export type WorkOrderTreeResult = {
         outcome?: {
             outcome_provenance: string;
             attested_by?: string;
+            step_up?: {
+                id: string;
+                method: string;
+                anchor?: string;
+                at: string;
+            };
         };
         replaced?: {
             relation: string;
@@ -3326,6 +3399,12 @@ export type WorkOrderTreeResult = {
         outcome?: {
             outcome_provenance: string;
             attested_by?: string;
+            step_up?: {
+                id: string;
+                method: string;
+                anchor?: string;
+                at: string;
+            };
         };
         replaced?: {
             relation: string;

package/dist/index.d.ts

@@ -1,12 +1,15 @@
-export { ROUTE_PREFIX, routePath } from "./routes.ts";
+export { ROOT_BASE, ROUTE_PREFIX, appBase, routePath, underBase } from "./routes.ts";
 export { TeraClient, KitRequestError, UNRECOGNIZED_RESPONSE, type FeedOptions, type InvokeVerdict, type KitErrorBody, type TeraClientOptions, type UploadOptions, type UploadProgress, type UploadRequest, type VerbRefusal, } from "./client.ts";
+export { STEP_UP_HEADER, STEP_UP_POLL_MS, STEP_UP_REQUIRED, STEP_UP_RESUME_PARAM, StepUpError, resumedStepUp, stepUpChallengeOf, stepUpPageURL, type StepUpChallenge, type StepUpEnd, type StepUpOptions, type StepUpWindow, } from "./stepup.ts";
 export { BASE_DELAY_MS, MAX_DELAY_MS, REPLAY_LIMIT, REPLAY_WINDOW_MS, HEARTBEAT_GRACE_MS, REAUTHENTICATE_EVENT, FeedConnection, browserSignals, defaultOrderKey, type Clock, type FeedConnectionOptions, type FeedConnectionPhase, type FeedConnectionState, type FeedFrame, type FeedLoss, type FeedSignal, type FeedSignals, } from "./feed/connection.ts";
 export { FeedOpenError, SSEParser, fetchOpener, isRefusal, type FeedOpener, type SSEEvent } from "./feed/sse.ts";
 export type * from "./generated/feed.ts";
 export type * from "./generated/kit.ts";
+export type * from "./generated/shares.ts";
 export type * from "./generated/workorder.ts";
 export type * from "./generated/workorder-events.ts";
 export { FEED_SCHEMAS } from "./generated/feed.ts";
 export { KIT_ROUTE_PREFIX, KIT_ROUTE_TABLE, KIT_SCHEMAS, KIT_SIGNOUT_PATH } from "./generated/kit.ts";
+export { SHARES_SCHEMAS } from "./generated/shares.ts";
 export { WORK_ORDER_SCHEMAS } from "./generated/workorder.ts";
 export { WORK_ORDER_EVENT_SCHEMAS } from "./generated/workorder-events.ts";

package/dist/index.js

@@ -2,11 +2,13 @@
 //
 // Framework-free, with no runtime dependencies: it carries no UI component,
 // because the framework is the author's.
-export { ROUTE_PREFIX, routePath } from "./routes.js";
+export { ROOT_BASE, ROUTE_PREFIX, appBase, routePath, underBase } from "./routes.js";
 export { TeraClient, KitRequestError, UNRECOGNIZED_RESPONSE, } from "./client.js";
+export { STEP_UP_HEADER, STEP_UP_POLL_MS, STEP_UP_REQUIRED, STEP_UP_RESUME_PARAM, StepUpError, resumedStepUp, stepUpChallengeOf, stepUpPageURL, } from "./stepup.js";
 export { BASE_DELAY_MS, MAX_DELAY_MS, REPLAY_LIMIT, REPLAY_WINDOW_MS, HEARTBEAT_GRACE_MS, REAUTHENTICATE_EVENT, FeedConnection, browserSignals, defaultOrderKey, } from "./feed/connection.js";
 export { FeedOpenError, SSEParser, fetchOpener, isRefusal } from "./feed/sse.js";
 export { FEED_SCHEMAS } from "./generated/feed.js";
 export { KIT_ROUTE_PREFIX, KIT_ROUTE_TABLE, KIT_SCHEMAS, KIT_SIGNOUT_PATH } from "./generated/kit.js";
+export { SHARES_SCHEMAS } from "./generated/shares.js";
 export { WORK_ORDER_SCHEMAS } from "./generated/workorder.js";
 export { WORK_ORDER_EVENT_SCHEMAS } from "./generated/workorder-events.js";

package/dist/routes.d.ts

@@ -8,3 +8,18 @@ export declare const ROUTE_PREFIX = "/tera/v1/";
  * collapses the dot segments and encoding does not change them.
  */
 export declare function routePath(...segments: string[]): string;
+/** The base of an app served at the root of its origin. */
+export declare const ROOT_BASE = "/";
+/**
+ * appBase checks the path an app is served under on its origin and answers it
+ * ending in `/`: `/` on a plugin's own origin, `/plugins/<name>/` on a
+ * path-based installation. A base that is not a root-absolute path on the
+ * page's own origin is refused.
+ */
+export declare function appBase(base?: string): string;
+/**
+ * underBase places a path the kit names under an app's base: a kit path
+ * (`/tera/v1/me`, from {@link routePath}) or a path relative to the base
+ * (`_tera/signout`, the kit's `signout_path`) alike.
+ */
+export declare function underBase(base: string, path: string): string;

package/dist/routes.js

@@ -5,6 +5,12 @@
 // The route table itself is declared once, in Go, under sdk/plugin/webui, and
 // generated into ./generated/kit.ts. What is here is how a path is built from
 // it.
+//
+// The table's paths are the kit's own: tera's proxy serves a plugin either at
+// the root of its own origin or, on a path-based installation, under
+// `/plugins/<name>/` on tera's origin, and strips that prefix before the kit
+// sees a request. A page therefore reaches every route, and tera's sign-out,
+// under its app's base (`/` or `/plugins/<name>/`), which only the page knows.
 import { KIT_ROUTE_PREFIX } from "./generated/kit.js";
 /** The prefix every kit route is served under. */
 export const ROUTE_PREFIX = KIT_ROUTE_PREFIX;
@@ -30,3 +36,25 @@ export function routePath(...segments) {
     });
     return ROUTE_PREFIX + parts.join("/");
 }
+/** The base of an app served at the root of its origin. */
+export const ROOT_BASE = "/";
+/**
+ * appBase checks the path an app is served under on its origin and answers it
+ * ending in `/`: `/` on a plugin's own origin, `/plugins/<name>/` on a
+ * path-based installation. A base that is not a root-absolute path on the
+ * page's own origin is refused.
+ */
+export function appBase(base = ROOT_BASE) {
+    if (!base.startsWith("/") || base.startsWith("//") || /[?#\\]/.test(base)) {
+        throw new TypeError(`appBase: ${JSON.stringify(base)} is not a root-absolute path on this origin`);
+    }
+    return base.endsWith("/") ? base : base + "/";
+}
+/**
+ * underBase places a path the kit names under an app's base: a kit path
+ * (`/tera/v1/me`, from {@link routePath}) or a path relative to the base
+ * (`_tera/signout`, the kit's `signout_path`) alike.
+ */
+export function underBase(base, path) {
+    return appBase(base) + (path.startsWith("/") ? path.slice(1) : path);
+}

package/dist/stepup.d.ts

@@ -0,0 +1,87 @@
+/**
+ * A person's step-up, from the page's side (ADR-173 D11 step 3).
+ *
+ * An act the plugin requires the person's confirmation for is refused
+ * `step_up_required`: by the plugin's own route, in the kit's envelope with
+ * `error.step_up`, or by a Work Order verb, relayed by the invoke route with
+ * the challenge in the refusal's `data.step_up`. Either names the step-up's
+ * id and the page on tera's origin the person confirms it on. The client then:
+ *
+ * 1. opens that page in a new window, and when the browser will not open one,
+ *    navigates to it instead with a `return_to` naming this page, which tera
+ *    accepts only on the plugin's own origin;
+ * 2. polls `GET /tera/v1/step-ups/{id}` until the step-up is satisfied,
+ *    declined or expired, and closes the window it opened;
+ * 3. sends the identical request again with `Tera-Step-Up: <id>` — or, for a
+ *    Work Order verb, with `step_up` in its params.
+ *
+ * A step-up confirms one act once: nothing here holds an id past the retry it
+ * was confirmed for, except across the navigation fallback, where the id rides
+ * back on the `return_to` as {@link STEP_UP_RESUME_PARAM} and is spent by the
+ * first request that needs a step-up after the page loads again.
+ */
+import type { KitError } from "./generated/kit.ts";
+/** The request header that carries a confirmed step-up's id to the plugin's route. */
+export declare const STEP_UP_HEADER = "Tera-Step-Up";
+/** The code of a refusal that needs the person's confirmation. */
+export declare const STEP_UP_REQUIRED = "step_up_required";
+/**
+ * The query parameter the navigation fallback adds to its `return_to`, naming
+ * the step-up the person went to confirm, so the page that loads again
+ * resumes it rather than beginning another.
+ */
+export declare const STEP_UP_RESUME_PARAM = "tera_step_up";
+/** How often the step-up's state is read while the person confirms it, by default. */
+export declare const STEP_UP_POLL_MS = 1000;
+/** What a refusal names of the step-up it needs: the kit envelope's `error.step_up`. */
+export type StepUpChallenge = NonNullable<KitError["error"]["step_up"]>;
+/** The part of a `Window` the client uses: whether the person closed it, and closing it. */
+export interface StepUpWindow {
+    readonly closed: boolean;
+    close(): void;
+}
+export interface StepUpOptions {
+    /** Opens the step-up's page in a new window; `window.open(url, "_blank")` when absent. Answers null when the browser would not open one. */
+    openWindow?: (url: string) => StepUpWindow | null;
+    /** The page's own URL, which the navigation fallback returns to; `location.href` when absent. */
+    pageURL?: () => string;
+    /** Waits between reads of the step-up's state; a timer when absent. */
+    sleep?: (ms: number) => Promise<void>;
+    /** How long to wait between reads; {@link STEP_UP_POLL_MS} when absent. */
+    pollIntervalMs?: number;
+}
+/**
+ * How a step-up ended without being confirmed:
+ * - `declined` — the person said they did not ask for it;
+ * - `expired` — nobody confirmed it in time;
+ * - `spent` — it confirmed another request already;
+ * - `abandoned` — the person closed its window and it is still waiting;
+ * - `navigated` — the browser would not open a window, so the page was sent to
+ *   tera's; it returns here, and the next request that needs a step-up resumes
+ *   this one.
+ */
+export type StepUpEnd = "declined" | "expired" | "spent" | "abandoned" | "navigated";
+/** A step-up the person did not confirm: the request it was for was not sent again. */
+export declare class StepUpError extends Error {
+    /** The step-up's id. */
+    readonly stepUpId: string;
+    /** How it ended. */
+    readonly end: StepUpEnd;
+    constructor(stepUpId: string, end: StepUpEnd, message: string);
+}
+/**
+ * The step-up a refusal needs confirmed, when it is one this client can have
+ * confirmed: code `step_up_required` with a page to open. A refusal naming an
+ * ended step-up carries no page, and is not one.
+ */
+export declare function stepUpChallengeOf(code: string, stepUp: unknown): StepUpChallenge | null;
+/**
+ * The step-up page's URL with `return_to` set to `returnTo`, itself carrying
+ * {@link STEP_UP_RESUME_PARAM}. tera follows it back only when it is on the
+ * plugin's own origin.
+ */
+export declare function stepUpPageURL(pageURL: string, stepUpId: string, returnTo: string): string;
+/** The step-up id a page loaded through the navigation fallback carries back, or null. */
+export declare function resumedStepUp(pageURL: string): string | null;
+export declare function defaultOpenWindow(url: string): StepUpWindow | null;
+export declare function defaultSleep(ms: number): Promise<void>;

package/dist/stepup.js

@@ -0,0 +1,66 @@
+/** The request header that carries a confirmed step-up's id to the plugin's route. */
+export const STEP_UP_HEADER = "Tera-Step-Up";
+/** The code of a refusal that needs the person's confirmation. */
+export const STEP_UP_REQUIRED = "step_up_required";
+/**
+ * The query parameter the navigation fallback adds to its `return_to`, naming
+ * the step-up the person went to confirm, so the page that loads again
+ * resumes it rather than beginning another.
+ */
+export const STEP_UP_RESUME_PARAM = "tera_step_up";
+/** How often the step-up's state is read while the person confirms it, by default. */
+export const STEP_UP_POLL_MS = 1000;
+/** A step-up the person did not confirm: the request it was for was not sent again. */
+export class StepUpError extends Error {
+    /** The step-up's id. */
+    stepUpId;
+    /** How it ended. */
+    end;
+    constructor(stepUpId, end, message) {
+        super(message);
+        this.name = "StepUpError";
+        this.stepUpId = stepUpId;
+        this.end = end;
+    }
+}
+/**
+ * The step-up a refusal needs confirmed, when it is one this client can have
+ * confirmed: code `step_up_required` with a page to open. A refusal naming an
+ * ended step-up carries no page, and is not one.
+ */
+export function stepUpChallengeOf(code, stepUp) {
+    if (code !== STEP_UP_REQUIRED || typeof stepUp !== "object" || stepUp === null)
+        return null;
+    const c = stepUp;
+    if (typeof c.id !== "string" || c.id === "" || typeof c.url !== "string" || c.url === "")
+        return null;
+    return c;
+}
+/**
+ * The step-up page's URL with `return_to` set to `returnTo`, itself carrying
+ * {@link STEP_UP_RESUME_PARAM}. tera follows it back only when it is on the
+ * plugin's own origin.
+ */
+export function stepUpPageURL(pageURL, stepUpId, returnTo) {
+    const back = new URL(returnTo);
+    back.searchParams.set(STEP_UP_RESUME_PARAM, stepUpId);
+    const page = new URL(pageURL);
+    page.searchParams.set("return_to", back.toString());
+    return page.toString();
+}
+/** The step-up id a page loaded through the navigation fallback carries back, or null. */
+export function resumedStepUp(pageURL) {
+    try {
+        const id = new URL(pageURL).searchParams.get(STEP_UP_RESUME_PARAM);
+        return id === null || id === "" ? null : id;
+    }
+    catch {
+        return null;
+    }
+}
+export function defaultOpenWindow(url) {
+    return globalThis.open?.(url, "_blank") ?? null;
+}
+export function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kottera/tera-web",
-  "version": "0.1.0-rc.3",
+  "version": "0.1.0-rc.4",
   "description": "The browser half of a UI over tera: a framework-free client for the /tera/v1/ routes a plugin's webui kit serves (ADR-162 D4).",
   "license": "Apache-2.0",
   "repository": {