@segmentstream-cloud/app 0.14.0 → 0.16.0

package/README.md

@@ -412,8 +412,8 @@ One authorization model covers the ontology: every `segmentstream.ontology` call
 included, runs as the signed-in user through the ontology service, which checks their
 permissions. `segmentstream.ontology.<entity>.aggregate(request)` posts to
 `/api/ontology/<entity>/aggregate` and needs read permission on the entities it reaches.
-`segmentstream.warehouse` is the only call that uses the workspace app credential, and it
-reaches the whole workspace warehouse. `segmentstream.fetch(path)` still requires the legacy
+`segmentstream.warehouse` uses the workspace app credential and reaches the whole workspace
+warehouse. The job helpers below use it for explicitly opted-in jobs. `segmentstream.fetch(path)` still requires the legacy
 platform session. Aggregates through the service need the workspace's ontology deployed with
 `@segmentstream-cloud/ontology` 0.13.0 or later.
 
@@ -529,9 +529,7 @@ const { fields, rows } = await segmentstream.ontology.aggregate({
   dimensions: ["acmeSales.orderDate"],
   granularity: "month",
   granularityOf: "acmeSales.orderDate",
-  filters: [
-    { dimension: "acmeSales.orderDate", operator: "inPeriod", value: "this year to date" },
-  ],
+  filters: [{ dimension: "acmeSales.orderDate", operator: "inPeriod", value: "this year to date" }],
   orderBy: [{ measure: "planAttainment", direction: "desc" }],
 });
 // fields[1]: { name: "planAttainment", label: "Plan attainment", unit: "ratio", additive: false,
