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

package/README.md

@@ -12,6 +12,8 @@ author's — and has no runtime dependencies. It is not yet published.
 | `src/index.ts` | The package's one entry point. Everything public is re-exported here. |
 | `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/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/signin.ts` | Signing in again after tera forgets the page's session, as a daemon restart does: `isSignInRequired(response)` recognises the UI proxy's 401 `sign_in_required`, and `reSignIn()` loads the page again, which signs the person in with no prompt while their tera session lives. `TeraClient` and `FeedConnection` do it on their own, once; a page reading its own routes with its own `fetch` applies `isSignInRequired`. |
 | `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). |
@@ -37,3 +39,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

@@ -118,6 +118,8 @@ export declare class TeraClient {
     private readonly pollMs;
     /** Whether the step-up the page was loaded back with has been taken up. */
     private resumeTaken;
+    /** Whether this client has loaded the page again to sign in. */
+    private signingIn;
     constructor(options?: TeraClientOptions);
     /** `GET /tera/v1/me`: who is signed in, and where to send them to sign out. */
     me(): Promise<KitMeResponse>;
@@ -159,9 +161,20 @@ export declare class TeraClient {
      * 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.
+     * buffer, never a stream. A `sign_in_required` answer loads the page again
+     * ({@link TeraClient.reSignIn}) and is returned as it arrived.
      */
     fetch(path: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Loads the page again to sign the person in to the plugin's origin: a
+     * top-level navigation to the page's own URL, which tera's UI proxy answers
+     * with its silent sign-in. The client does it itself on a
+     * `sign_in_required` answer; a page calls it for one it read on its own.
+     * It navigates once per client: a second call does nothing.
+     */
+    reSignIn(): void;
+    /** Loads the page again when `request` rejects as `sign_in_required`, and rejects as it did. */
+    private signInOnRefusal;
     /**
      * 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

package/dist/client.js

@@ -43,13 +43,23 @@
  * 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.
  *
+ * # Signing in again
+ *
+ * A request tera's UI proxy answers `sign_in_required` — the person's session
+ * on the plugin's origin is gone, as it is after a daemon restart — loads the
+ * page again ({@link TeraClient.reSignIn}), which signs the person in, and
+ * still rejects (or, from {@link TeraClient.fetch}, answers) as it arrived.
+ * The page is loaded again once per client, however many requests were
+ * refused together. A feed the client opens does the same.
+ *
  * 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 { appBase, routePath, underBase } from "./routes.js";
+import { appBase, isBaseRelative, routePath, underBase } from "./routes.js";
 import { FeedConnection } from "./feed/connection.js";
 import { fetchOpener } from "./feed/sse.js";
+import { SIGN_IN_REQUIRED, isSignInRequired } from "./signin.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
@@ -102,6 +112,8 @@ export class TeraClient {
     pollMs;
     /** Whether the step-up the page was loaded back with has been taken up. */
     resumeTaken = false;
+    /** Whether this client has loaded the page again to sign in. */
+    signingIn = false;
     constructor(options = {}) {
         this.base = appBase(options.base);
         this.fetchFn = options.fetch ?? ((...args) => globalThis.fetch(...args));
@@ -157,7 +169,7 @@ export class TeraClient {
      * the page no longer wants it.
      */
     feed(options) {
-        return new FeedConnection({ ...options, base: this.base, open: fetchOpener(this.fetchFn) });
+        return new FeedConnection({ ...options, base: this.base, open: fetchOpener(this.fetchFn), reSignIn: () => this.reSignIn() });
     }
     /**
      * `POST /tera/v1/uploads`: sends one file as the signed-in person and
@@ -167,13 +179,13 @@ export class TeraClient {
      */
     async upload(file, options = {}) {
         try {
-            return await this.uploadOnce(file, options, null);
+            return await this.signInOnRefusal(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));
+            return this.signInOnRefusal(this.uploadOnce(file, options, await this.confirmStepUp(challenge)));
         }
     }
     uploadOnce(file, options, stepUpId) {
@@ -246,15 +258,47 @@ export class TeraClient {
      * 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.
+     * buffer, never a stream. A `sign_in_required` answer loads the page again
+     * ({@link TeraClient.reSignIn}) and is returned as it arrived.
      */
     async fetch(path, init = {}) {
         const url = underBase(this.base, path);
         const first = await this.fetchSameOrigin(url, init, null);
+        if (await isSignInRequired(first)) {
+            this.reSignIn();
+            return first;
+        }
         const challenge = await stepUpRefusalOf(first);
         if (challenge === null)
             return first;
-        return this.fetchSameOrigin(url, init, await this.confirmStepUp(challenge));
+        const second = await this.fetchSameOrigin(url, init, await this.confirmStepUp(challenge));
+        if (await isSignInRequired(second))
+            this.reSignIn();
+        return second;
+    }
+    /**
+     * Loads the page again to sign the person in to the plugin's origin: a
+     * top-level navigation to the page's own URL, which tera's UI proxy answers
+     * with its silent sign-in. The client does it itself on a
+     * `sign_in_required` answer; a page calls it for one it read on its own.
+     * It navigates once per client: a second call does nothing.
+     */
+    reSignIn() {
+        if (this.signingIn)
+            return;
+        this.signingIn = true;
+        this.navigate(this.pageURL());
+    }
+    /** Loads the page again when `request` rejects as `sign_in_required`, and rejects as it did. */
+    async signInOnRefusal(request) {
+        try {
+            return await request;
+        }
+        catch (err) {
+            if (err instanceof KitRequestError && err.status === 401 && err.code === SIGN_IN_REQUIRED)
+                this.reSignIn();
+            throw err;
+        }
     }
     /**
      * Has the person confirm the step-up `challenge` names, and answers its id
@@ -335,7 +379,7 @@ export class TeraClient {
      */
     async signOut() {
         const { signout_path: path } = await this.me();
-        if (typeof path !== "string" || path === "" || path.startsWith("/") || /^[^/?#]*:/.test(path) || /[\\]/.test(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(underBase(this.base, path));
@@ -346,13 +390,13 @@ export class TeraClient {
     }
     async json(url, init, stepUp = true) {
         try {
-            return await this.jsonOnce(url, init, null);
+            return await this.signInOnRefusal(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));
+            return this.signInOnRefusal(this.jsonOnce(url, init, await this.confirmStepUp(challenge)));
         }
     }
     async jsonOnce(url, init, stepUpId) {

package/dist/feed/connection.d.ts

@@ -99,6 +99,12 @@ export interface FeedConnectionOptions {
     orderKey?: (record: FeedFrameRecord) => number | undefined;
     /** Opens one stream; {@link fetchOpener} when absent. */
     open?: FeedOpener;
+    /**
+     * Loads the page again when tera's UI proxy refuses the stream
+     * `sign_in_required`, which signs the person in; {@link reSignIn} when
+     * absent. A {@link TeraClient}'s feed passes the client's own.
+     */
+    reSignIn?: () => void;
     clock?: Clock;
     /** {@link browserSignals} when absent. */
     signals?: FeedSignals;

package/dist/feed/connection.js

@@ -16,6 +16,7 @@
  * | a `reauthenticate` event (D7: the token expired)    | reconnect at once                  |
  * | a `credential_expired` status (D7, the same ending)  | reconnect at once                  |
  * | a status reporting loss                             | one replay, rationed (see Loss)    |
+ * | a 401 `sign_in_required` (tera forgot the session)  | STOP, and load the page again      |
  * | any other 4xx, a 501, or a success that is not an   | STOP: a refusal. A person has to   |
  * | event stream                                        | act ({@link FeedConnection.retry}) |
  *
@@ -65,6 +66,7 @@
  */
 import { routePath, underBase, ROOT_BASE } from "../routes.js";
 import { fetchOpener, isRefusal } from "./sse.js";
+import { isSignInRequiredAnswer, reSignIn } from "../signin.js";
 export const BASE_DELAY_MS = 1_000;
 export const MAX_DELAY_MS = 30_000;
 /** Replays allowed in {@link REPLAY_WINDOW_MS} before a loss is surfaced. */
@@ -233,6 +235,10 @@ export class FeedConnection {
                 this.generation += 1;
                 this.teardown();
                 this.set({ phase: "refused", refusal: err, lastError: err.message, delayMs: 0 });
+                // The person's session on the plugin's origin is gone; only a page
+                // load brings it back, and that ends this connection with the page.
+                if (isSignInRequiredAnswer(err.status, err.contentType, err.body))
+                    (this.options.reSignIn ?? reSignIn)();
                 return;
             }
             this.reopen(err instanceof Error ? err.message : String(err));

package/dist/generated/kit.d.ts

@@ -2,11 +2,11 @@ import type { FeedFrameRecord, FeedFrameStatus } from "./feed.ts";
 /**
  * The vocabulary of the kit's own error codes (sdk/plugin/webui.KitCodes).
  *
- * Every code the kit answers with when no verb gave a verdict. Only tera_unavailable is retryable. A failure envelope may also carry a verb's own code, or tera's own code for a call it refused, verbatim, which is not a member: a reader keeps a code it does not know as it arrived and branches on retryable.
+ * Every code the kit answers with when no verb gave a verdict, and sign_in_required, which tera's UI proxy answers in front of the kit when a request that is not a page load reaches the plugin's origin with no live session: load the page again to sign in. Only tera_unavailable is retryable. A failure envelope may also carry a verb's own code, or tera's own code for a call it refused, verbatim, which is not a member: a reader keeps a code it does not know as it arrived and branches on retryable.
  *
  * 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" | "step_up_required";
+export type KitErrorCode = "unauthenticated" | "cross_origin" | "route_not_found" | "method_not_allowed" | "route_not_served" | "invalid_request" | "exchange_refused" | "tera_unavailable" | "step_up_required" | "sign_in_required";
 /**
  * Kit error envelope.
  *
@@ -33,6 +33,7 @@ export type KitError = {
             url?: string;
             methods?: string[];
             expires_at?: string;
+            label?: string;
             state?: string;
         };
     };
@@ -85,6 +86,8 @@ export type KitMeResponse = {
     subject: string;
     /** 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. */
@@ -155,10 +158,13 @@ export declare const KIT_SCHEMAS: {
 export declare const KIT_ROUTE_PREFIX = "/tera/v1/";
 /** 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 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: {
@@ -170,7 +176,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";

package/dist/generated/kit.js

@@ -17,10 +17,13 @@ export const KIT_SCHEMAS = {
 export const KIT_ROUTE_PREFIX = "/tera/v1/";
 /** 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";
+/** tera's proxy's phone path, which `GET /tera/v1/me` answers as phone_path: relative, resolved against the app's base. */
+export const KIT_PHONE_PATH = "_tera/phone";
 /** 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",
+    phone_path: "_tera/phone",
     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: {
@@ -33,7 +36,7 @@ export const KIT_ROUTE_TABLE = {
             name: "me",
             method: "GET",
             path: "/tera/v1/me",
-            summary: "Who is signed in, and where to send them to sign out.",
+            summary: "Who is signed in, where to send them to sign out, and where to send them to open a page on their phone.",
             same_origin: false,
             response: {
                 media_type: "application/json",

package/dist/generated/shares.d.ts

@@ -124,7 +124,7 @@ export type SharesMakeRequest = {
  *
  * 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";
+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_plugin_only" | "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.
  *
@@ -143,6 +143,8 @@ export type SharesRefusal = {
     existing?: string;
     /** On share_invitation_refused, why the address was not invited (inviter_limited, email_unavailable, ...). */
     invitation?: string;
+    /** On share_plugin_only, the installation's name: the plugin the share is made or extended through. */
+    plugin?: string;
 };
 /**
  * A share.

package/dist/generated/workorder.d.ts

@@ -476,6 +476,21 @@ export type WorkOrderCreateParams = {
     needs_approval?: boolean;
     /** Existing Work Order to file this one beneath, making it part of that train. It must be one you can read with work_order.get; one you cannot is refused exactly as that read would refuse it. The new Work Order takes that parent's cohort, verbatim; beside it `cohort` accepts `{"new": true, "label"?: …}`, a sub-unit nested under the parent's cohort, and `{"of": "<work-order-id>"}`, joining the cohort of a Work Order in the parent's tree. */
     parent_id?: string;
+    /** Directories of the filing plugin's data volume this Work Order's dispatch is handed. Only a plugin may name them — as itself or acting for a person, or on create_child as the taker of its own off-tera work — and only for a type of its own vault; any other filer is refused (plugin_data_not_a_plugin). The dispatch is placed on the host holding the volume and sees the named directories and nothing else of it. Name input, output or both; neither may contain the other. */
+    plugin_data?: {
+        /** The one directory the dispatch reads, mounted read-only and told to the step in TERA_PLUGIN_DATA_INPUT. It must exist when the step starts (plugin_data_unavailable). */
+        input?: {
+            /** A clean relative path inside the plugin's data volume: no `..`, not absolute. */
+            dir: string;
+        };
+        /** The one directory the dispatch writes, told to the step in TERA_PLUGIN_DATA_OUTPUT. Created if absent; refused when not empty at the step's start (plugin_output_not_empty). */
+        output?: {
+            /** The most the directory may hold when the step ends: at least 1 GiB, at most the installation's hosted { step_output_limit }. Past it the step fails (plugin_output_bound_exceeded). */
+            bound_bytes: number;
+            /** A clean relative path inside the plugin's data volume: no `..`, not absolute. */
+            dir: string;
+        };
+    };
     /** Dispatch priority; higher runs sooner among ready Work Orders. */
     priority?: number;
     /** Typed, NON-CAUSAL relations from this Work Order to others (supersedes / duplicate_of / about / related). Each entry is a {relation, work_order_id} pair with an optional note, and `work_order_id` is a bare Work Order id — the same spelling `depends_on` and `parent_id` use, never a `vault://` ref. Set them here when the fact is known at filing time, which for the superseding case it usually is; discovered later, use work_order.relate. Three of the four gate nothing: no dispatch is blocked, delayed or cancelled by `duplicate_of`, `about` or `related`. A `supersedes` entry is the exception and it is the point of setting one here — it RETIRES the Work Order it names, in this call's own transaction: that Work Order moves to `superseded` with `superseded_by` set to this one, and can no longer be retried. The target must be in `failed:awaiting-ack`; one that is still running is refused, and the door is work_order.force_fail(id, reason) first. A terminal one is refused too — there is no retry to close — and so is a `supersedes` entry on a drafted create, since a draft may never be released. To record the claim WITHOUT moving the row, use work_order.relate. Same authorization as work_order.relate — a worker-class caller is refused, and an operator-class one needs `api/v1/workorders/relate` on top of its create grant, because the edge is the relate operation whichever call delivered it. Every target must exist, and no two entries may name the same target. Reach on the target is required for the two EVALUATIVE relations (`supersedes`, `duplicate_of`) and not for the two descriptive ones (`about`, `related`), per entry rather than per payload. */
