@wtfalch/foundry 0.61.0 → 0.63.0

package/dist/plan/stage-guards.js

@@ -1,6 +1,8 @@
 import { createHash } from 'node:crypto';
 import { bgKey } from './blue-green.js';
 import { envClass } from './stage-isolation.js';
+import { stageServicesReady } from './stage-services.js';
+import { stageSignInReady } from './stage-signin.js';
 /**
  * The guards that must hold before stage gets an exact copy of production (campaign T3 section 5, G2 and G3).
  * Each is checked here and recorded under a `bg.<id>.…` scope key only after it was verified live. Nothing in
@@ -77,6 +79,11 @@ export function buildStageProbes(input) {
             run: call ? () => call({ url: jobsUrl, syncKey, projectId }) : null,
         });
     }
+    else if (jobsUrl && syncKey) {
+        // Stage holds a jobs key but production's project is unknown: foundry never writes `JOBS_PROJECT_ID` into
+        // an app's env, so the probe cannot be built. It is kept as not run, never passed.
+        probes.push({ what: 'jobs:prod-project-unknown', run: null });
+    }
     const customersOrgId = input.liveCustomersOrgId;
     const workspacesUrl = stage.get('WORKSPACES_URL');
     const workspacesKey = stage.get('WORKSPACES_API_KEY');
@@ -166,8 +173,107 @@ export function stageGuardsReady(recorded, id) {
         missing.push('stagegate');
     if (!recorded[bgKey.stageProbes(id)]?.startsWith('ok:'))
         missing.push('stageprobes');
+    if (!stageSignInReady(recorded[bgKey.stageSignIn(id)]))
+        missing.push('stagesignin');
+    if (!stageServicesReady(recorded[bgKey.stageServices(id)]))
+        missing.push('stageservices');
     // An older ok: record outlives a later block; the stage state says what the last apply found.
     if (recorded[bgKey.stageState(id)] !== 'ok')
         missing.push('stagestate');
     return { ready: missing.length === 0, missing };
 }
+/** Milliseconds the host may take to name the people holding `releases:preview`. */
+export const STAGE_MEMBERS_TIMEOUT_MS = 10_000;
+const EMAIL = /^[^\s@,;<>()"]+@[^\s@,;<>()"]+\.[^\s@,;<>()"]+$/;
+/** Trimmed, lower-case, unique and sorted; anything that is not an email address is dropped. */
+export function normaliseEmails(list) {
+    const out = new Set();
+    for (const item of list) {
+        if (typeof item !== 'string')
+            continue;
+        const email = item.trim().toLowerCase();
+        if (email.length <= 254 && EMAIL.test(email))
+            out.add(email);
+    }
+    return [...out].sort();
+}
+/** The hash recorded for a sorted list. */
+export const membersHash = (sorted) => sha256(sorted.join('\n'));
+const errorName = (error) => (error instanceof Error ? error.name : 'unknown');
+/**
+ * The stage gate's list: `owners` always, plus the people `read` names. `members` is false when the read failed,
+ * timed out or the host has no port; the list is then the owners alone. One fixed log line names the subject and
+ * the error name, never an address.
+ */
+export async function stageGateEmails(input) {
+    const owners = normaliseEmails(input.owners);
+    if (!input.read) {
+        console.error(`${input.label}: stage gate members of ${input.subjectId} not read (NoMembersPort); the gate stays as it is`);
+        return { emails: owners, members: false };
+    }
+    let timer;
+    try {
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                const error = new Error('timed out');
+                error.name = 'MembersTimeout';
+                reject(error);
+            }, input.timeoutMs ?? STAGE_MEMBERS_TIMEOUT_MS);
+        });
+        const answer = await Promise.race([input.read({ orgId: input.orgId }), timeout]);
+        if (!answer || !Array.isArray(answer.emails)) {
+            const error = new Error('bad answer');
+            error.name = 'MembersInvalid';
+            throw error;
+        }
+        return { emails: normaliseEmails([...owners, ...answer.emails]), members: true };
+    }
+    catch (error) {
+        console.error(`${input.label}: stage gate members of ${input.subjectId} not read (${errorName(error)}); the gate stays as it is`);
+        return { emails: owners, members: false };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * One release tick for one subject whose stage gate is recorded: the gate's list becomes owners plus the people
+ * holding `releases:preview`. Nothing is done while the read fails, the list is unchanged since the last write
+ * (`bg.<id>.stagegatemembers`) or the Access call fails; the hash is recorded only after the Access call
+ * succeeded. Never throws.
+ */
+export async function syncStageGateMembers(input) {
+    const gateId = input.recorded[bgKey.stageGate(input.subjectId)];
+    if (!gateId)
+        return;
+    const { emails, members } = await stageGateEmails(input);
+    if (!members)
+        return;
+    if (emails.length === 0) {
+        console.error(`${input.label}: stage gate members of ${input.subjectId} not written (NoEmails)`);
+        return;
+    }
+    const hash = membersHash(emails);
+    if (input.recorded[bgKey.stageGateMembers(input.subjectId)] === hash)
+        return;
+    try {
+        if (!input.setPeople) {
+            const error = new Error('no setPeople');
+            error.name = 'NoGatePeoplePort';
+            throw error;
+        }
+        await input.setPeople(gateId, emails);
+    }
+    catch (error) {
+        console.error(`${input.label}: updating the stage gate of ${input.subjectId} failed (${errorName(error)}); the gate stays as it is`);
+        return;
+    }
+    input.record(bgKey.stageGateMembers(input.subjectId), hash);
+    try {
+        await input.persist();
+    }
+    catch (error) {
+        console.error(`${input.label}: recording the stage gate members of ${input.subjectId} failed (${errorName(error)})`);
+    }
+}

package/dist/plan/stage-isolation.js

@@ -173,6 +173,57 @@ const LIVE_MODE_KEY = /(^|[^a-z0-9])(sk|rk)_live_|^live_/;
 const sha256 = (value) => createHash('sha256').update(value).digest('hex');
 const URL_HOST = /^[a-z][a-z0-9+.-]*:\/\/(?:[^@/?#]*@)?([^/?#:]+)/i;
 const hostOf = (value) => URL_HOST.exec(value)?.[1]?.toLowerCase() ?? null;
+/** Every string inside a parsed JSON value. */
+function* strings(value) {
+    if (typeof value === 'string')
+        yield value;
+    else if (Array.isArray(value))
+        for (const v of value)
+            yield* strings(v);
+    else if (value && typeof value === 'object')
+        for (const v of Object.values(value))
+            yield* strings(v);
+}
+/**
+ * What a stage `AGORA_CONFIG` must not hold: production's client id, or production Agora's own host (its
+ * `AGORA_CANONICAL_HOST`, or an internal host). The issuer is shared on purpose and is not a production host
+ * unless it is one of those. Codes only; the value is parsed here and never returned.
+ */
+function agoraConfigViolations(value, prodByName, prodHosts) {
+    let stage;
+    try {
+        stage = JSON.parse(value);
+    }
+    catch {
+        return ['config_unreadable'];
+    }
+    const out = [];
+    let prodClientId;
+    try {
+        const prodValue = prodByName.get('AGORA_CONFIG')?.value;
+        prodClientId = prodValue
+            ? JSON.parse(prodValue).clientId
+            : undefined;
+    }
+    catch {
+        prodClientId = undefined;
+    }
+    const clientId = stage?.clientId;
+    if (typeof clientId === 'string' && clientId !== '' && clientId === prodClientId) {
+        out.push('value_shared');
+    }
+    const canonical = prodByName.get('AGORA_CANONICAL_HOST')?.value?.toLowerCase();
+    const hosts = new Set([...prodHosts, ...(canonical ? [canonical] : [])]);
+    for (const text of strings(stage)) {
+        const lower = text.toLowerCase();
+        const host = hostOf(text);
+        if (hosts.has(lower) || (host && hosts.has(host))) {
+            out.push('host_is_prod_internal');
+            break;
+        }
+    }
+    return out;
+}
 /**
  * The violations of stage isolation, as `<code>:<name>`; empty when stage is isolated. Names only: an env
  * name or a resource kind, never a value.
@@ -239,6 +290,11 @@ export function assertStageIsolated(input) {
                 out.add(`live_mcp_resource:${name}`);
             }
         }
+        if (kind === 'agora' && name === 'AGORA_CONFIG' && item.value !== undefined) {
+            for (const code of agoraConfigViolations(item.value, prodByName, prodHosts)) {
+                out.add(`${code}:${name}`);
+            }
+        }
         if (item.class === 'literal')
             continue;
         const shared = isSharedWithProd(name) && !(input.signIn?.customers && name === 'AUTH_ORGANIZATION_ID');

package/dist/plan/stage-services.d.ts

@@ -0,0 +1,93 @@
+import { type StageKind } from './stage-isolation.js';
+/**
+ * Stage's own files organisation, ai organisation and jobs project (campaign T3 section 5, G6): each service
+ * production's app uses gets an organisation or project of its own, named `<production name>-stage`, with keys
+ * minted for it only. A stage key is worthless on production, and production's key never reaches stage. Nothing
+ * here returns, logs or throws a secret: errors carry fixed text, ids and refs (CLAUDE.md, Platform steps).
+ */
+export type StageService = 'files' | 'ai' | 'jobs';
+export declare const STAGE_SERVICES: readonly StageService[];
+/** One credential a service shows once: the env name stage holds it under, and its value. */
+export interface StageSecret {
+    env: string;
+    value: string;
+}
+/** How one service is made for stage. The executor builds this from the platform's own files, ai and jobs ports. */
+export interface StageServicePort {
+    /** Whether the host can reach the service now and has what it needs. `false`: recorded absent, nothing minted. */
+    available(): Promise<boolean>;
+    /**
+     * Finds or makes stage's organisation (files, ai) or project (jobs), by its `<production name>-stage` name.
+     * Jobs shows its credentials with the first create; they come back here, once.
+     */
+    create(): Promise<{
+        id: string;
+        name?: string;
+        keyIds?: string[];
+        secrets?: StageSecret[];
+    }>;
+    /** Files and ai: mints stage's key in the organisation. The secret comes back once. */
+    mintKey?(id: string): Promise<{
+        keyIds: string[];
+        secrets: StageSecret[];
+    }>;
+    /** The env name that carries the organisation id, when the app reads one. */
+    idEnv?: string;
+    /** The held store the keys live in. A ref is an id, not a value. */
+    held: {
+        refFor(envName: string): string;
+        resolve(ref: string): Promise<string | null>;
+        put(ref: string, value: string): Promise<void>;
+    };
+}
+export interface StageServicesPort {
+    files?: StageServicePort;
+    ai?: StageServicePort;
+    jobs?: StageServicePort;
+    /** The id of production's jobs project, so stage's jobs key can be tried against it. */
+    prodJobsProjectId?: string;
+}
+/** Fixed text and ids only: safe to log, record and return. */
+export declare class StageServiceError extends Error {
+    readonly name = "StageServiceError";
+}
+/** The fixed reasons a used service is recorded absent. */
+export declare const STAGE_SERVICE_ABSENT: {
+    readonly noPort: "no-port";
+    readonly notForKind: "not-for-kind";
+};
+export interface StageServicesResult {
+    /** The env stage gets: urls and ids, and the keys. */
+    env: Array<{
+        key: string;
+        value: string;
+    }>;
+    /** `bg.<id>.stageservices`. */
+    record: string;
+    /** Per service: `ok:<hash>` or `absent:<service>:<reason>`. */
+    services: Partial<Record<StageService, string>>;
+}
+/**
+ * Makes stage's organisation or project in every service production's app uses (judged by the names in its env),
+ * mints its keys once and returns the env stage holds. Order per service: the organisation (its id recorded and
+ * persisted at once), then the key (its ids and held refs recorded and persisted before the secret is put), then
+ * the put. A run that failed halfway finds both and does the rest; a key is never minted twice, and when its ref
+ * is recorded but the held store no longer has it, this stops. A service the app does not use is left alone; one
+ * the kind does not take or the host cannot provide is recorded `absent:<service>:<reason>` and nothing is minted.
+ */
+export declare function ensureStageServices(input: {
+    id: string;
+    kind: StageKind;
+    /** The env of the live app. */
+    prod: ReadonlyMap<string, string>;
+    port: StageServicesPort | undefined;
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+    /** Registers a value for redaction before it is written anywhere. */
+    secret: (value: string) => void;
+    /** A fixed-text line for a service left absent. */
+    log?: (line: string) => void;
+}): Promise<StageServicesResult>;
+/** Whether the recorded `bg.<id>.stageservices` lets the copy go on. */
+export declare const stageServicesReady: (value: string | undefined) => boolean;

package/dist/plan/stage-services.js

@@ -0,0 +1,153 @@
+import { createHash } from 'node:crypto';
+import { bgKey } from './blue-green.js';
+import { isAllowed } from './stage-isolation.js';
+export const STAGE_SERVICES = ['files', 'ai', 'jobs'];
+/** Fixed text and ids only: safe to log, record and return. */
+export class StageServiceError extends Error {
+    name = 'StageServiceError';
+}
+/** The env names that show production's app uses a service, and the name of its URL. */
+const SERVICE_ENV = {
+    files: { evidence: ['FILES_URL', 'FILES_API_KEY', 'FILES_ORGANISATION_ID'], url: 'FILES_URL' },
+    ai: { evidence: ['AI_URL', 'AI_API_KEY', 'AI_ORGANISATION_ID'], url: 'AI_URL' },
+    jobs: {
+        evidence: ['JOBS_SCHEDULER_URL', 'JOBS_SYNC_KEY', 'JOBS_SIGNING_SECRET'],
+        url: 'JOBS_SCHEDULER_URL',
+    },
+};
+/** The fixed reasons a used service is recorded absent. */
+export const STAGE_SERVICE_ABSENT = {
+    noPort: 'no-port',
+    notForKind: 'not-for-kind',
+};
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+function parseKeys(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.ids) && parsed.refs ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Makes stage's organisation or project in every service production's app uses (judged by the names in its env),
+ * mints its keys once and returns the env stage holds. Order per service: the organisation (its id recorded and
+ * persisted at once), then the key (its ids and held refs recorded and persisted before the secret is put), then
+ * the put. A run that failed halfway finds both and does the rest; a key is never minted twice, and when its ref
+ * is recorded but the held store no longer has it, this stops. A service the app does not use is left alone; one
+ * the kind does not take or the host cannot provide is recorded `absent:<service>:<reason>` and nothing is minted.
+ */
+export async function ensureStageServices(input) {
+    const { id, kind, prod } = input;
+    const env = [];
+    const services = {};
+    for (const service of STAGE_SERVICES) {
+        const spec = SERVICE_ENV[service];
+        if (!spec.evidence.some((name) => prod.has(name)))
+            continue;
+        const at = `stage ${service} for ${id}`;
+        const absent = async (reason) => {
+            const value = `absent:${service}:${reason}`;
+            input.log?.(`${at}: left absent (${reason}); nothing was made`);
+            services[service] = value;
+            input.record(bgKey.stageService(id, service), value);
+            await input.persist();
+        };
+        if (!isAllowed(kind, spec.url)) {
+            await absent(STAGE_SERVICE_ABSENT.notForKind);
+            continue;
+        }
+        const port = input.port?.[service];
+        let available = false;
+        try {
+            available = port ? await port.available() : false;
+        }
+        catch {
+            // Not reachable: the same as no port.
+        }
+        if (!port || !available) {
+            await absent(STAGE_SERVICE_ABSENT.noPort);
+            continue;
+        }
+        const orgKey = bgKey.stageServiceOrg(id, service);
+        const keysKey = bgKey.stageServiceKeys(id, service);
+        const step = async (what, run) => {
+            try {
+                return await run();
+            }
+            catch {
+                // The cause can echo a credential; the step's name is all a reader needs.
+                throw new StageServiceError(`${at}: ${what} failed`);
+            }
+        };
+        let orgId = input.recorded()[orgKey];
+        let keys = parseKeys(input.recorded()[keysKey]);
+        let fresh;
+        const keep = async (ids, secrets) => {
+            const refs = {};
+            for (const s of secrets)
+                refs[s.env] = port.held.refFor(s.env);
+            keys = { ids, refs };
+            fresh = secrets;
+            for (const s of secrets)
+                input.secret(s.value);
+            input.record(keysKey, JSON.stringify(keys));
+            await input.persist();
+        };
+        if (!orgId) {
+            const made = await step('making the organisation', () => port.create());
+            orgId = made.id;
+            input.record(orgKey, orgId);
+            if (made.name)
+                input.record(bgKey.stageServiceName(id, service), made.name);
+            if (made.secrets && made.secrets.length > 0)
+                await keep(made.keyIds ?? [orgId], made.secrets);
+            else
+                await input.persist();
+        }
+        if (!keys) {
+            if (!port.mintKey) {
+                throw new StageServiceError(`${at}: ${orgId} exists but its credentials were never kept; remove it in the service and clear ${orgKey} before making it again`);
+            }
+            const mint = port.mintKey.bind(port);
+            const minted = await step('minting the key', () => mint(orgId));
+            await keep(minted.keyIds, minted.secrets);
+        }
+        const kept = keys;
+        // Put what was just minted; resolve the rest. A ref recorded with no held value is never minted again.
+        for (const [name, ref] of Object.entries(kept.refs)) {
+            const minted = fresh?.find((s) => s.env === name);
+            if (minted) {
+                await step('holding the key', () => port.held.put(ref, minted.value));
+                env.push({ key: name, value: minted.value });
+                continue;
+            }
+            const held = await step('reading the held key', () => port.held.resolve(ref));
+            if (!held) {
+                throw new StageServiceError(`${at}: key ${kept.ids.join(',')} was minted but ${ref} is no longer held; restore the held value`);
+            }
+            input.secret(held);
+            env.push({ key: name, value: held });
+        }
+        const url = prod.get(spec.url);
+        if (url)
+            env.push({ key: spec.url, value: url });
+        if (port.idEnv)
+            env.push({ key: port.idEnv, value: orgId });
+        const value = `ok:${sha256(JSON.stringify([service, orgId, kept.ids]))}`;
+        services[service] = value;
+        input.record(bgKey.stageService(id, service), value);
+        await input.persist();
+    }
+    const entries = Object.entries(services).sort(([a], [b]) => a.localeCompare(b));
+    return {
+        env,
+        services,
+        record: entries.length === 0 ? 'none' : `ok:${sha256(JSON.stringify(entries))}`,
+    };
+}
+/** Whether the recorded `bg.<id>.stageservices` lets the copy go on. */
+export const stageServicesReady = (value) => value === 'none' || value?.startsWith('ok:') === true;

package/dist/plan/stage-signin.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Stage signs in the same people through the same sign-in service, with a client, a broker entry key, an app
+ * key and a cookie secret of its own (campaign T3 section 5, G4). A stage session is worthless on production,
+ * and stage never holds a production credential. Nothing here returns, logs or throws a secret: errors name
+ * ids and refs only (CLAUDE.md, Platform steps, rules 1 and 6).
+ */
+/** What the stage client of a public SPA says: the client alone. */
+export interface StagePublicClientSpec {
+    /** `<production client name>-stage`. */
+    clientName: string;
+    organizationId: string;
+    /** Only on the stage host. */
+    redirectUris: string[];
+    postLogoutRedirectUris: string[];
+    /** `https://stage-<id>.<domain>`. */
+    origins: string[];
+}
+/** What the stage client and its broker entry say. Everything here is an id, a name or an address, never a key. */
+export interface StageSignInSpec {
+    /** `<production client name>-stage`. */
+    clientName: string;
+    /** The sign-in organisation production's users are in: the same one, so the same people can sign in. */
+    organizationId: string;
+    /** Only on the stage host. */
+    redirectUris: string[];
+    postLogoutRedirectUris: string[];
+    /** `<production broker entry name>-stage`. */
+    brokerName: string;
+    /** `https://stage-<id>.<domain>`. */
+    origins: string[];
+    from: string;
+    registration: boolean;
+    emailLink?: boolean;
+}
+/** What the broker entry of the stage client is asked to say (no key: the key is handed over on its own). */
+export interface StageBrokerEntry {
+    name: string;
+    organizationId: string;
+    clientId: string;
+    origins: string[];
+    from: string;
+    registration: boolean;
+    emailLink?: boolean;
+}
+/**
+ * The host's side of stage sign-in. `required: false` is a subject that does not sign in (recorded `none`);
+ * a subject that signs in but has no port here stays unrecorded, so the copy waits.
+ */
+export type StageSignInPort = {
+    required: false;
+} | {
+    /** A client only: no app key, no broker entry and no cookie secret (Agora is a static SPA). */
+    required: true;
+    public: true;
+    spec: StagePublicClientSpec;
+    findClient(name: string): Promise<{
+        appId: string;
+        clientId?: string;
+    } | undefined>;
+    createClient(spec: StagePublicClientSpec): Promise<{
+        appId: string;
+        clientId: string;
+    }>;
+} | {
+    required: true;
+    public?: undefined;
+    spec: StageSignInSpec;
+    /** The client of that name in production's sign-in project, to adopt after a create whose answer was lost. */
+    findClient(name: string): Promise<{
+        appId: string;
+        clientId?: string;
+    } | undefined>;
+    /** Makes the client in production's sign-in organisation and project. */
+    createClient(spec: StageSignInSpec): Promise<{
+        appId: string;
+        clientId: string;
+    }>;
+    /** Writes the broker entry with the key, and deploys the broker when its entries changed. */
+    writeBrokerEntry(entry: StageBrokerEntry, appKey: string): Promise<void>;
+    /** The held store the app key lives in. `ref` is an id, not a value. */
+    held: {
+        ref: string;
+        resolve(): Promise<string | null>;
+        put(value: string): Promise<void>;
+    };
+};
+/** Tries the broker write this many times (CLAUDE.md, Platform steps, rule 1). */
+export declare const STAGE_SIGNIN_DELIVERY_TRIES = 3;
+/** The guard value for a subject that does not sign in. */
+export declare const STAGE_SIGNIN_NONE = "none";
+/** Fixed text and ids only: safe to log, record and return. */
+export declare class StageSignInError extends Error {
+    readonly name = "StageSignInError";
+}
+export interface StageSignInResult {
+    /** The env stage gets: the client id and the app key. The cookie secret is stage's own, minted with the rest of its env. */
+    env: Array<{
+        key: string;
+        value: string;
+    }>;
+    /** `bg.<id>.stagesignin`: `ok:<hash of the client, app and entry ids>`. Never a value. */
+    guard: string;
+}
+/**
+ * Makes stage's client, mints its app key once and writes its broker entry. Order: the client first (its ids
+ * recorded and persisted at once, a lost answer is adopted by name), then the key (held, its ref recorded under
+ * {@link bgKey.stageSignInKey} and persisted before anything is delivered), then the broker entry (retried).
+ * A run that failed halfway finds both and does the rest; the key is never minted twice. When the ref is
+ * recorded but the held store no longer has the key, this stops: it never mints another.
+ */
+export declare function ensureStageSignIn(input: {
+    id: string;
+    port: Extract<StageSignInPort, {
+        required: true;
+        public?: undefined;
+    }>;
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+    /** Registers a value for redaction before it is written anywhere. */
+    secret: (value: string) => void;
+    generate: () => string;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<StageSignInResult>;
+/** `ok:<sha256 of the ids>`: the client, the app, the broker entry's name and its origins. No value goes in. */
+export declare function stageSignInGuard(input: {
+    appId: string;
+    clientId: string;
+    brokerName: string;
+    origins: readonly string[];
+}): string;
+/** Whether the recorded `bg.<id>.stagesignin` lets the copy go on. */
+export declare const stageSignInReady: (value: string | undefined) => boolean;
+export interface StagePublicClientResult {
+    clientId: string;
+    /** `bg.<id>.stagesignin`: `ok:<hash of the client and app ids and the origins>`. Never a value. */
+    guard: string;
+}
+/**
+ * Makes the public client of a static SPA's stage (Agora): found by name or created, its ids recorded and
+ * persisted at once. There is no key and no broker entry, so nothing secret exists. The guard hashes the app id,
+ * the client id, the client name and the origins.
+ */
+export declare function ensureStagePublicClient(input: {
+    id: string;
+    port: Extract<StageSignInPort, {
+        public: true;
+    }>;
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+}): Promise<StagePublicClientResult>;