@@ -553,6 +551,42 @@ const { fields, rows } = await segmentstream.ontology.aggregate({
   0.23.0 or later, which declares and serves measures of the model; earlier versions refuse
   them. Requests that name none work as before, and their fields carry no `inputs`.
 
+## Start a pipeline job
+
+With app SDK 0.15.0 and pipeline SDK 0.1.0a65 or later, opt in a job and deploy it:
+
+```python
+s.job("land_watch", assets=[land_checks], allow_app_runs=True)
+```
+
+In server code, check the user's role or permissions before calling on their behalf:
+
+```ts
+const user = await segmentstream.requireUser();
+if (!user.roles.includes("operator")) {
+  throw new Error("An operator role is required.");
+}
+
+const run = await segmentstream.jobs.run("land_watch");
+// From a later authorized request, for example a Route Handler the page polls:
+const current = await segmentstream.jobs.getRun(run.id);
+const recent = await segmentstream.jobs.listRuns("land_watch");
+```
+
+The helpers use the workspace app credential, read on every call, or fall back to the
+legacy member session. Credential access defaults to denied unless the current deployed
+job sets `allow_app_runs=True`. It stays within the workspace and permits submission and
+status/history reads; run logs, activity and cancellation require platform membership.
+Removing the flag revokes app access to that job's runs.
+
+`run()` returns immediately with a run ID and status. It generates a UUID idempotency key
+unless passed `{ idempotencyKey }`; reuse an explicit key when retrying one button action.
+Separate calls with new keys can run concurrently. Partitioned jobs accept
+`{ partitionRange: { startDate, endDate } }`. All helpers accept an optional `signal`.
+Poll `getRun()` until status is `succeeded`, `failed` or `cancelled`, and tolerate future
+status values. Protect both submission and status routes with your app's authorization.
+See [app data access](../../docs/app-data.md#start-a-pipeline-job-from-the-app) for a Route Handler.
+
 ## How requests are handled
 
 - Page navigations without a session are redirected to `/sign-in?returnTo=<path>` and
@@ -568,7 +602,7 @@ const { fields, rows } = await segmentstream.ontology.aggregate({
 | -------------------------------------- | ------------------------------------------------------------------------------- |
 | `NEON_AUTH_BASE_URL`                   | The workspace's Neon Auth URL. Set: sign in with Neon Auth. Unset: 0.2 sign-in. |
 | `SEGMENTSTREAM_APP_AUTH_COOKIE_SECRET` | 32 or more characters; signs the session cache cookie. Required with Neon Auth. |
-| `SEGMENTSTREAM_APP_CREDENTIAL`         | The workspace app credential for warehouse queries.                             |
+| `SEGMENTSTREAM_APP_CREDENTIAL`         | The workspace app credential for warehouse queries and opted-in pipeline jobs.  |
 | `SEGMENTSTREAM_ONTOLOGY_URL`           | Optional: the ontology service when it does not run beside the app.             |
 | `SEGMENTSTREAM_URL`                    | SegmentStream origin. Defaults to `https://cloud.segmentstream.com`.            |
 

package/dist/app.d.ts

@@ -1,6 +1,7 @@
 import type { Environment, SegmentStreamAppConfig } from "./config.js";
 import type { AgentIdentities } from "./agent.js";
 import type { WarehouseClient } from "./data.js";
+import type { JobsClient } from "./jobs.js";
 import type { SegmentStreamRouteHandlers } from "./handlers.js";
 import type { AgentAuthorizations } from "./oauth.js";
 import type { AuthRouteHandlers, CreateNeonAuth, SignOutOptions } from "./neon.js";
@@ -46,6 +47,8 @@ export interface SegmentStreamApp<O = unknown> {
      * (`SEGMENTSTREAM_APP_CREDENTIAL`) when it is set, else the signed-in member's session.
      */
     readonly warehouse: WarehouseClient;
+    /** Start and read pipeline runs with the workspace credential. Server-only; gate app users. */
+    readonly jobs: JobsClient;
     /** The app's ontology service, `/api/ontology`, as the signed-in user. Server-only. */
     readonly ontology: OntologyClient<O>;
     /**

package/dist/app.js

@@ -57,6 +57,7 @@ export function createApp(config, dependencies = {}) {
             getAccessToken: legacy.getAccessToken,
             fetch: data.fetch,
             warehouse: data.warehouse,
+            jobs: data.jobs,
             ontology: createOntologyClient(ontologyTransport),
             oauth: createAgentAuthorizations(ontologyTransport),
             agent: createAgentIdentities(ontologyTransport),
@@ -87,6 +88,7 @@ export function createApp(config, dependencies = {}) {
         getAccessToken: async () => null,
         fetch: data.fetch,
         warehouse: data.warehouse,
+        jobs: data.jobs,
         ontology: createOntologyClient(neon.ontologyTransport),
         oauth: createAgentAuthorizations(neon.ontologyTransport),
         agent: createAgentIdentities(neon.ontologyTransport),
@@ -97,7 +99,7 @@ async function noSegmentStreamSession() {
     throw new SegmentStreamApiError({
         code: "app_credential_missing",
         status: 401,
-        detail: "Apps that sign in with Neon Auth have no SegmentStream session. Warehouse queries use the workspace app credential, SEGMENTSTREAM_APP_CREDENTIAL, which is not set; SegmentStream sets it on deploy. Other SegmentStream API calls are not available to these apps yet.",
+        detail: "Apps that sign in with Neon Auth have no SegmentStream session. Warehouse queries and opted-in job runs need SEGMENTSTREAM_APP_CREDENTIAL, which SegmentStream sets on deploy. Generic fetch requires a legacy SegmentStream session.",
     });
 }
 function notConfiguredHandlers() {

package/dist/data.d.ts

@@ -214,7 +214,7 @@ export interface DataClientDependencies {
     readonly getAccessToken: () => Promise<string | null>;
     /**
      * The workspace app credential, `SEGMENTSTREAM_APP_CREDENTIAL`, read on every call. The API
-     * accepts it for warehouse queries and their results; without it they use the session token.
+     * accepts it for warehouse queries and opted-in job runs; otherwise they use the session token.
      */
     readonly getAppCredential?: () => string | undefined;
     readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
@@ -224,4 +224,5 @@ export interface DataClientDependencies {
 export declare function createDataClient(dependencies: DataClientDependencies): {
     fetch: (path: string, init?: RequestInit) => Promise<Response>;
     warehouse: WarehouseClient;
+    jobs: import("./jobs.js").JobsClient;
 };

package/dist/data.js

@@ -1,5 +1,6 @@
 import { SegmentStreamApiError, readJson } from "./errors.js";
 import { encodeParameters } from "./parameters.js";
+import { createJobsClient } from "./jobs.js";
 export { SegmentStreamApiError } from "./errors.js";
 const REQUEST_TIMEOUT_MS = 45_000;
 const DEFAULT_MAX_ROWS = 10_000;
@@ -17,8 +18,8 @@ export function createDataClient(dependencies) {
     function apiFetch(path, init = {}) {
         return authorizedFetch(path, init, dependencies.getAccessToken);
     }
-    /** Warehouse queries prefer the app's own credential, which needs no SegmentStream session. */
-    async function warehouseToken() {
+    /** Workspace operations prefer the app credential, which needs no SegmentStream session. */
+    async function workspaceToken() {
         return dependencies.getAppCredential?.() ?? dependencies.getAccessToken();
     }
     async function authorizedFetch(path, init, getToken) {
@@ -122,7 +123,7 @@ export function createDataClient(dependencies) {
             parameters: encodeParameters(options.params),
             ...bytesLimit(options.maximumBytesBilled),
             pageSize: bounds.pageSize,
-        }, options.signal, warehouseToken);
+        }, options.signal, workspaceToken);
         return collect(page, bounds, options.signal);
     }
     async function result(queryId, options = {}) {
@@ -135,7 +136,7 @@ export function createDataClient(dependencies) {
         if (pageToken !== undefined) {
             search.set("pageToken", pageToken);
         }
-        return call("GET", `${workspace}/warehouse/queries/${encodeURIComponent(queryId)}?${search.toString()}`, undefined, signal, warehouseToken);
+        return call("GET", `${workspace}/warehouse/queries/${encodeURIComponent(queryId)}?${search.toString()}`, undefined, signal, workspaceToken);
     }
     const warehouse = {
         query,
@@ -146,7 +147,7 @@ export function createDataClient(dependencies) {
                 parameters: encodeParameters(options.params),
                 ...bytesLimit(options.maximumBytesBilled),
                 dryRun: true,
-            }, options.signal, warehouseToken);
+            }, options.signal, workspaceToken);
             return {
                 columns: page.columns,
                 bytesProcessed: page.bytesProcessed ?? null,
@@ -154,7 +155,11 @@ export function createDataClient(dependencies) {
             };
         },
     };
-    return { fetch: apiFetch, warehouse };
+    const jobs = createJobsClient({
+        workspace,
+        fetch: (path, init) => authorizedFetch(path, init, workspaceToken),
+    });
+    return { fetch: apiFetch, warehouse, jobs };
 }
 function bytesLimit(value) {
     if (value === undefined) {

package/dist/decision-pages.js

@@ -1,7 +1,7 @@
 import { AGENT_CONNECT_PAGE, CONSENT_PAGE } from "./pages.js";
 import { matchesPathPrefix } from "./proxy.js";
 /** Pages where a signed-in member lets an agent act for them. */
-const DECISION_PAGES = [CONSENT_PAGE, AGENT_CONNECT_PAGE];
+const DECISION_PAGES = [CONSENT_PAGE, AGENT_CONNECT_PAGE, "/sign-in", "/api/oauth/consent"];
 /**
  * The proxy, with the decision pages unframeable: no other site may show them in a frame and trick
  * a member into clicking Allow or Approve. Every app gets this from the SDK, whatever its Next.js
@@ -12,8 +12,14 @@ export function withUnframeablePages(proxy) {
         const response = await proxy(request);
         const pathname = request.nextUrl.pathname;
         if (DECISION_PAGES.some((page) => matchesPathPrefix(pathname, page))) {
+            response.headers.set("cache-control", "no-store");
+            response.headers.set("referrer-policy", "no-referrer");
             response.headers.set("x-frame-options", "DENY");
-            response.headers.set("content-security-policy", "frame-ancestors 'none'");
+            const policy = response.headers.get("content-security-policy");
+            response.headers.set("content-security-policy", policy === null
+                ? "frame-ancestors 'none'"
+                : policy.replace(/frame-ancestors[^;]*/g, "frame-ancestors 'none'") +
+                    (policy.includes("frame-ancestors") ? "" : "; frame-ancestors 'none'"));
         }
         return response;
     };

package/dist/index.d.ts

@@ -24,6 +24,7 @@ export { AGENT_CONNECT_HANDLER, AGENT_CONNECT_PAGE } from "./agent.js";
 export type { AgentIdentities, AgentIdentity, AgentPairing } from "./agent.js";
 export type { AgentAuthorizationRequest, AgentAuthorizations, AgentScope } from "./oauth.js";
 export type { ApiIssue } from "./errors.js";
+export type { JobReadOptions, JobRun, JobRunOptions, JobsClient } from "./jobs.js";
 export type { CurrentUser } from "./me.js";
 export type { AuthRouteHandler, AuthRouteHandlers, SignOutOptions } from "./neon.js";
 export type { ActionCall, ActionOptions, ActionResponse, Change, Edit, EditKind, EntityClient, FieldFilter, GeneratedActions, HistoryEntry, HistoryOptions, HistoryPage, JsonRecord, JsonValue, ManyFilter, ModelAggregateClient, OntologyClient, AggregateEntityClient, OntologyPage, OntologyQuery, OrderBy, RequestOptions, UntypedOntologyClient, ValidationIssue, Where, } from "./ontology.js";

package/dist/jobs.d.ts

@@ -0,0 +1,49 @@
+/** A pipeline run, returned immediately by `run()` and refreshed with `getRun()`. */
+export interface JobRun {
+    readonly id: string;
+    readonly deploymentId: string;
+    readonly jobName: string;
+    /** `queued`, `starting`, `running`, `succeeded`, `failed` or `cancelled`; future values are accepted. */
+    readonly status: string;
+    readonly trigger: string;
+    readonly partitionRange?: {
+        readonly startDate: string;
+        readonly endDate: string;
+    };
+    readonly failure?: {
+        readonly code: string;
+        readonly detail: string;
+        readonly retryable: boolean;
+        readonly reference: string;
+    };
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly startedAt?: string;
+    readonly completedAt?: string;
+}
+export interface JobRunOptions {
+    /** Reuse the same key when retrying one submission. Defaults to a new UUID for each call. */
+    readonly idempotencyKey?: string;
+    readonly partitionRange?: {
+        readonly startDate: string;
+        readonly endDate: string;
+    };
+    readonly signal?: AbortSignal;
+}
+export interface JobReadOptions {
+    readonly signal?: AbortSignal;
+}
+/**
+ * Server-only pipeline execution. The workspace credential can start and read only jobs deployed
+ * with `allow_app_runs=True`. Check the app user's permissions before calling on their behalf.
+ */
+export interface JobsClient {
+    /** Submit a run without waiting for completion. */
+    readonly run: (jobName: string, options?: JobRunOptions) => Promise<JobRun>;
+    readonly getRun: (runId: string, options?: JobReadOptions) => Promise<JobRun>;
+    readonly listRuns: (jobName: string, options?: JobReadOptions) => Promise<readonly JobRun[]>;
+}
+export declare function createJobsClient(dependencies: {
+    readonly workspace: string;
+    readonly fetch: (path: string, init: RequestInit) => Promise<Response>;
+}): JobsClient;

package/dist/jobs.js

@@ -0,0 +1,40 @@
+import { apiErrorFrom, readJson } from "./errors.js";
+export function createJobsClient(dependencies) {
+    async function request(path, init) {
+        const response = await dependencies.fetch(path, init);
+        const payload = await readJson(response);
+        if (!response.ok) {
+            throw apiErrorFrom(response.status, payload, "SegmentStream rejected the job request.");
+        }
+        return payload;
+    }
+    return {
+        async run(jobName, options = {}) {
+            const key = options.idempotencyKey?.trim() ?? crypto.randomUUID();
+            if (!/^[A-Za-z0-9._:-]{8,128}$/.test(key)) {
+                throw new TypeError("idempotencyKey must be 8–128 letters, numbers, dots, underscores, colons or hyphens.");
+            }
+            const { run } = await request(`${dependencies.workspace}/jobs/${segment(jobName, "jobName")}/runs`, {
+                method: "POST",
+                headers: { "content-type": "application/json", "idempotency-key": key },
+                body: JSON.stringify(options.partitionRange ? { partitionRange: options.partitionRange } : {}),
+                signal: options.signal,
+            });
+            return run;
+        },
+        async getRun(runId, options = {}) {
+            const { run } = await request(`${dependencies.workspace}/runs/${segment(runId, "runId")}?includeTrigger=true`, { method: "GET", signal: options.signal });
+            return run;
+        },
+        async listRuns(jobName, options = {}) {
+            const { runs } = await request(`${dependencies.workspace}/jobs/${segment(jobName, "jobName")}/runs?includeTrigger=true`, { method: "GET", signal: options.signal });
+            return runs;
+        },
+    };
+}
+function segment(value, name) {
+    if (!value || value === "." || value === "..") {
+        throw new TypeError(`${name} must be a non-empty identifier.`);
+    }
+    return encodeURIComponent(value);
+}

package/dist/logo.d.ts

@@ -0,0 +1 @@
+export declare const SEGMENTSTREAM_LOGO_URI: string;

package/dist/logo.js

@@ -0,0 +1,25 @@
+// Official asset: apps/website/public/segmentstream-logo-black.svg. Keep it in sync.
+const SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="283 330 755 162" fill="none">
+  <!-- S icon (black) -->
+  <path fill="#18181b" d="M342.57,485.52l46.86-61.07c4.2-5.48,3.17-13.33-2.31-17.54l-1.08-0.83c-6.34-4.86-15.42-3.67-20.29,2.67l-29.25,38.12c-9.07,11.82-6.84,28.75,4.98,37.82L342.57,485.52z"/>
+  <path fill="#18181b" d="M393.15,410.11c-0.16-15.51-12.79-28.04-28.34-28.04H349.9c-4.94,0-8.95,4.01-8.95,8.95v19.39h42.52l0.01,0.01c0.09,0,0.19-0.01,0.28-0.01c4.37,0,7.9,3.54,7.9,7.9c0,0.9-0.15,1.77-0.43,2.58c0,0,1.25-3.04,1.63-5.72c0.24-1.69,0.29-3.97,0.3-4.77v0c0-0.03,0-0.06,0-0.09C393.15,410.18,393.15,410.11,393.15,410.11z"/>
+  <path fill="#18181b" d="M339.43,335.27l-46.86,61.07c-4.2,5.48-3.17,13.33,2.31,17.54l1.08,0.83c6.34,4.86,15.42,3.67,20.29-2.67l29.25-38.12c9.07-11.82,6.84-28.75-4.98-37.82L339.43,335.27z"/>
+  <path fill="#18181b" d="M288.85,410.68c0.16,15.51,12.79,28.04,28.34,28.04h14.91c4.94,0,8.95-4.01,8.95-8.95v-19.39h-42.52l-0.01-0.01c-0.09,0-0.19,0.01-0.28,0.01c-4.37,0-7.9-3.54-7.9-7.9c0-0.9,0.15-1.77,0.43-2.58c0,0-1.25,3.04-1.63,5.72c-0.24,1.69-0.29,3.97-0.3,4.77v0c0,0.03,0,0.06,0,0.09C288.85,410.6,288.85,410.68,288.85,410.68z"/>
+  <!-- Wordmark: segmentstream (black) -->
+  <g fill="#18181b">
+    <path d="M452.61,400.96c-1.03-1.65-2.99-3.72-6.2-3.72c-1.45,0-2.48,0.52-3.1,1.14c-0.52,0.52-0.93,1.34-0.93,2.27c0,1.14,0.52,1.86,1.45,2.48c0.62,0.41,1.24,0.62,3.41,1.76l5.16,2.58c2.27,1.14,4.44,2.27,6.09,4.03c2.38,2.38,3.2,5.06,3.2,8.06c0,3.92-1.45,7.33-3.82,9.91c-3.41,3.72-7.64,4.85-12.19,4.85c-2.79,0-6.3-0.41-9.4-2.79c-2.48-1.86-4.54-4.85-5.58-7.95l8.26-3.92c0.52,1.45,1.45,3.3,2.38,4.13c0.62,0.62,2.07,1.65,4.44,1.65c1.55,0,3.2-0.52,4.13-1.45c0.83-0.83,1.45-2.17,1.45-3.41c0-1.24-0.41-2.27-1.34-3.3c-1.24-1.24-2.68-1.96-4.34-2.68l-3.72-1.76c-1.96-0.93-4.34-2.07-5.99-3.72c-2.27-2.17-3.1-4.54-3.1-7.33c0-3.51,1.34-6.92,3.61-9.29c1.96-2.07,5.27-4.13,10.64-4.13c3.1,0,5.58,0.62,8.05,2.27c1.45,0.93,3.41,2.58,4.96,5.37L452.61,400.96z"/>
+    <path d="M509.71,423.06c-1.86,3.3-4.54,6.2-7.33,7.95c-3.51,2.27-8.16,3.3-12.81,3.3c-5.78,0-10.53-1.45-14.66-5.58c-4.13-4.13-6.4-10.12-6.4-16.63c0-6.71,2.37-13.22,6.92-17.86c3.61-3.61,8.36-5.89,14.56-5.89c6.92,0,11.36,2.99,13.94,5.68c5.58,5.78,6.09,13.84,6.09,18.38v1.24h-31.19c0.21,3.1,1.55,6.61,3.72,8.78c2.38,2.38,5.27,2.79,7.74,2.79c2.79,0,4.85-0.62,6.92-2.17c1.76-1.34,3.1-3.1,4.03-4.75L509.71,423.06z M499.7,405.4c-0.41-2.38-1.55-4.44-3.1-5.89c-1.34-1.24-3.51-2.48-6.82-2.48c-3.51,0-5.78,1.45-7.12,2.79c-1.45,1.34-2.58,3.41-3.1,5.58H499.7z"/>
+    <path d="M552.37,389.5h10.12v39.96c0,10.22-1.14,17.55-7.13,22.62c-2.79,2.27-7.33,4.65-14.46,4.65c-5.06,0-10.12-1.24-14.25-5.37c-3.2-3.2-5.68-8.26-6.4-13.53h9.81c0.41,2.38,1.65,5.16,3.2,6.81c1.24,1.34,3.72,3,7.85,3c4.23,0,6.71-1.65,7.95-2.89c3.3-3.2,3.3-7.75,3.3-10.95v-5.68c-4.65,5.89-10.33,6.2-13.22,6.2c-5.58,0-10.22-1.55-14.35-5.89c-3.92-4.13-6.51-10.02-6.51-17.25c0-7.95,3-13.42,6.4-16.83c4.34-4.44,9.5-5.99,14.77-5.99c4.34,0,9.19,1.45,12.91,5.89V389.5z M533.05,400.34c-2.58,2.38-4.44,6.4-4.44,11.05c0,4.34,1.65,8.57,4.34,10.95c1.86,1.65,4.65,2.89,7.75,2.89c3.2,0,5.99-0.93,8.47-3.51c2.99-3.2,3.82-6.92,3.82-10.22c0-4.85-1.55-8.47-4.13-10.95c-2.48-2.48-5.27-3.1-8.16-3.1C537.91,397.45,535.33,398.17,533.05,400.34z"/>
+    <path d="M575.29,389.5h10.12v4.03c3.41-4.13,7.43-5.16,10.74-5.16c4.54,0,8.78,2.17,11.26,6.4c3.61-5.16,9.09-6.4,12.91-6.4c5.27,0,9.91,2.48,12.39,6.82c0.83,1.45,2.27,4.65,2.27,10.95v26.85h-10.12v-23.96c0-4.85-0.52-6.82-0.93-7.75c-0.62-1.65-2.17-3.82-5.78-3.82c-2.48,0-4.65,1.34-5.99,3.2c-1.76,2.48-1.96,6.2-1.96,9.91v22.41h-10.12v-23.96c0-4.85-0.52-6.82-0.93-7.75c-0.62-1.65-2.17-3.82-5.78-3.82c-2.48,0-4.65,1.34-5.99,3.2c-1.76,2.48-1.96,6.2-1.96,9.91v22.41h-10.12V389.5z"/>
+    <path d="M686.72,423.06c-1.86,3.3-4.54,6.2-7.33,7.95c-3.51,2.27-8.16,3.3-12.8,3.3c-5.78,0-10.53-1.45-14.66-5.58c-4.13-4.13-6.4-10.12-6.4-16.63c0-6.71,2.38-13.22,6.92-17.86c3.61-3.61,8.36-5.89,14.56-5.89c6.92,0,11.36,2.99,13.94,5.68c5.58,5.78,6.09,13.84,6.09,18.38v1.24h-31.19c0.21,3.1,1.55,6.61,3.72,8.78c2.38,2.38,5.27,2.79,7.75,2.79c2.79,0,4.85-0.62,6.92-2.17c1.76-1.34,3.1-3.1,4.03-4.75L686.72,423.06z M676.7,405.4c-0.41-2.38-1.55-4.44-3.1-5.89c-1.34-1.24-3.51-2.48-6.82-2.48c-3.51,0-5.78,1.45-7.13,2.79c-1.45,1.34-2.58,3.41-3.1,5.58H676.7z"/>
+    <path d="M697.46,389.5h10.12v4.03c4.34-4.85,9.29-5.16,11.77-5.16c8.05,0,11.46,4.03,12.81,5.89c1.65,2.38,2.68,5.37,2.68,12.08v26.64h-10.12v-24.16c0-11.05-4.13-11.36-7.95-11.36c-4.54,0-9.19,0.62-9.19,14.66v20.86h-10.12V389.5z"/>
+    <path d="M758.08,398.79v34.18h-10.12v-34.18h-4.23v-9.29h4.23v-15.9h10.12v15.9h7.75v9.29H758.08z"/>
+    <path d="M791.64,400.96c-1.03-1.65-2.99-3.72-6.2-3.72c-1.45,0-2.48,0.52-3.1,1.14c-0.52,0.52-0.93,1.34-0.93,2.27c0,1.14,0.52,1.86,1.45,2.48c0.62,0.41,1.24,0.62,3.41,1.76l5.16,2.58c2.27,1.14,4.44,2.27,6.09,4.03c2.38,2.38,3.2,5.06,3.2,8.06c0,3.92-1.45,7.33-3.82,9.91c-3.41,3.72-7.64,4.85-12.19,4.85c-2.79,0-6.3-0.41-9.4-2.79c-2.48-1.86-4.54-4.85-5.58-7.95l8.26-3.92c0.52,1.45,1.45,3.3,2.38,4.13c0.62,0.62,2.07,1.65,4.44,1.65c1.55,0,3.2-0.52,4.13-1.45c0.83-0.83,1.45-2.17,1.45-3.41c0-1.24-0.41-2.27-1.34-3.3c-1.24-1.24-2.69-1.96-4.34-2.68l-3.72-1.76c-1.96-0.93-4.34-2.07-5.99-3.72c-2.27-2.17-3.1-4.54-3.1-7.33c0-3.51,1.34-6.92,3.61-9.29c1.96-2.07,5.27-4.13,10.64-4.13c3.1,0,5.58,0.62,8.05,2.27c1.45,0.93,3.41,2.58,4.96,5.37L791.64,400.96z"/>
+    <path d="M820.25,398.79v34.18h-10.12v-34.18h-4.23v-9.29h4.23v-15.9h10.12v15.9h7.75v9.29H820.25z"/>
+    <path d="M834.81,389.5h10.12v3.92c1.14-1.34,2.79-2.79,4.23-3.61c1.96-1.14,3.92-1.45,6.2-1.45c2.48,0,5.16,0.41,7.95,2.07l-4.13,9.19c-2.27-1.45-4.13-1.55-5.16-1.55c-2.17,0-4.34,0.31-6.3,2.38c-2.79,2.99-2.79,7.13-2.79,10.02v22.51h-10.12V389.5z"/>
+    <path d="M904.83,423.06c-1.86,3.3-4.54,6.2-7.33,7.95c-3.51,2.27-8.16,3.3-12.8,3.3c-5.78,0-10.53-1.45-14.66-5.58c-4.13-4.13-6.4-10.12-6.4-16.63c0-6.71,2.38-13.22,6.92-17.86c3.61-3.61,8.36-5.89,14.56-5.89c6.92,0,11.36,2.99,13.94,5.68c5.58,5.78,6.09,13.84,6.09,18.38v1.24h-31.19c0.21,3.1,1.55,6.61,3.72,8.78c2.38,2.38,5.27,2.79,7.75,2.79c2.79,0,4.85-0.62,6.92-2.17c1.76-1.34,3.1-3.1,4.03-4.75L904.83,423.06z M894.81,405.4c-0.41-2.38-1.55-4.44-3.1-5.89c-1.34-1.24-3.51-2.48-6.82-2.48c-3.51,0-5.78,1.45-7.13,2.79c-1.45,1.34-2.58,3.41-3.1,5.58H894.81z"/>
+    <path d="M946.38,389.5h10.12v43.48h-10.12v-4.54c-4.44,5.16-9.91,5.89-13.01,5.89c-13.43,0-21.07-11.15-21.07-23.13c0-14.15,9.71-22.82,21.17-22.82c3.2,0,8.78,0.83,12.91,6.2V389.5z M922.63,411.39c0,7.54,4.75,13.84,12.08,13.84c6.4,0,12.29-4.65,12.29-13.74c0-9.5-5.89-14.04-12.29-14.04C927.38,397.45,922.63,403.64,922.63,411.39z"/>
+    <path d="M969.31,389.5h10.12v4.03c3.41-4.13,7.43-5.16,10.74-5.16c4.54,0,8.78,2.17,11.26,6.4c3.62-5.16,9.09-6.4,12.91-6.4c5.27,0,9.91,2.48,12.39,6.82c0.83,1.45,2.27,4.65,2.27,10.95v26.85h-10.12v-23.96c0-4.85-0.52-6.82-0.93-7.75c-0.62-1.65-2.17-3.82-5.78-3.82c-2.48,0-4.65,1.34-5.99,3.2c-1.76,2.48-1.96,6.2-1.96,9.91v22.41H994.1v-23.96c0-4.85-0.52-6.82-0.93-7.75c-0.62-1.65-2.17-3.82-5.78-3.82c-2.48,0-4.65,1.34-5.99,3.2c-1.76,2.48-1.96,6.2-1.96,9.91v22.41h-10.12V389.5z"/>
+  </g>
+</svg>`;
+export const SEGMENTSTREAM_LOGO_URI = `data:image/svg+xml,${encodeURIComponent(SVG)}`;

package/dist/oauth-completion.d.ts

@@ -0,0 +1,6 @@
+/** Keep a copyable PKCE-bound code visible while trying the client's loopback callback. */
+export declare function oauthCompletion(options: {
+    readonly redirect?: string;
+    readonly approved?: boolean;
+}): Response;
+export declare function loopbackRedirect(value: string): boolean;

package/dist/oauth-completion.js

@@ -0,0 +1,57 @@
+import { randomBytes } from "node:crypto";
+import { SEGMENTSTREAM_LOGO_URI } from "./logo.js";
+function escape(value) {
+    return value.replace(/[&<>"']/g, (character) => ({
+        "&": "&amp;",
+        "<": "&lt;",
+        ">": "&gt;",
+        '"': "&quot;",
+        "'": "&#39;",
+    })[character]);
+}
+/** Keep a copyable PKCE-bound code visible while trying the client's loopback callback. */
+export function oauthCompletion(options) {
+    const nonce = randomBytes(18).toString("base64");
+    const redirect = options.redirect;
+    const code = redirect === undefined ? null : new URL(redirect).searchParams.get("code");
+    const title = options.approved === false ? "Request denied" : "Authorization complete";
+    const manual = code === null
+        ? "<p>You can return to your terminal.</p>"
+        : `
+    <p>Return to your terminal. If it is still waiting, copy and paste this code:</p>
+    <input id="code" aria-label="Authorization code" readonly value="${escape(code)}">
+    <button id="copy" type="button">Copy code</button><p id="status" role="status"></p>
+    <p><a href="${escape(redirect)}">Continue to the client</a></p>`;
+    const script = code === null
+        ? ""
+        : `
+    document.getElementById('copy').addEventListener('click', async () => {
+      const input = document.getElementById('code');
+      try { await navigator.clipboard.writeText(input.value);
+        document.getElementById('status').textContent = 'Copied';
+      } catch { input.select(); document.getElementById('status').textContent = 'Select and copy the code'; }
+    });
+    // A frame attempts loopback without losing the fallback page on connection failure.
+    const frame = document.createElement('iframe'); frame.hidden = true;
+    frame.src = ${JSON.stringify(redirect).replace(/</g, "\\u003c")}; document.body.appendChild(frame);`;
+    return new Response(`<!doctype html><html lang="en"><meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1"><title>${title}</title>
+    <style nonce="${nonce}">body{font:16px system-ui;background:#fafafa;color:#18181b;margin:10vh auto;
+    max-width:480px;padding:24px}input,button{font:inherit;padding:12px;margin:8px 0}input{width:95%}</style>
+    <img src="${escape(SEGMENTSTREAM_LOGO_URI)}" alt="SegmentStream" width="210" height="45">
+    <h1>${title}</h1>${manual}<script nonce="${nonce}">${script}</script></html>`, {
+        headers: {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": "no-store",
+            "referrer-policy": "no-referrer",
+            "x-frame-options": "DENY",
+            "content-security-policy": `default-src 'none'; img-src data:; style-src 'nonce-${nonce}'; ` +
+                `script-src 'nonce-${nonce}'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'; ` +
+                `frame-src ${redirect === undefined ? "'none'" : new URL(redirect).origin}`,
+        },
+    });
+}
+export function loopbackRedirect(value) {
+    const url = new URL(value);
+    return url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname);
+}