@@ -590,6 +605,21 @@ export type WorkOrderCreateChildParams = {
     on_child_failure?: "fail-fast" | "wait-others" | "ignore";
     /** The off-tera Work Order you hold, to file this child beneath (ADR-139 D6). Honoured only for its current taker; omit it inside a dispatch, where the parent is the dispatch's own Work Order. */
     parent?: string;
+    /** Directories of the filing plugin's data volume this Work Order's dispatch is handed. Only a plugin may name them — as itself or acting for a person, or on create_child as the taker of its own off-tera work — and only for a type of its own vault; any other filer is refused (plugin_data_not_a_plugin). The dispatch is placed on the host holding the volume and sees the named directories and nothing else of it. Name input, output or both; neither may contain the other. */
+    plugin_data?: {
+        /** The one directory the dispatch reads, mounted read-only and told to the step in TERA_PLUGIN_DATA_INPUT. It must exist when the step starts (plugin_data_unavailable). */
+        input?: {
+            /** A clean relative path inside the plugin's data volume: no `..`, not absolute. */
+            dir: string;
+        };
+        /** The one directory the dispatch writes, told to the step in TERA_PLUGIN_DATA_OUTPUT. Created if absent; refused when not empty at the step's start (plugin_output_not_empty). */
+        output?: {
+            /** The most the directory may hold when the step ends: at least 1 GiB, at most the installation's hosted { step_output_limit }. Past it the step fails (plugin_output_bound_exceeded). */
+            bound_bytes: number;
+            /** A clean relative path inside the plugin's data volume: no `..`, not absolute. */
+            dir: string;
+        };
+    };
     /** Informational: echoed back for your own bookkeeping. What governs whether the parent waits is the wait it declares, not this field. */
     policy?: "wait-for-all" | "wait-for-any" | "fire-and-forget";
     /** Dispatch priority; higher runs sooner among ready Work Orders. */
@@ -1404,6 +1434,11 @@ export type WorkOrderGetResult = {
     } | null;
     created_by?: string;
     created_via?: string;
+    released_via?: string;
+    lent_by?: string;
+    arrival_evidence?: {
+        [key: string]: string;
+    };
     created_at: string;
     updated_at: string;
     off_tera: boolean;

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { ROOT_BASE, ROUTE_PREFIX, appBase, routePath, underBase } from "./routes.ts";
+export { phoneURL } from "./phone.ts";
+export { SIGN_IN_REQUIRED, isSignInRequired, isSignInRequiredAnswer, reSignIn, type ReSignInOptions } from "./signin.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";
@@ -9,7 +11,7 @@ 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 { KIT_ROUTE_PREFIX, KIT_ROUTE_TABLE, KIT_PHONE_PATH, 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

@@ -3,12 +3,14 @@
 // Framework-free, with no runtime dependencies: it carries no UI component,
 // because the framework is the author's.
 export { ROOT_BASE, ROUTE_PREFIX, appBase, routePath, underBase } from "./routes.js";
+export { phoneURL } from "./phone.js";
+export { SIGN_IN_REQUIRED, isSignInRequired, isSignInRequiredAnswer, reSignIn } from "./signin.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 { KIT_ROUTE_PREFIX, KIT_ROUTE_TABLE, KIT_PHONE_PATH, 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/phone.d.ts

@@ -0,0 +1,11 @@
+import type { KitMeResponse } from "./generated/kit.ts";
+/**
+ * phoneURL builds the "Open on your phone" link of the page at `location`:
+ * the `phone_path` `me` answers, resolved against the app's `base` (`/`, or
+ * `/plugins/<name>/` on a path-based installation, as
+ * `TeraClientOptions.base`), with `next` set to `location.href`, fragment
+ * included. It answers a root-absolute path on the page's own origin. A
+ * `phone_path` that is not a path relative to the base is refused rather
+ * than followed.
+ */
+export declare function phoneURL(me: Pick<KitMeResponse, "phone_path">, location: Pick<Location, "href">, base?: string): string;

package/dist/phone.js

@@ -0,0 +1,24 @@
+// "Open on your phone" (ADR-177 D4): a link to tera's phone page, which draws
+// the page's URL as a QR code. A page builds it without knowing tera's URL:
+// it links to its own proxy's phone path, under its app's base, and tera's
+// proxy redirects to tera's phone page for a URL under this installation's
+// own base and to the app's base for any other.
+import { ROOT_BASE, isBaseRelative, underBase } from "./routes.js";
+/** The query parameter naming the page the phone opens. */
+const NEXT_PARAM = "next";
+/**
+ * phoneURL builds the "Open on your phone" link of the page at `location`:
+ * the `phone_path` `me` answers, resolved against the app's `base` (`/`, or
+ * `/plugins/<name>/` on a path-based installation, as
+ * `TeraClientOptions.base`), with `next` set to `location.href`, fragment
+ * included. It answers a root-absolute path on the page's own origin. A
+ * `phone_path` that is not a path relative to the base is refused rather
+ * than followed.
+ */
+export function phoneURL(me, location, base = ROOT_BASE) {
+    const path = me.phone_path;
+    if (!isBaseRelative(path)) {
+        throw new TypeError(`phoneURL: phone_path is not a path relative to the app's base: ${JSON.stringify(path)}`);
+    }
+    return underBase(base, path) + "?" + new URLSearchParams({ [NEXT_PARAM]: location.href }).toString();
+}

package/dist/routes.d.ts

@@ -23,3 +23,10 @@ export declare function appBase(base?: string): string;
  * (`_tera/signout`, the kit's `signout_path`) alike.
  */
 export declare function underBase(base: string, path: string): string;
+/**
+ * isBaseRelative reports whether a path the kit answers (`signout_path`,
+ * `phone_path`) is relative to the app's base: not empty, not root-absolute,
+ * naming no scheme and holding no backslash, so that {@link underBase} keeps
+ * it on the page's own origin under its base.
+ */
+export declare function isBaseRelative(path: unknown): path is string;

package/dist/routes.js

@@ -58,3 +58,12 @@ export function appBase(base = ROOT_BASE) {
 export function underBase(base, path) {
     return appBase(base) + (path.startsWith("/") ? path.slice(1) : path);
 }
+/**
+ * isBaseRelative reports whether a path the kit answers (`signout_path`,
+ * `phone_path`) is relative to the app's base: not empty, not root-absolute,
+ * naming no scheme and holding no backslash, so that {@link underBase} keeps
+ * it on the page's own origin under its base.
+ */
+export function isBaseRelative(path) {
+    return typeof path === "string" && path !== "" && !path.startsWith("/") && !/^[^/?#]*:/.test(path) && !path.includes("\\");
+}

package/dist/signin.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Signing in again after tera forgets the page's session.
+ *
+ * tera's UI proxy holds a plugin origin's sessions in memory, so a daemon
+ * restart forgets every one. Only a page load can sign the person in again —
+ * silently, while their tera session lives — so the proxy answers anything
+ * else that arrives with no live session, a script's `fetch` among them, 401
+ * in the kit's envelope with code {@link SIGN_IN_REQUIRED}. The page recovers
+ * by loading itself again ({@link reSignIn}).
+ *
+ * That cannot loop: a page load never receives this answer, it starts the
+ * sign-in. A person whose tera session is gone too lands on tera's sign-in
+ * page, which is where they have to be.
+ *
+ * It is not the kit's `unauthenticated`, which says the request did reach the
+ * plugin, with no verified caller; loading the page again does not fix that.
+ *
+ * {@link TeraClient} and {@link FeedConnection} react on their own. A page
+ * reading one of the plugin's routes with its own `fetch` applies
+ * {@link isSignInRequired} to the response:
+ *
+ *     const res = await fetch("api/boards");
+ *     if (await isSignInRequired(res)) return reSignIn();
+ */
+/** The code of the proxy's answer to a request that needs the page loaded again to sign in. */
+export declare const SIGN_IN_REQUIRED = "sign_in_required";
+export interface ReSignInOptions {
+    /** Sends the page to a URL; `location.assign` when absent. */
+    navigate?: (url: string) => void;
+    /** The page's own URL, which is loaded again; `location.href` when absent. */
+    pageURL?: () => string;
+}
+/**
+ * Whether an answer is the proxy's `sign_in_required`: HTTP 401, a JSON body,
+ * and the kit's envelope carrying that code. Any other 401 — the kit's own
+ * `unauthenticated`, another code, a body that is not JSON — is not.
+ */
+export declare function isSignInRequiredAnswer(status: number, contentType: string, body: string): boolean;
+/**
+ * Whether `res` is the proxy's `sign_in_required` answer. It reads a copy of
+ * the body, so `res` can still be read by the caller.
+ */
+export declare function isSignInRequired(res: Response): Promise<boolean>;
+/**
+ * Loads the page again, a top-level navigation to its own URL, which signs
+ * the person in to the plugin's origin and returns them where they were.
+ */
+export declare function reSignIn(options?: ReSignInOptions): void;

package/dist/signin.js

@@ -0,0 +1,74 @@
+/**
+ * Signing in again after tera forgets the page's session.
+ *
+ * tera's UI proxy holds a plugin origin's sessions in memory, so a daemon
+ * restart forgets every one. Only a page load can sign the person in again —
+ * silently, while their tera session lives — so the proxy answers anything
+ * else that arrives with no live session, a script's `fetch` among them, 401
+ * in the kit's envelope with code {@link SIGN_IN_REQUIRED}. The page recovers
+ * by loading itself again ({@link reSignIn}).
+ *
+ * That cannot loop: a page load never receives this answer, it starts the
+ * sign-in. A person whose tera session is gone too lands on tera's sign-in
+ * page, which is where they have to be.
+ *
+ * It is not the kit's `unauthenticated`, which says the request did reach the
+ * plugin, with no verified caller; loading the page again does not fix that.
+ *
+ * {@link TeraClient} and {@link FeedConnection} react on their own. A page
+ * reading one of the plugin's routes with its own `fetch` applies
+ * {@link isSignInRequired} to the response:
+ *
+ *     const res = await fetch("api/boards");
+ *     if (await isSignInRequired(res)) return reSignIn();
+ */
+/** The code of the proxy's answer to a request that needs the page loaded again to sign in. */
+export const SIGN_IN_REQUIRED = "sign_in_required";
+const JSON_TYPE = "application/json";
+/**
+ * Whether an answer is the proxy's `sign_in_required`: HTTP 401, a JSON body,
+ * and the kit's envelope carrying that code. Any other 401 — the kit's own
+ * `unauthenticated`, another code, a body that is not JSON — is not.
+ */
+export function isSignInRequiredAnswer(status, contentType, body) {
+    if (status !== 401)
+        return false;
+    if (contentType.toLowerCase().split(";")[0].trim() !== JSON_TYPE)
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return false;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return false;
+    const error = parsed.error;
+    return typeof error === "object" && error !== null && error.code === SIGN_IN_REQUIRED;
+}
+/**
+ * Whether `res` is the proxy's `sign_in_required` answer. It reads a copy of
+ * the body, so `res` can still be read by the caller.
+ */
+export async function isSignInRequired(res) {
+    if (res.status !== 401)
+        return false;
+    let text;
+    try {
+        text = await res.clone().text();
+    }
+    catch {
+        return false;
+    }
+    return isSignInRequiredAnswer(res.status, res.headers.get("content-type") ?? "", text);
+}
+/**
+ * Loads the page again, a top-level navigation to its own URL, which signs
+ * the person in to the plugin's origin and returns them where they were.
+ */
+export function reSignIn(options = {}) {
+    const navigate = options.navigate ?? ((url) => globalThis.location.assign(url));
+    const pageURL = options.pageURL ?? (() => globalThis.location.href);
+    navigate(pageURL());
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kottera/tera-web",
-  "version": "0.1.0-rc.4",
+  "version": "0.1.0-rc.6",
   "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": {