@sequenceholdings/artifact-studio 0.4.0 → 0.5.0

package/dist/env-bindings.d.ts

@@ -0,0 +1,52 @@
+export interface NamedOrigin {
+    readonly name: string;
+    readonly origin: string;
+}
+export interface NamedWorkspace {
+    readonly name: string;
+    readonly workspaceName: string;
+    /** UUID of that workspace in the deploy environment, when the name resolved. */
+    readonly workspaceId?: string;
+    /** This deploy creates the workspace, so a missing remote id is not a foreign binding. */
+    readonly provisioned?: boolean;
+}
+export interface BindingSourceFile {
+    readonly path: string;
+    readonly content: string;
+    readonly encoding?: 'utf8' | 'base64';
+}
+export interface CrossEnvironmentBinding {
+    readonly path: string;
+    readonly kind: 'api_origin' | 'workspace';
+    readonly value: string;
+    readonly environment?: string;
+    readonly message: string;
+}
+export interface BindingCheckInput {
+    readonly deployEnvironment: string;
+    readonly deployOrigin: string;
+    readonly origins: readonly NamedOrigin[];
+    readonly workspaces: readonly NamedWorkspace[];
+    /** Workspace UUIDs that exist in the deploy environment. */
+    readonly workspaceIdsInDeployEnvironment: ReadonlySet<string>;
+    readonly files: readonly BindingSourceFile[];
+}
+export declare class CrossEnvironmentBindingError extends Error {
+    readonly deployEnvironment: string;
+    readonly bindings: readonly CrossEnvironmentBinding[];
+    constructor(deployEnvironment: string, bindings: readonly CrossEnvironmentBinding[]);
+}
+export declare function canonicalDeploymentOrigin(url: string): string | undefined;
+export declare function formatCrossEnvironmentBindings({ deployEnvironment, bindings, }: {
+    deployEnvironment: string;
+    bindings: readonly CrossEnvironmentBinding[];
+}): string;
+export declare function findCrossEnvironmentBindings(input: BindingCheckInput): CrossEnvironmentBinding[];
+export declare function assertNoCrossEnvironmentBindings({ deployEnvironment, deployOrigin, origins, workspaces, files, workspaceExists, }: {
+    deployEnvironment: string;
+    deployOrigin: string;
+    origins: readonly NamedOrigin[];
+    workspaces: readonly NamedWorkspace[];
+    files: readonly BindingSourceFile[];
+    workspaceExists: (workspaceId: string) => Promise<boolean>;
+}): Promise<void>;

package/dist/env-bindings.js

