@reticlehq/server 3.7.0 → 3.8.1

package/dist/portal/production/production-activation.js

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+import { bridgeWsUrl, HelloScope, LOOPBACK_HOST, PRODUCTION_ACTIVATE_PARAM, PRODUCTION_TICKET_PATH, ProductionTicketResponseSchema, } from '@reticlehq/core';
+/**
+ * Turn `reticle_lease { production }` into a page that will connect on a live site, in one step.
+ *
+ * 1. Mint a single-use session nonce for the site's origin, bound to a production drive.
+ * 2. Ask the service for an activation ticket with the linked API key:
+ *    `POST /v1/production-mode/tickets { workspaceId, nonce, bridgePort, scope, origin, bridge }`.
+ * 3. Hand back `<url>?reticle_activate=<ticket>` for the lease to open.
+ *
+ * The service decides who may activate (an owner or admin of a workspace with production mode on)
+ * and signs the ticket. No static secret leaves the machine: the page only ever sees the nonce.
+ */
+/** Said when the service has no ticket route: an older or self-hosted service. */
+export const PRODUCTION_MODE_NOT_OFFERED = `the server does not offer production mode (POST ${PRODUCTION_TICKET_PATH} answered 404). ` +
+    'Production mode needs a Reticle service that issues activation tickets.';
+/** Said when this project has no linked cloud credentials to ask with. */
+export const PRODUCTION_MODE_NOT_LINKED = 'production mode needs a linked Reticle cloud account: run `reticle connect`, or set RETICLE_API_KEY';
+/** Said when the daemon cannot mint a nonce here (no bridge in this process). */
+const PRODUCTION_MODE_NO_BRIDGE = 'production mode needs the daemon that owns the bridge: start `reticle mcp` or the daemon, then lease again';
+const TICKET_TIMEOUT_MS = 10_000;
+/** The `production` argument of `reticle_lease { action: "acquire" }`. */
+export const ProductionLeaseArgSchema = z.object({
+    workspaceId: z.string().min(1).max(128).describe('The workspace the service activates for.'),
+    scope: z
+        .nativeEnum(HelloScope)
+        .describe('observe: read only. act: also click and type, under the production policy.'),
+    intent: z
+        .string()
+        .max(2000)
+        .optional()
+        .describe('What this drive is meant to do, in words. It is the only thing that lifts a refused action: "invite a teammate" allows sending an invite.'),
+});
+export async function activateProduction(input) {
+    const parsed = ProductionLeaseArgSchema.safeParse(input.production);
+    if (!parsed.success) {
+        throw new Error('reticle_lease{action:"acquire"} production needs { workspaceId, scope: "observe" | "act" }');
+    }
+    const ask = parsed.data;
+    if (input.nonces === undefined || input.bridgePort === undefined) {
+        throw new Error(PRODUCTION_MODE_NO_BRIDGE);
+    }
+    const cloud = await input.cloud();
+    if (null === cloud)
+        throw new Error(PRODUCTION_MODE_NOT_LINKED);
+    const origin = new URL(input.url).origin;
+    const minted = input.nonces.mint({
+        origin,
+        production: {
+            scope: ask.scope,
+            origin,
+            ...(ask.intent === undefined ? {} : { intent: ask.intent }),
+        },
+    });
+    const drive = minted.production;
+    if (drive === undefined)
+        throw new Error(PRODUCTION_MODE_NO_BRIDGE);
+    const ticket = await requestTicket(cloud, {
+        workspaceId: ask.workspaceId,
+        nonce: minted.nonce,
+        bridgePort: input.bridgePort,
+        scope: ask.scope,
+        // Told, never guessed: the ticket is bound to this origin and names this bridge. The bridge
+        // listens on loopback, which the loader accepts over ws://.
+        origin,
+        bridge: bridgeWsUrl(input.bridgePort, LOOPBACK_HOST),
+    }, input.fetch);
+    if (ticket.policy !== undefined)
+        drive.setPolicy(ticket.policy);
+    const target = new URL(input.url);
+    target.searchParams.set(PRODUCTION_ACTIVATE_PARAM, ticket.ticket);
+    return { url: target.toString(), drive, scope: ask.scope, expiresAt: minted.expiresAt };
+}
+async function requestTicket(cloud, request, doFetch = (url, init) => fetch(url, init)) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, TICKET_TIMEOUT_MS);
+    try {
+        const res = await doFetch(`${cloud.url.replace(/\/+$/, '')}${PRODUCTION_TICKET_PATH}`, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${cloud.apiKey}`, 'content-type': 'application/json' },
+            body: JSON.stringify(request),
+            signal: controller.signal,
+        });
+        if (404 === res.status)
+            throw new Error(PRODUCTION_MODE_NOT_OFFERED);
+        const body = await res.json().catch(() => undefined);
+        if (!res.ok) {
+            const reason = z.object({ error: z.string() }).safeParse(body);
+            throw new Error(`the server refused a production-mode ticket (HTTP ${String(res.status)})` +
+                (reason.success ? `: ${reason.data.error}` : ''));
+        }
+        const parsed = ProductionTicketResponseSchema.safeParse(body);
+        if (!parsed.success) {
+            throw new Error('the server answered the ticket request with something that is not a ticket');
+        }
+        return parsed.data;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * The lease as the readiness wait sees it, minus the zero-install injector. An injected SDK would
+ * connect with the machine's pairing token as a development session, outside the policy; a
+ * production page connects only through its own activated loader.
+ */
+export function leaseWithoutInjection(lease) {
+    return lease.isLoading === undefined ? {} : { isLoading: lease.isLoading };
+}
+/** `reticle_lease`'s `production` argument, described for the agent. */
+export const PRODUCTION_LEASE_ARG = ProductionLeaseArgSchema.optional().describe('Drive a live site in production mode: mints a single-use session nonce, asks the linked Reticle service for an activation ticket, and opens the site with it. Every act then passes the production policy (docs/production-mode.md).');
+/** What a production lease reports back. */
+export const PRODUCTION_LEASE_OUTPUT = z
+    .object({ scope: z.string(), expiresAt: z.number() })
+    .optional()
+    .describe('Present on a production lease: its scope and when its nonce expires (epoch ms).');
+/** Activate when the lease asked for production, else nothing. */
+export function activationFor(ports, asked, url, root) {
+    if (asked === undefined)
+        return Promise.resolve(undefined);
+    return activateProduction({
+        production: asked,
+        url,
+        nonces: ports.nonces,
+        bridgePort: ports.bridgePort,
+        cloud: () => ports.linkedCloud?.(root) ?? Promise.resolve(null),
+    });
+}
+/**
+ * Guard a production lease's requests with its drive, and hand the readiness wait a lease it
+ * cannot inject into. A development lease passes through untouched.
+ */
+export async function guardedForProduction(pool, lease, activated) {
+    if (activated === undefined)
+        return lease;
+    const { drive } = activated;
+    await pool.guardLease(lease.sessionId, (method, url) => drive.refuseRequest(method, url));
+    return leaseWithoutInjection(lease);
+}
+/** The `production` field of the lease result. */
+export function summary(activated) {
+    return activated === undefined
+        ? {}
+        : { production: { scope: activated.scope, expiresAt: activated.expiresAt } };
+}
+/**
+ * Why an activated page never connected. The service redeems a ticket only for a browser signed in
+ * as the person who asked for it, and a leased browser starts signed out. The generic diagnosis
+ * blamed the page's CSP and said to allow the bridge for development only, which is wrong here.
+ */
+export function notActivatedHint(url) {
+    return (`${url} did not start production mode: no page connected with the session nonce. The ` +
+        'service redeems the activation ticket only for a browser signed in as you, in the workspace ' +
+        'the lease names, and a leased browser starts signed out. Release this lease, then acquire ' +
+        'again with your session cookies for this site in seedStorage { cookies }. When the browser is ' +
+        'signed in, the site did not load the SDK on the activated page (docs/production-mode.md).');
+}
+/** Playwright's name for Chrome's Local Network Access grant (local + loopback network). */
+const LOCAL_NETWORK_ACCESS = 'local-network-access';
+/**
+ * The permissions a lease is opened with. A production page on a public origin dials the bridge on
+ * loopback, which Chromium blocks unless a person grants Local Network Access, and a leased browser
+ * has no person. Granted on the lease's own origin only. Not a launch flag: a second
+ * `--disable-features` replaces the list Playwright launches with instead of adding to it.
+ */
+export function leasePermissions(asked, production) {
+    if (production === undefined)
+        return asked;
+    const granted = asked ?? [];
+    return granted.includes(LOCAL_NETWORK_ACCESS) ? granted : [...granted, LOCAL_NETWORK_ACCESS];
+}

package/dist/portal/production/production-drive.d.ts

@@ -0,0 +1,52 @@
+import { HelloScope, type CommandResult, type LiftableProductionRule, type ProductionPolicyEntry, type ReticleEvent } from '@reticlehq/core';
+/**
+ * The refused actions an intent asks for in so many words. "Invite a teammate" asks for one;
+ * "she does not invite anybody" asks for none.
+ */
+export declare function rulesAsked(intent: string): LiftableProductionRule[];
+/** The refused action a control's own words name, if any. */
+export declare function controlRule(words: string): LiftableProductionRule | undefined;
+/** The policy entry a request matches, if any. */
+export declare function requestRule(policy: readonly ProductionPolicyEntry[], method: string, url: string, base?: string): LiftableProductionRule | undefined;
+/** What a production nonce grants. Supplied by the local caller that mints it. */
+export interface ProductionGrant {
+    scope: HelloScope;
+    /** The drive's declared intent, in words. It is what lifts a refused rule. */
+    intent?: string;
+    /** The service's refused requests. Absent: the default list. */
+    policy?: readonly ProductionPolicyEntry[];
+    /** The origin the drive was activated on. */
+    origin?: string;
+}
+export declare class ProductionDrive {
+    #private;
+    constructor(grant: ProductionGrant & {
+        expiresAt: number;
+    }, clock: () => number);
+    get scope(): HelloScope;
+    /** The service's refused requests, from the ticket. Set before the page opens. */
+    setPolicy(policy: readonly ProductionPolicyEntry[]): void;
+    /** A page may narrow its drive to observing. Nothing widens it again. */
+    narrowToObserve(): void;
+    /** Learn ids from what the drive created: a 2xx POST/PUT whose JSON body names an `id`. */
+    noteEvent(event: ReticleEvent): void;
+    /** The refusal for a request the page is about to send, or undefined to let it go. */
+    refuseRequest(method: string, url: string): string | undefined;
+    /** A refusal made outside a command, once. */
+    takePending(): string | undefined;
+    /**
+     * The refusal for a command, or undefined to send it. `inspect` reads a ref's control from the
+     * page: what the control says about itself is evidence; what it does is decided here.
+     */
+    refuseCommand(name: string, args: Record<string, unknown>, inspect: (ref: string) => Promise<unknown>): Promise<string | undefined>;
+    /**
+     * Send a command through the policy. A refusal comes back as a failed result naming the rule,
+     * never as a silent no-op; a request the act sent and the guard refused fails the act that sent it.
+     */
+    gate(name: string, args: Record<string, unknown>, send: (name: string, args: Record<string, unknown>) => Promise<CommandResult>): Promise<CommandResult>;
+}
+/**
+ * Judge a native (CDP) gesture, which reaches the page without `Session.command`. Throws the
+ * refusal so the gesture is never performed.
+ */
+export declare function assertNativeAllowed(drive: ProductionDrive | undefined, action: string, inspected: unknown): Promise<void>;

package/dist/portal/production/production-drive.js

@@ -0,0 +1,301 @@
+import { ActionType, DEFAULT_PRODUCTION_POLICY, EventType, HelloScope, MessageKind, ProductionRule, ReticleCommand, asRecord, asString, productionRefusal, } from '@reticlehq/core';
+/**
+ * One production drive: what it was granted, what it created, and the rule that refuses an act.
+ *
+ * Enforced where the daemon dispatches a command (`Session.command`) and, on a leased browser, where
+ * the page's requests leave it. The page is never asked. Two things are recognised:
+ *
+ * - the control an act would press: its name, text, value, test id, link and form target;
+ * - the request it would send: method and path against the policy list.
+ *
+ * An action passes when the drive's declared intent names it, or when it touches only something
+ * this drive created (an id it saw come back from a 2xx create).
+ */
+/** Commands that read or move around. Everything else a page is told to do is an act. */
+const READ_COMMANDS = new Set([
+    ReticleCommand.SNAPSHOT,
+    ReticleCommand.QUERY,
+    ReticleCommand.MATCH,
+    ReticleCommand.INSPECT,
+    ReticleCommand.ANIMATIONS,
+    ReticleCommand.NARRATE,
+    ReticleCommand.CAPABILITIES,
+    ReticleCommand.STATE_READ,
+    ReticleCommand.STORAGE_READ,
+    ReticleCommand.SCROLL,
+    ReticleCommand.SESSION_CONFIG,
+    ReticleCommand.PRESENTER,
+    ReticleCommand.IMPACT,
+    ReticleCommand.CAPTURE,
+    ReticleCommand.RENDER,
+    ReticleCommand.NAVIGATE,
+    ReticleCommand.REFRESH,
+    ReticleCommand.FLOWS,
+    ReticleCommand.FLOW_PROGRESS,
+    ReticleCommand.PLAN,
+    ReticleCommand.MARKERS,
+]);
+/** Acts that only move the pointer or the view. They press nothing. */
+const LOOKING_ACTIONS = new Set([
+    ActionType.HOVER,
+    ActionType.FOCUS,
+    ActionType.BLUR,
+    ActionType.SCROLL,
+    ActionType.SCROLL_INTO_VIEW,
+]);
+/** Each refused action as words on a control, and as words in an intent. */
+const RULE_WORDS = [
+    [
+        ProductionRule.CANCEL_SUBSCRIPTION,
+        /\bcancel\b.{0,40}\b(?:subscription|plan|trial|membership)\b|\bdowngrade\b|\/subscriptions?\b.*\bcancel/i,
+    ],
+    [
+        ProductionRule.DELETE_WORKSPACE,
+        /\b(?:delete|remove|destroy|erase)\b.{0,40}\b(?:workspace|project|organi[sz]ation|org|account)s?\b/i,
+    ],
+    [
+        ProductionRule.REVOKE_KEY,
+        /\b(?:revoke|rotate|regenerate|roll)\b.{0,40}\b(?:key|token|secret)s?\b|\brevoke\b/i,
+    ],
+    [
+        ProductionRule.SEND_INVITE,
+        /\binvit(?:e|es|ed|ing|ation|ations)\b|\/invit|\bsend (?:an? )?(?:email|invite|invitation)s?\b|\bresend\b|\bemail (?:it|them|the)\b/i,
+    ],
+    [
+        ProductionRule.CHANGE_ROLE,
+        /\bchange (?:the |their |a |his |her )?(?:member'?s? )?role\b|\bmake (?:an? |them )?(?:admin|owner)\b|\bpromote\b|\bdemote\b|\bset role\b|\btransfer ownership\b/i,
+    ],
+    [
+        ProductionRule.PAYMENT,
+        /\b(?:pay|pays|paying|payment|purchase|buy|checkout|check out|subscribe|upgrade|place order|confirm order|add (?:a )?card)\b|\/(?:billing|checkout)\b/i,
+    ],
+];
+/** A word that turns the action after it into one the intent forbids: "does not invite". */
+const NEGATION = /\b(?:not|no|never|without|nor|avoid|don't|doesn't|won't)\b/i;
+const NEGATION_REACH = 4;
+/**
+ * The refused actions an intent asks for in so many words. "Invite a teammate" asks for one;
+ * "she does not invite anybody" asks for none.
+ */
+// ponytail: the same negation rule as `outwardActionsAsked` in core; one helper once both settle.
+export function rulesAsked(intent) {
+    const asked = [];
+    for (const [rule, pattern] of RULE_WORDS) {
+        for (const match of intent.matchAll(new RegExp(pattern.source, 'gi'))) {
+            const before = intent.slice(0, match.index).split(/\s+/).slice(-NEGATION_REACH).join(' ');
+            if (!NEGATION.test(before)) {
+                asked.push(rule);
+                break;
+            }
+        }
+    }
+    return asked;
+}
+/** The refused action a control's own words name, if any. */
+export function controlRule(words) {
+    const text = words.replace(/[_-]+/g, ' ');
+    return RULE_WORDS.find(([, pattern]) => pattern.test(text) || pattern.test(words))?.[0];
+}
+/** The policy entry a request matches, if any. */
+export function requestRule(policy, method, url, base) {
+    let pathname;
+    try {
+        pathname = new URL(url, base ?? 'http://localhost').pathname;
+    }
+    catch {
+        return undefined;
+    }
+    const verb = method.toUpperCase();
+    return policy.find((entry) => entry.methods.some((m) => m.toUpperCase() === verb) &&
+        new RegExp(entry.path, 'i').test(pathname))?.rule;
+}
+/** The text a control shows about itself, from an INSPECT reply or an act's own target. */
+function controlWords(descriptor) {
+    const d = asRecord(descriptor);
+    return ['name', 'text', 'label', 'value', 'testid', 'href', 'formAction']
+        .map((key) => asString(d[key]) ?? '')
+        .join(' ');
+}
+/** The shortest created id that counts. Shorter strings match too much by accident. */
+const MIN_CREATED_ID_LENGTH = 4;
+export class ProductionDrive {
+    #scope;
+    #intentAllows;
+    #policy;
+    #origin;
+    #expiresAt;
+    #clock;
+    /** Ids this drive saw come back from its own creates. Deleting those is allowed. */
+    #created = new Set();
+    /** Refusals made outside a command (a blocked request), told to the next act. */
+    #pending;
+    constructor(grant, clock) {
+        this.#scope = grant.scope;
+        this.#intentAllows = new Set(rulesAsked(grant.intent ?? ''));
+        this.#policy = grant.policy ?? DEFAULT_PRODUCTION_POLICY;
+        this.#origin = grant.origin;
+        this.#expiresAt = grant.expiresAt;
+        this.#clock = clock;
+    }
+    get scope() {
+        return this.#scope;
+    }
+    /** The service's refused requests, from the ticket. Set before the page opens. */
+    setPolicy(policy) {
+        this.#policy = policy;
+    }
+    /** A page may narrow its drive to observing. Nothing widens it again. */
+    narrowToObserve() {
+        this.#scope = HelloScope.OBSERVE;
+    }
+    /** Learn ids from what the drive created: a 2xx POST/PUT whose JSON body names an `id`. */
+    noteEvent(event) {
+        if (event.type !== EventType.NET_REQUEST)
+            return;
+        const data = event.data;
+        const method = (asString(data['method']) ?? '').toUpperCase();
+        const status = data['status'];
+        if ('number' !== typeof status || status < 200 || status > 299)
+            return;
+        // A refused request that SUCCEEDED got past every guard (no leased browser to stop it). The
+        // drive cannot take it back; it stops acting and says why on the next act.
+        const url = asString(data['url']) ?? '';
+        const rule = requestRule(this.#policy, method, url, this.#origin);
+        if (rule !== undefined && !this.#lifted(rule, url))
+            this.#pending ??= productionRefusal(rule);
+        if (method !== 'POST' && method !== 'PUT')
+            return;
+        const body = asString(data['responseBody']);
+        if (body === undefined)
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            return;
+        }
+        const top = asRecord(parsed);
+        const candidates = [top['id'], ...Object.values(top).map((v) => asRecord(v)['id'])];
+        for (const id of candidates) {
+            const text = 'number' === typeof id ? String(id) : asString(id);
+            if (text !== undefined && MIN_CREATED_ID_LENGTH <= text.length)
+                this.#created.add(text);
+        }
+    }
+    #createdHere(text) {
+        for (const id of this.#created)
+            if (text.includes(id))
+                return true;
+        return false;
+    }
+    #lifted(rule, touched) {
+        return this.#intentAllows.has(rule) || this.#createdHere(touched);
+    }
+    /** The refusal for a request the page is about to send, or undefined to let it go. */
+    refuseRequest(method, url) {
+        const rule = requestRule(this.#policy, method, url, this.#origin);
+        if (rule === undefined || this.#lifted(rule, url))
+            return undefined;
+        const refusal = productionRefusal(rule);
+        this.#pending = refusal;
+        return refusal;
+    }
+    /** A refusal made outside a command, once. */
+    takePending() {
+        const pending = this.#pending;
+        this.#pending = undefined;
+        return pending;
+    }
+    /**
+     * The refusal for a command, or undefined to send it. `inspect` reads a ref's control from the
+     * page: what the control says about itself is evidence; what it does is decided here.
+     */
+    async refuseCommand(name, args, inspect) {
+        if (this.#expiresAt <= this.#clock())
+            return productionRefusal(ProductionRule.EXPIRED);
+        if (name === ReticleCommand.NAVIGATE)
+            return this.#refuseNavigation(asString(args['url']));
+        if (READ_COMMANDS.has(name))
+            return undefined;
+        const pending = this.takePending();
+        if (pending !== undefined)
+            return pending;
+        if (this.#scope === HelloScope.OBSERVE)
+            return productionRefusal(ProductionRule.OBSERVE_ONLY);
+        const steps = name === ReticleCommand.ACT_SEQUENCE
+            ? (Array.isArray(args['steps']) ? args['steps'] : []).map(asRecord)
+            : name === ReticleCommand.ACT
+                ? [args]
+                : [];
+        for (const step of steps) {
+            const refusal = await this.#refuseStep(step, inspect);
+            if (refusal !== undefined)
+                return refusal;
+        }
+        return undefined;
+    }
+    /**
+     * Send a command through the policy. A refusal comes back as a failed result naming the rule,
+     * never as a silent no-op; a request the act sent and the guard refused fails the act that sent it.
+     */
+    async gate(name, args, send) {
+        const inspect = async (ref) => (await send(ReticleCommand.INSPECT, { ref })).result;
+        const refusal = await this.refuseCommand(name, args, inspect);
+        if (refusal !== undefined)
+            return refusedCommand(refusal);
+        const result = await send(name, args);
+        if (READ_COMMANDS.has(name))
+            return result;
+        const late = this.takePending();
+        return late === undefined ? result : refusedCommand(late);
+    }
+    #refuseNavigation(url) {
+        if (url === undefined || this.#origin === undefined)
+            return undefined;
+        try {
+            if (new URL(url, this.#origin).origin === this.#origin)
+                return undefined;
+        }
+        catch {
+            return undefined;
+        }
+        return productionRefusal(ProductionRule.OFF_ORIGIN);
+    }
+    async #refuseStep(step, inspect) {
+        const action = asString(step['action']) ?? ActionType.CLICK;
+        if (LOOKING_ACTIONS.has(action))
+            return undefined;
+        const ref = asString(step['ref']);
+        const control = ref === undefined ? asRecord(step['target']) : await inspect(ref);
+        const words = controlWords(control);
+        // A role picker says "Admin" in its value and "Role" in its name: selecting one changes a role.
+        const picksRole = action === ActionType.SELECT && /\brole\b/i.test(words);
+        const formAction = asString(asRecord(control)['formAction']);
+        const rule = (picksRole ? ProductionRule.CHANGE_ROLE : controlRule(words)) ??
+            (formAction === undefined
+                ? undefined
+                : requestRule(this.#policy, 'POST', formAction, this.#origin));
+        if (rule === undefined || this.#lifted(rule, words))
+            return undefined;
+        return productionRefusal(rule);
+    }
+}
+/** A refusal in the shape every command result has: `ok: false`, the rule in `error`. */
+function refusedCommand(error) {
+    return { kind: MessageKind.COMMAND_RESULT, id: REFUSED_ID, ok: false, error };
+}
+const REFUSED_ID = 'production-policy';
+/** The ref a native gesture is judged under: the control was already inspected, so none is read. */
+const NATIVE_REF = 'native';
+/**
+ * Judge a native (CDP) gesture, which reaches the page without `Session.command`. Throws the
+ * refusal so the gesture is never performed.
+ */
+export async function assertNativeAllowed(drive, action, inspected) {
+    if (drive === undefined)
+        return;
+    const refusal = await drive.refuseCommand(ReticleCommand.ACT, { ref: NATIVE_REF, action }, () => Promise.resolve(inspected));
+    if (refusal !== undefined)
+        throw new Error(refusal);
+}

package/dist/portal/production/production-hello.d.ts

@@ -0,0 +1,23 @@
+import { HelloEnv, HelloScope } from '@reticlehq/core';
+import type { ProductionDrive } from './production-drive.js';
+/**
+ * Which HELLO may open a production session, and with what scope.
+ *
+ * The nonce decides, never the page. A page that says `production` without a production nonce is
+ * refused, because the pairing token belongs to a developer's machine and must not open a drive on a
+ * live site. A production nonce makes the session production even when the page says nothing: a page
+ * cannot talk its way out of the policy. The page may narrow `act` to `observe`, and never widen.
+ */
+/** The close reason for a refused production HELLO. Under the 123-byte close-frame limit. */
+export declare const PRODUCTION_HELLO_REFUSED = "production mode refused \u2014 it needs a live production session nonce and a scope";
+export type HelloAdmission = {
+    ok: true;
+    production?: ProductionDrive;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function admitHello(hello: {
+    env?: HelloEnv | undefined;
+    scope?: HelloScope | undefined;
+}, granted: ProductionDrive | undefined): HelloAdmission;

package/dist/portal/production/production-hello.js

@@ -0,0 +1,23 @@
+import { HelloEnv, HelloScope } from '@reticlehq/core';
+/**
+ * Which HELLO may open a production session, and with what scope.
+ *
+ * The nonce decides, never the page. A page that says `production` without a production nonce is
+ * refused, because the pairing token belongs to a developer's machine and must not open a drive on a
+ * live site. A production nonce makes the session production even when the page says nothing: a page
+ * cannot talk its way out of the policy. The page may narrow `act` to `observe`, and never widen.
+ */
+/** The close reason for a refused production HELLO. Under the 123-byte close-frame limit. */
+export const PRODUCTION_HELLO_REFUSED = 'production mode refused — it needs a live production session nonce and a scope';
+export function admitHello(hello, granted) {
+    const claimsProduction = hello.env === HelloEnv.PRODUCTION;
+    if (granted === undefined) {
+        return claimsProduction ? { ok: false, reason: PRODUCTION_HELLO_REFUSED } : { ok: true };
+    }
+    if (claimsProduction && hello.scope === undefined) {
+        return { ok: false, reason: PRODUCTION_HELLO_REFUSED };
+    }
+    if (hello.scope === HelloScope.OBSERVE)
+        granted.narrowToObserve();
+    return { ok: true, production: granted };
+}