package/dist/oauth.d.ts

@@ -30,6 +30,7 @@ export interface AgentAuthorizations {
      * It takes `request`, `decision` (`approve` or `deny`) and, to allow reading only, `scope`
      * (`ontology:read`), and sends the browser back to the agent.
      */
+    readonly deviceRequest: (userCode: string) => Promise<AgentAuthorizationRequest | null>;
     readonly consentHandler: () => {
         readonly POST: (request: Request) => Promise<Response>;
     };

package/dist/oauth.js

@@ -1,6 +1,7 @@
 import { NextResponse } from "next/server";
 import { isSameOrigin } from "./decision-pages.js";
 import { apiErrorFrom, readJson } from "./errors.js";
+import { loopbackRedirect, oauthCompletion } from "./oauth-completion.js";
 import { CONSENT_PAGE } from "./pages.js";
 export { CONSENT_PAGE };
 function parseRequest(payload) {
@@ -55,6 +56,21 @@ export function createAgentAuthorizations(transport) {
             }
             return parseRequest(payload);
         },
+        async deviceRequest(userCode) {
+            const response = await transport.fetch("/oauth/device/lookup", {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ user_code: userCode }),
+            });
+            const payload = await readJson(response);
+            if (response.status === 404) {
+                return null;
+            }
+            if (!response.ok) {
+                throw apiErrorFrom(response.status, payload, "The verification attempt was refused.");
+            }
+            return parseRequest(payload);
+        },
         consentHandler: () => ({
             async POST(request) {
                 if (!isSameOrigin(request)) {
@@ -62,11 +78,21 @@ export function createAgentAuthorizations(transport) {
                 }
                 const form = await request.formData();
                 const id = String(form.get("request") ?? "");
+                if (form.get("decision") === "lookup") {
+                    const url = new URL(CONSENT_PAGE, request.url);
+                    url.searchParams.set("device", "1");
+                    url.searchParams.set("user_code", String(form.get("user_code") ?? "").slice(0, 32));
+                    return NextResponse.redirect(url, 303);
+                }
+                const device = id.startsWith("device:");
                 const decision = form.get("decision") === "approve" ? "approve" : "deny";
-                const response = await transport.fetch(requestPath(id, decision), {
+                const response = await transport.fetch(device ? `/oauth/device/${decision}` : requestPath(id, decision), {
                     method: "POST",
                     headers: { "content-type": "application/json", accept: "application/json" },
-                    body: JSON.stringify(form.get("scope") === "ontology:read" ? { scope: "ontology:read" } : {}),
+                    body: JSON.stringify({
+                        ...(device ? { user_code: id.slice(7) } : {}),
+                        ...(form.get("scope") === "ontology:read" ? { scope: "ontology:read" } : {}),
+                    }),
                 });
                 const payload = await readJson(response);
                 if (response.status === 404) {
@@ -75,10 +101,16 @@ export function createAgentAuthorizations(transport) {
                 if (!response.ok) {
                     throw apiErrorFrom(response.status, payload, "The ontology service refused the decision.");
                 }
+                if (device) {
+                    return oauthCompletion({ approved: decision === "approve" });
+                }
                 const redirect = payload?.redirect;
                 if (typeof redirect !== "string" || !URL.canParse(redirect)) {
                     throw apiErrorFrom(502, payload, "The ontology service answered without a redirect.");
                 }
+                if (decision === "approve" && loopbackRedirect(redirect)) {
+                    return oauthCompletion({ redirect });
+                }
                 // 303: the agent's redirect URI receives a GET, whatever method brought the browser here.
                 return NextResponse.redirect(redirect, 303);
             },

package/dist/ui/index.d.ts

@@ -13,3 +13,4 @@ export { isAllowed } from "../permissions.js";
 export type { CurrentUser } from "../me.js";
 export type { AgentPairing } from "../agent.js";
 export { SegmentStreamApiError, NOT_INVITED, SIGN_IN_LINK_INVALID } from "../errors.js";
+export { SegmentStreamLogo } from "./segmentstream-logo.js";

package/dist/ui/index.js

@@ -9,3 +9,4 @@ export { SignIn } from "./sign-in.js";
 export { SIGN_IN_ERROR_MESSAGES, signInErrorCode, signInErrorMessage, useSignIn, } from "./use-sign-in.js";
 export { isAllowed } from "../permissions.js";
 export { SegmentStreamApiError, NOT_INVITED, SIGN_IN_LINK_INVALID } from "../errors.js";
+export { SegmentStreamLogo } from "./segmentstream-logo.js";

package/dist/ui/segmentstream-logo.d.ts

@@ -0,0 +1,2 @@
+/** The official SegmentStream wordmark, also used on segmentstream.com. */
+export declare function SegmentStreamLogo(): import("react").JSX.Element;

package/dist/ui/segmentstream-logo.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import Image from "next/image";
+import { SEGMENTSTREAM_LOGO_URI } from "../logo.js";
+/** The official SegmentStream wordmark, also used on segmentstream.com. */
+export function SegmentStreamLogo() {
+    return (_jsx(Image, { unoptimized: true, src: SEGMENTSTREAM_LOGO_URI, alt: "SegmentStream", width: 210, height: 45 }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/app",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Sign-in, users, permissions, the ontology client and warehouse data access for SegmentStream workspace apps built with Next.js.",
   "license": "Apache-2.0",
   "author": "SegmentStream",