@sequenceholdings/artifact-studio 0.4.0 → 0.6.1

package/dist/env-binding-scan.js

@@ -0,0 +1,179 @@
+import yaml from 'js-yaml';
+const UUID_SOURCE = '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}';
+const SCANNED_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.json', '.yml', '.yaml']);
+export function originsDeclaredInFiles(files) {
+    const origins = [];
+    for (const file of files) {
+        if (file.encoding === 'base64' || basename(file.path) !== 'artifact.bundle.yml')
+            continue;
+        for (const [name, url] of Object.entries(declaredTargets(file.content))) {
+            try {
+                origins.push({ name, origin: new URL(url).origin.toLowerCase() });
+            }
+            catch {
+                // A target that is not a URL is reported when the selected environment is checked.
+            }
+        }
+    }
+    return origins;
+}
+export function declaredTargets(content) {
+    let parsed;
+    try {
+        parsed = yaml.load(content);
+    }
+    catch {
+        return {};
+    }
+    if (!parsed || typeof parsed !== 'object' || !('targets' in parsed))
+        return {};
+    const targets = parsed.targets;
+    if (!targets || typeof targets !== 'object')
+        return {};
+    const urls = {};
+    for (const [name, value] of Object.entries(targets)) {
+        if (value && typeof value === 'object' && 'url' in value && typeof value.url === 'string')
+            urls[name] = value.url;
+    }
+    return urls;
+}
+export function contentContainsOrigin(content, origin, skippedLines) {
+    const haystack = content.toLowerCase();
+    const needle = origin.toLowerCase();
+    let from = 0;
+    while (from < haystack.length) {
+        const at = haystack.indexOf(needle, from);
+        if (at < 0)
+            return false;
+        const next = haystack[at + needle.length];
+        const line = haystack.slice(0, at).split('\n').length - 1;
+        if (!skippedLines.has(line) && (next === undefined || !/[a-z0-9.-]/.test(next)))
+            return true;
+        from = at + needle.length;
+    }
+    return false;
+}
+/** Manifest text with the root `targets` map removed, so its URLs are declarations. */
+export function contentOutsideTargets(content) {
+    let parsed;
+    try {
+        parsed = yaml.load(content);
+    }
+    catch {
+        return content;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || !('targets' in parsed))
+        return content;
+    const rest = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (key !== 'targets')
+            rest[key] = value;
+    }
+    return yaml.dump(rest, { lineWidth: -1 });
+}
+export function collectWorkspaceSlotIds(files) {
+    const ids = new Set();
+    for (const file of files) {
+        if (!scannable(file))
+            continue;
+        for (const workspaceId of workspaceSlotIds(file))
+            ids.add(workspaceId);
+    }
+    return [...ids];
+}
+export function workspaceSlotIds(file) {
+    const ids = new Set();
+    if (file.path.endsWith('.yml') || file.path.endsWith('.yaml'))
+        collectYamlWorkspaceIds(file.content, ids);
+    const marker = /workspace/gi;
+    let match;
+    while ((match = marker.exec(file.content))) {
+        const region = workspaceExpression(file.content, match.index);
+        for (const id of region.matchAll(new RegExp(UUID_SOURCE, 'gi')))
+            ids.add(id[0].toLowerCase());
+    }
+    return [...ids];
+}
+function workspaceExpression(content, start) {
+    let depth = 0;
+    let quote;
+    const limit = Math.min(content.length, start + 500);
+    for (let index = start; index < limit; index += 1) {
+        const char = content[index] ?? '';
+        const step = stepExpression({ char, depth, quote });
+        depth = step.depth;
+        quote = step.quote;
+        if (step.skip) {
+            index += 1;
+            continue;
+        }
+        if (step.done)
+            return content.slice(start, index);
+        if (char === '\n' && depth === 0 && expressionEnds(content.slice(index + 1))) {
+            return content.slice(start, index);
+        }
+    }
+    return content.slice(start, limit);
+}
+function stepExpression({ char, depth, quote }) {
+    if (quote) {
+        if (char === '\\')
+            return { depth, quote, skip: true };
+        return { depth, quote: char === quote ? undefined : quote };
+    }
+    if (char === '"' || char === "'" || char === '`')
+        return { depth, quote: char };
+    if (char === '(' || char === '[' || char === '{')
+        return { depth: depth + 1, quote };
+    if (char === ')' || char === ']' || char === '}')
+        return { depth: Math.max(0, depth - 1), quote };
+    if (char === ';' && depth === 0)
+        return { depth, quote, done: true };
+    return { depth, quote };
+}
+function expressionEnds(rest) {
+    const next = rest.split('\n')[0] ?? '';
+    return next.trim() === '' || (!/^[ \t]/.test(next) && !/^[)\]},.]/.test(next.trimStart()));
+}
+export function scannable(file) {
+    if (file.encoding === 'base64')
+        return false;
+    const name = basename(file.path);
+    if (name === 'pnpm-lock.yaml' || name === 'package-lock.json' || name === 'yarn.lock' || name.endsWith('.md'))
+        return false;
+    if (name === '.env')
+        return true;
+    const extension = name.includes('.') ? name.slice(name.lastIndexOf('.')) : '';
+    return SCANNED_EXTENSIONS.has(extension);
+}
+export function basename(path) {
+    const parts = path.split('/');
+    return parts[parts.length - 1] ?? path;
+}
+function collectYamlWorkspaceIds(content, ids) {
+    let parsed;
+    try {
+        parsed = yaml.load(content);
+    }
+    catch {
+        return;
+    }
+    walkYaml(parsed, null, ids);
+}
+function walkYaml(node, parentKey, ids) {
+    if (!node || typeof node !== 'object')
+        return;
+    if (Array.isArray(node)) {
+        for (const item of node)
+            walkYaml(item, parentKey, ids);
+        return;
+    }
+    for (const [key, value] of Object.entries(node)) {
+        if (parentKey === 'storage' && new RegExp(`^${UUID_SOURCE}$`, 'i').test(key))
+            ids.add(key.toLowerCase());
+        if (/workspace/i.test(key) && typeof value === 'string' && new RegExp(`^${UUID_SOURCE}$`, 'i').test(value)) {
+            ids.add(value.toLowerCase());
+        }
+        walkYaml(value, key, ids);
+    }
+}

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>;