@@ -0,0 +1,180 @@
+import { basename, collectWorkspaceSlotIds, contentContainsOrigin, declaredTargets, contentOutsideTargets, originsDeclaredInFiles, scannable, workspaceSlotIds, } from './env-binding-scan.js';
+export class CrossEnvironmentBindingError extends Error {
+    deployEnvironment;
+    bindings;
+    constructor(deployEnvironment, bindings) {
+        super(formatCrossEnvironmentBindings({ deployEnvironment, bindings }));
+        this.deployEnvironment = deployEnvironment;
+        this.bindings = bindings;
+        this.name = 'CrossEnvironmentBindingError';
+    }
+}
+export function canonicalDeploymentOrigin(url) {
+    try {
+        return new URL(url).origin.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+export function formatCrossEnvironmentBindings({ deployEnvironment, bindings, }) {
+    const lines = bindings.map((binding) => `  ${binding.path}: ${binding.message}`);
+    return `Refusing to deploy to ${deployEnvironment} because the source binds another environment.\n${lines.join('\n')}`;
+}
+export function findCrossEnvironmentBindings(input) {
+    const deployOrigin = canonicalDeploymentOrigin(input.deployOrigin);
+    if (!deployOrigin) {
+        return [{
+                path: 'environment',
+                kind: 'api_origin',
+                value: input.deployOrigin,
+                message: `Invalid deployment URL '${input.deployOrigin}'.`,
+            }];
+    }
+    const origins = mergeOrigins(input.origins, originsDeclaredInFiles(input.files));
+    const present = workspaceIdsPresent(input);
+    return dedupe([
+        ...selectedTargetFindings({ ...input, deployOrigin, origins }),
+        ...foreignOriginFindings({ ...input, deployOrigin, origins }),
+        ...unresolvedWorkspaceFindings(input),
+        ...foreignWorkspaceFindings({ ...input, present }),
+    ]);
+}
+export async function assertNoCrossEnvironmentBindings({ deployEnvironment, deployOrigin, origins, workspaces, files, workspaceExists, }) {
+    const present = new Set();
+    for (const workspace of workspaces) {
+        if (workspace.workspaceId)
+            present.add(workspace.workspaceId.toLowerCase());
+    }
+    for (const workspaceId of collectWorkspaceSlotIds(files)) {
+        if (present.has(workspaceId))
+            continue;
+        if (await workspaceExists(workspaceId))
+            present.add(workspaceId);
+    }
+    const bindings = findCrossEnvironmentBindings({
+        deployEnvironment,
+        deployOrigin,
+        origins,
+        workspaces,
+        workspaceIdsInDeployEnvironment: present,
+        files,
+    });
+    if (bindings.length > 0)
+        throw new CrossEnvironmentBindingError(deployEnvironment, bindings);
+}
+function mergeOrigins(catalog, declared) {
+    return [...catalog, ...declared].map((origin) => ({
+        name: origin.name,
+        origin: canonicalDeploymentOrigin(origin.origin) ?? origin.origin.toLowerCase(),
+    }));
+}
+function selectedTargetFindings({ deployEnvironment, deployOrigin, origins, files, }) {
+    const findings = [];
+    for (const file of files) {
+        if (file.encoding === 'base64' || basename(file.path) !== 'artifact.bundle.yml')
+            continue;
+        const selected = declaredTargets(file.content)[deployEnvironment];
+        if (selected === undefined)
+            continue;
+        const origin = canonicalDeploymentOrigin(selected);
+        if (origin === deployOrigin)
+            continue;
+        const owner = origins.find((entry) => entry.origin === origin && entry.name !== deployEnvironment);
+        findings.push({
+            path: file.path,
+            kind: 'api_origin',
+            value: selected,
+            ...(owner ? { environment: owner.name } : {}),
+            message: owner
+                ? `targets.${deployEnvironment}.url is ${origin}, which is the ${owner.name} API origin`
+                : `targets.${deployEnvironment}.url is ${selected}, not the ${deployEnvironment} API origin ${deployOrigin}`,
+        });
+    }
+    return findings;
+}
+function foreignOriginFindings({ deployOrigin, origins, files, }) {
+    const foreign = new Map();
+    for (const origin of origins) {
+        if (origin.origin === deployOrigin)
+            continue;
+        const names = foreign.get(origin.origin) ?? [];
+        if (!names.includes(origin.name))
+            names.push(origin.name);
+        foreign.set(origin.origin, names);
+    }
+    const findings = [];
+    for (const file of files) {
+        if (!scannable(file))
+            continue;
+        const content = basename(file.path) === 'artifact.bundle.yml' ? contentOutsideTargets(file.content) : file.content;
+        for (const [origin, names] of foreign) {
+            if (!contentContainsOrigin(content, origin, new Set()))
+                continue;
+            findings.push({
+                path: file.path,
+                kind: 'api_origin',
+                value: origin,
+                environment: names[0],
+                message: `API origin ${origin} belongs to ${names.join(', ')}`,
+            });
+        }
+    }
+    return findings;
+}
+function unresolvedWorkspaceFindings(input) {
+    const seen = new Set();
+    const findings = [];
+    for (const workspace of input.workspaces) {
+        if (workspace.workspaceId || workspace.provisioned || seen.has(workspace.workspaceName))
+            continue;
+        seen.add(workspace.workspaceName);
+        findings.push({
+            path: 'sequence.app.yml',
+            kind: 'workspace',
+            value: workspace.workspaceName,
+            message: `Workspace "${workspace.workspaceName}" (${workspace.name}) does not resolve in ${input.deployEnvironment}`,
+        });
+    }
+    return findings;
+}
+function foreignWorkspaceFindings({ deployEnvironment, files, present, }) {
+    const findings = [];
+    const reported = new Set();
+    for (const file of files) {
+        if (!scannable(file))
+            continue;
+        for (const workspaceId of workspaceSlotIds(file)) {
+            if (present.has(workspaceId) || reported.has(`${file.path}:${workspaceId}`))
+                continue;
+            reported.add(`${file.path}:${workspaceId}`);
+            findings.push({
+                path: file.path,
+                kind: 'workspace',
+                value: workspaceId,
+                message: `Workspace ${workspaceId} does not resolve in ${deployEnvironment}`,
+            });
+        }
+    }
+    return findings;
+}
+function workspaceIdsPresent(input) {
+    const present = new Set();
+    for (const workspaceId of input.workspaceIdsInDeployEnvironment)
+        present.add(workspaceId.toLowerCase());
+    for (const workspace of input.workspaces) {
+        if (workspace.workspaceId)
+            present.add(workspace.workspaceId.toLowerCase());
+    }
+    return present;
+}
+function dedupe(bindings) {
+    const seen = new Set();
+    return bindings.filter((binding) => {
+        const key = `${binding.kind}\0${binding.path}\0${binding.value}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}

package/dist/gateway/control.d.ts

@@ -64,6 +64,24 @@ export declare const gatewayTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>], "kind">;
 export type GatewayTarget = z.infer<typeof gatewayTargetSchema>;
+declare const latticeInvokeGrantSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    deploymentId: z.ZodString;
+    frameworkBuildId: z.ZodString;
+    upstreamUrl: z.ZodString;
+    upstreamAudience: z.ZodOptional<z.ZodString>;
+    publicOrigin: z.ZodString;
+    environment: z.ZodString;
+    principalSub: z.ZodString;
+    path: z.ZodString;
+    serviceAccountId: z.ZodNullable<z.ZodString>;
+    resources: z.ZodObject<{
+        concurrency: z.ZodNumber;
+        max_instances: z.ZodNumber;
+        timeout_seconds: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type LatticeInvokeGrant = z.infer<typeof latticeInvokeGrantSchema>;
 export declare class GatewayControlError extends Error {
     readonly status: number;
     constructor(status: number);
@@ -86,9 +104,24 @@ export declare class ArtifactGatewayControl {
         target: GatewayTarget;
     }>;
     authorize(session: GatewaySession): Promise<GatewayTarget>;
+    /** SHA-256 both sides so a wrong bearer still takes constant time. */
+    tokenMatches(presented: string): boolean;
+    latticeInvoke(body: {
+        server: string;
+        path: string;
+        principalSub: string;
+        lattice: {
+            runId: string;
+            nodeId: string;
+            stepId: string;
+            processId: string;
+        };
+        requestId: string;
+    }): Promise<LatticeInvokeGrant>;
     tunnel({ token, sessionId, epoch }: {
         token: string;
         sessionId: string;
         epoch: number;
     }): Promise<TunnelLease>;
 }
+export {};

package/dist/gateway/control.js

@@ -1,3 +1,4 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
 import { z } from 'zod';
 import { normalizePublicOrigin } from '../tunnel/protocol.js';
 import { artifactRequestContextSchema } from '../server/request-context.js';
@@ -20,6 +21,23 @@ export const gatewayTargetSchema = z.discriminatedUnion('kind', [
 ]);
 const bootstrapSchema = z.object({ parentOrigin: z.string().transform(normalizePublicOrigin), channelId: id, nonce: z.string().min(16).max(255) });
 const usageResultSchema = z.object({ rejected: z.number().int().nonnegative() });
+const latticeInvokeGrantSchema = z.object({
+    projectId: id,
+    deploymentId: id,
+    frameworkBuildId: artifactNextFrameworkBuildIdSchema,
+    upstreamUrl: z.string().url(),
+    upstreamAudience: z.string().url().optional(),
+    publicOrigin: z.string().min(1).max(2048),
+    environment: id,
+    principalSub: id,
+    path: z.string().min(1).max(512),
+    serviceAccountId: id.nullable(),
+    resources: z.object({
+        concurrency: z.number().int().min(1).max(80),
+        max_instances: z.number().int().min(1).max(100),
+        timeout_seconds: z.number().int().min(1).max(300),
+    }).strict(),
+}).strict();
 export class GatewayControlError extends Error {
     status;
     constructor(status) {
@@ -106,6 +124,17 @@ export class ArtifactGatewayControl {
             throw new GatewayControlError(403);
         return target;
     }
+    /** SHA-256 both sides so a wrong bearer still takes constant time. */
+    tokenMatches(presented) {
+        if (presented.length === 0 || presented.length > 1024)
+            return false;
+        const actual = createHash('sha256').update(presented).digest();
+        const expected = createHash('sha256').update(this.options.token).digest();
+        return timingSafeEqual(actual, expected);
+    }
+    async latticeInvoke(body) {
+        return latticeInvokeGrantSchema.parse(await this.call('lattice-invoke', body));
+    }
     async tunnel({ token, sessionId, epoch }) {
         const value = await this.call('tunnel', { token, sessionId, epoch });
         const parsed = z.object({ sessionId: id, epoch: z.number().int().positive(), ownerId: id, projectId: id, environment: id, expiresAt: z.number().int().positive(), publicOrigin: z.string().transform(normalizePublicOrigin) }).parse(value);

package/dist/gateway/hosted-proxy.d.ts

@@ -32,5 +32,10 @@ export interface HostedArtifactProxyOptions {
         timeoutMs?: number;
     };
 }
+export declare function hostedIdentityToken(input: {
+    audience: string;
+    signal: AbortSignal;
+}): Promise<string>;
+export declare function cloudRunOrigin(value: string): URL;
 /** HTTP-only streaming hop. Authentication, CSRF and release admission happen before calling this. */
 export declare function proxyHostedArtifact(options: HostedArtifactProxyOptions): Promise<void>;

package/dist/gateway/hosted-proxy.js

@@ -32,7 +32,10 @@ async function defaultIdentityTokenProvider({ audience }) {
         throw error;
     }
 }
-function cloudRunOrigin(value) {
+export function hostedIdentityToken(input) {
+    return defaultIdentityTokenProvider(input);
+}
+export function cloudRunOrigin(value) {
     const url = new URL(value);
     if (!/^https:\/\/[a-z0-9.-]+\.run\.app\/?$/.test(value) || url.protocol !== 'https:' ||
         url.username || url.password || url.port || url.pathname !== '/' || url.search || url.hash ||

package/dist/gateway/lattice-invoke.d.ts

@@ -0,0 +1,48 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type ArtifactRequestAdmission } from './admission.js';
+import { type LatticeInvokeGrant } from './control.js';
+import { invokeHostedArtifact } from './lattice-upstream.js';
+import type { GatewayUsageReporter } from './usage.js';
+/** Lattice invoke, then the generic refusal for every other `/_sequence/` path. */
+export declare function routeSequenceRequest(input: {
+    request: IncomingMessage;
+    response: ServerResponse;
+    control: Parameters<typeof handleLatticeInvoke>[0]['control'];
+    privateKey: string;
+    keyId: string;
+    admission?: Pick<ArtifactRequestAdmission, 'acquire'>;
+    usage?: Pick<GatewayUsageReporter, 'record'>;
+}): Promise<boolean>;
+export declare function routeLatticeInvoke(input: {
+    request: IncomingMessage;
+    response: ServerResponse;
+    control: Parameters<typeof handleLatticeInvoke>[0]['control'];
+    privateKey: string;
+    keyId: string;
+    admission?: Pick<ArtifactRequestAdmission, 'acquire'>;
+    usage?: Pick<GatewayUsageReporter, 'record'>;
+}): Promise<boolean>;
+export declare function handleLatticeInvoke(input: {
+    request: IncomingMessage;
+    response: ServerResponse;
+    control: {
+        tokenMatches: (presented: string) => boolean;
+        latticeInvoke: (body: {
+            server: string;
+            path: string;
+            principalSub: string;
+            lattice: {
+                runId: string;
+                nodeId: string;
+                stepId: string;
+                processId: string;
+            };
+            requestId: string;
+        }) => Promise<LatticeInvokeGrant>;
+    };
+    privateKey: string;
+    keyId: string;
+    admission?: Pick<ArtifactRequestAdmission, 'acquire'>;
+    usage?: Pick<GatewayUsageReporter, 'record'>;
+    invoke?: typeof invokeHostedArtifact;
+}): Promise<void>;

package/dist/gateway/lattice-invoke.js

@@ -0,0 +1,245 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { z } from 'zod';
+import { isManagedServerInvokePath } from '../server/managed-server-path.js';
+import { ARTIFACT_CONTEXT_MAX_AGE_SECONDS, ARTIFACT_LATTICE_CONTEXT_MAX_AGE_SECONDS } from '../server/request-context.js';
+import { normalizePublicOrigin } from '../tunnel/protocol.js';
+import { ArtifactAdmissionError } from './admission.js';
+import { GatewayControlError } from './control.js';
+import { invokeHostedArtifact } from './lattice-upstream.js';
+import { signGatewayContext } from './session.js';
+const requestSchema = z.object({
+    server: z.string().min(1).max(255),
+    path: z.string().refine(isManagedServerInvokePath, 'Invalid managed server path'),
+    principalSub: z.string().min(1).max(255),
+    body: z.unknown().optional(),
+    lattice: z.object({
+        runId: z.string().min(1).max(255),
+        nodeId: z.string().min(1).max(255),
+        stepId: z.string().min(1).max(255),
+        processId: z.string().min(1).max(255),
+    }).strict(),
+    requestId: z.string().min(1).max(255),
+    timeoutMs: z.number().int().positive().max(300_000),
+}).strict();
+const BODY_CAP = Math.floor(1.1 * 1024 * 1024);
+/** Lattice invoke, then the generic refusal for every other `/_sequence/` path. */
+export async function routeSequenceRequest(input) {
+    if (await routeLatticeInvoke(input))
+        return true;
+    if (input.request.url?.startsWith('/_sequence/')) {
+        write(input.response, 404, { error: 'not_found' });
+        return true;
+    }
+    return false;
+}
+export async function routeLatticeInvoke(input) {
+    if ((input.request.url ?? '').split('?')[0] !== '/_sequence/lattice-invoke')
+        return false;
+    if (input.request.method !== 'POST') {
+        write(input.response, 404, { error: 'not_found' });
+        return true;
+    }
+    await handleLatticeInvoke(input);
+    return true;
+}
+export async function handleLatticeInvoke(input) {
+    const startedAt = new Date().toISOString();
+    const startedMs = performance.now();
+    const presented = bearer(input.request);
+    if (!presented || !input.control.tokenMatches(presented)) {
+        write(input.response, 403, { error: 'lattice_invoke_denied' });
+        return;
+    }
+    let parsed;
+    try {
+        parsed = requestSchema.parse(JSON.parse((await readBody(input.request)).toString('utf8')));
+    }
+    catch {
+        write(input.response, 400, { error: 'invalid_lattice_invoke' });
+        return;
+    }
+    let grant;
+    try {
+        grant = await input.control.latticeInvoke({
+            server: parsed.server,
+            path: parsed.path,
+            principalSub: parsed.principalSub,
+            lattice: parsed.lattice,
+            requestId: parsed.requestId,
+        });
+    }
+    catch (error) {
+        const status = error instanceof GatewayControlError ? error.status : 502;
+        if (status === 503) {
+            write(input.response, 503, { error: 'lattice_invoke_unavailable' });
+            return;
+        }
+        if (status === 401 || status === 403 || status === 404) {
+            write(input.response, 403, { error: 'lattice_invoke_denied' });
+            return;
+        }
+        write(input.response, 502, { error: 'lattice_invoke_failed' });
+        return;
+    }
+    if (grant.principalSub !== parsed.principalSub || grant.path !== parsed.path) {
+        write(input.response, 403, { error: 'lattice_invoke_denied' });
+        return;
+    }
+    const observed = await invokeAdmittedLattice({ ...input, grant, parsed });
+    input.usage?.record(latticeUsageEvent({ grant, requestId: parsed.requestId, startedAt, startedMs, ...observed }));
+}
+/** The browser proxy records on response finish. This path returns first, so it records the upstream result itself. */
+async function invokeAdmittedLattice(input) {
+    const signal = callerAbortSignal(input);
+    let release = () => { };
+    try {
+        const admitted = await acquireLatticeAdmission({ admission: input.admission, grant: input.grant });
+        release = admitted.bind(input.response, () => input.response.destroy());
+        const session = syntheticSession(input.grant, input.parsed.lattice);
+        const requestContext = signGatewayContext({
+            session,
+            method: 'POST',
+            path: input.grant.path,
+            privateKey: input.privateKey,
+            keyId: input.keyId,
+            serviceAccountId: input.grant.serviceAccountId,
+            requestId: input.parsed.requestId,
+            ttlSeconds: Math.min(ARTIFACT_LATTICE_CONTEXT_MAX_AGE_SECONDS, Math.max(ARTIFACT_CONTEXT_MAX_AGE_SECONDS, Math.ceil(input.parsed.timeoutMs / 1000))),
+        });
+        const result = await (input.invoke ?? invokeHostedArtifact)({
+            upstreamUrl: input.grant.upstreamUrl,
+            ...(input.grant.upstreamAudience ? { upstreamAudience: input.grant.upstreamAudience } : {}),
+            path: input.grant.path,
+            body: input.parsed.body ?? {},
+            requestContext,
+            timeoutMs: input.parsed.timeoutMs,
+            signal,
+        });
+        write(input.response, 200, { status: result.status, body: result.body });
+        return latticeOutcome({ aborted: signal.aborted, status: result.status });
+    }
+    catch (error) {
+        if (error instanceof ArtifactAdmissionError) {
+            writeAdmissionFailure(input.response, error);
+            return { outcome: 'error', httpStatus: error.status };
+        }
+        if (signal.aborted || input.response.writableEnded)
+            return { outcome: 'cancelled', httpStatus: 499 };
+        write(input.response, 502, { error: 'lattice_invoke_failed' });
+        return { outcome: 'error', httpStatus: 502 };
+    }
+    finally {
+        release();
+    }
+}
+function latticeOutcome({ aborted, status }) {
+    const httpStatus = status >= 100 && status <= 599 ? status : 502;
+    if (aborted)
+        return { outcome: 'cancelled', httpStatus };
+    return { outcome: httpStatus >= 400 ? 'error' : 'success', httpStatus };
+}
+function latticeUsageEvent(input) {
+    return {
+        // One id per gateway call. Retries of the same Lattice step reuse requestId,
+        // and a later attempt with a different outcome would be rejected as a
+        // conflicting duplicate. Delivery retries resend this same object.
+        eventId: `gateway:${randomUUID()}`,
+        requestId: input.requestId,
+        actorId: input.grant.principalSub,
+        projectId: input.grant.projectId,
+        deploymentId: input.grant.deploymentId,
+        environment: input.grant.environment,
+        startedAt: input.startedAt,
+        endedAt: new Date().toISOString(),
+        measurements: { requestCount: 1, durationMs: Math.max(0, Math.round(performance.now() - input.startedMs)) },
+        outcome: input.outcome,
+        httpStatus: input.httpStatus,
+    };
+}
+function writeAdmissionFailure(response, error) {
+    const capacity = error.status === 429;
+    write(response, capacity ? 429 : 503, {
+        error: capacity ? 'lattice_invoke_capacity' : 'lattice_invoke_unavailable',
+    });
+}
+/** Same per-app lease the browser proxy acquires. Missing admission fails closed. */
+async function acquireLatticeAdmission(input) {
+    if (!input.admission)
+        throw new ArtifactAdmissionError(503, 'admission_unavailable');
+    return input.admission.acquire({
+        environment: input.grant.environment,
+        projectId: input.grant.projectId,
+        deploymentId: input.grant.deploymentId,
+        resources: input.grant.resources,
+    });
+}
+/** The worker closing its connection must abort the Cloud Run POST still in flight. */
+function callerAbortSignal(input) {
+    const abort = new AbortController();
+    const stop = () => {
+        if (!input.response.writableEnded)
+            abort.abort();
+    };
+    if (typeof input.request.on === 'function')
+        input.request.on('aborted', stop);
+    if (typeof input.response.on === 'function')
+        input.response.on('close', stop);
+    return abort.signal;
+}
+function syntheticSession(grant, lattice) {
+    const publicOrigin = normalizePublicOrigin(grant.publicOrigin);
+    return {
+        version: 1,
+        kind: 'hosted',
+        sessionId: null,
+        deploymentId: grant.deploymentId,
+        frameworkBuildId: grant.frameworkBuildId,
+        projectId: grant.projectId,
+        ownerId: grant.principalSub,
+        environment: grant.environment,
+        publicOrigin,
+        expiresAt: Date.now() + 60_000,
+        published: true,
+        bridge: {
+            parentOrigin: publicOrigin,
+            channelId: 'lattice-invoke',
+            nonce: randomBytes(16).toString('hex'),
+        },
+        lattice,
+    };
+}
+function bearer(request) {
+    const header = request.headers.authorization;
+    if (typeof header !== 'string' || !header.startsWith('Bearer '))
+        return null;
+    return header.slice('Bearer '.length);
+}
+function readBody(request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let length = 0;
+        request.on('data', (chunk) => {
+            length += chunk.byteLength;
+            if (length > BODY_CAP) {
+                reject(new Error('body too large'));
+                request.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        request.on('end', () => resolve(Buffer.concat(chunks)));
+        request.on('error', reject);
+    });
+}
+function write(response, status, body) {
+    if (response.headersSent)
+        return;
+    response.writeHead(status, {
+        ...(status >= 400 ? { connection: 'close' } : {}),
+        'content-type': 'application/json',
+        'cache-control': 'no-store',
+        'x-content-type-options': 'nosniff',
+    });
+    response.end(JSON.stringify(body));
+}

package/dist/gateway/lattice-upstream.d.ts

@@ -0,0 +1,38 @@
+import { request as httpsRequest } from 'node:https';
+export interface HostedArtifactInvocation {
+    upstreamUrl: string;
+    upstreamAudience?: string;
+    path: string;
+    body: unknown;
+    requestContext: string;
+    timeoutMs: number;
+    /** Wall-clock cancellation from the caller, combined with `timeoutMs`. */
+    signal?: AbortSignal;
+    identityTokenProvider?: (input: {
+        audience: string;
+        signal: AbortSignal;
+    }) => Promise<string>;
+    /** Tests supply the socket. Production uses `https.request`. */
+    dial?: typeof httpsRequest;
+    /** Tests supply the hop. Production dials the validated Cloud Run origin. */
+    dispatch?: (input: {
+        origin: URL;
+        path: string;
+        headers: Record<string, string>;
+        body: Buffer;
+        timeoutMs: number;
+        signal: AbortSignal;
+    }) => Promise<{
+        status: number;
+        contentType?: string;
+        body: Buffer;
+    }>;
+}
+/**
+ * Buffered POST into a hosted Next.js app. The destination must already be a
+ * Cloud Run origin Atlas resolved; this rejects anything else before dialing.
+ */
+export declare function invokeHostedArtifact(input: HostedArtifactInvocation): Promise<{
+    status: number;
+    body: unknown;
+}>;