@sequenceholdings/artifact-studio 0.2.6 → 0.3.1

package/dist/tunnel/redis.js

@@ -0,0 +1,404 @@
+import { randomUUID } from 'node:crypto';
+import { DEFAULT_TUNNEL_LIMITS, parseTunnelFrame } from './protocol.js';
+import { redisIdentifier as identifier, redisNamespaceSchema as namespaceSchema, redisLeaseSchema as leaseSchema } from './redis-ownership.js';
+import { RelaySocket } from './redis-socket.js';
+import { deriveRelayFrameKey, RelayFrameAuthenticator } from './redis-auth.js';
+export { RedisTunnelOwnership } from './redis-ownership.js';
+/** Internal Redis channels contain authorized application traffic. Deploy them
+ * on the environment's private, authenticated Redis and disable command replay.
+ * Every message is authenticated with a gateway-only key: other Redis clients
+ * can neither inject, redirect nor replay tunnel frames. */
+export class RedisTunnelRelay {
+    options;
+    started = false;
+    closed = false;
+    attached = new Map();
+    connected = new Map();
+    frames;
+    publishing = Promise.resolve();
+    receiving = Promise.resolve();
+    outgoingBytes = 0;
+    incomingBytes = 0;
+    generation = 0;
+    starting;
+    constructor(options) {
+        this.options = options;
+        identifier.parse(options.nodeId);
+        namespaceSchema.parse(options.namespace);
+        if (options.namespace !== options.ownership.namespace || Object.is(options.publisher, options.subscriber))
+            throw new Error('Separate, environment-scoped Redis clients are required');
+        this.frames = new RelayFrameAuthenticator(deriveRelayFrameKey({ secret: options.secret, namespace: options.namespace }));
+        if (options.connectTimeoutMs !== undefined && (!Number.isSafeInteger(options.connectTimeoutMs) || options.connectTimeoutMs < 1 || options.connectTimeoutMs > 60_000))
+            throw new Error('Invalid tunnel connect timeout');
+        const policy = options.publisher.options;
+        if (policy.enableOfflineQueue !== false || policy.autoResendUnfulfilledCommands !== false || policy.maxRetriesPerRequest !== 0) {
+            throw new Error('Tunnel Redis publisher must disable offline queues, command replay and retries');
+        }
+    }
+    channel(nodeId) { return `artifact-tunnel:${this.options.namespace}:node:${identifier.parse(nodeId)}`; }
+    assertStarted() { if (!this.started || this.closed)
+        throw new Error('Tunnel relay is not subscribed'); }
+    isReady() { return this.started && !this.closed; }
+    async start() {
+        if (this.closed)
+            throw new Error('Tunnel relay is closed');
+        if (this.started)
+            return;
+        if (this.starting)
+            return this.starting;
+        this.starting = this.subscribe();
+        try {
+            await this.starting;
+        }
+        finally {
+            this.starting = undefined;
+        }
+    }
+    async subscribe() {
+        const generation = this.generation;
+        this.removeListeners();
+        this.options.subscriber.on('message', this.onMessage);
+        for (const event of ['error', 'close', 'end', 'reconnecting'])
+            this.options.subscriber.on(event, this.onRedisFailure);
+        try {
+            await this.options.subscriber.subscribe(this.channel(this.options.nodeId));
+            if (this.closed || generation !== this.generation)
+                throw new Error('Tunnel relay subscription interrupted');
+            this.started = true;
+        }
+        catch (error) {
+            this.removeListeners();
+            throw error;
+        }
+    }
+    removeListeners() {
+        this.options.subscriber.off('message', this.onMessage);
+        for (const event of ['error', 'close', 'end', 'reconnecting'])
+            this.options.subscriber.off(event, this.onRedisFailure);
+    }
+    onRedisFailure = () => {
+        this.generation++;
+        this.started = false;
+        for (const owner of this.attached.values())
+            this.closeOwner(owner);
+        for (const connection of this.connected.values())
+            connection.socket.terminate();
+    };
+    /**
+     * A local overload or malformed envelope resets relayed traffic like a Redis failure (in-flight
+     * streams fail closed), but the subscriber is still connected and emits no 'ready' event for
+     * gateway-main to restart on. Resubscribe now so a transient burst cannot leave the node unready.
+     */
+    onRelayOverload = () => {
+        this.onRedisFailure();
+        if (!this.closed)
+            void this.start().catch(() => undefined);
+    };
+    onMessage = (channel, raw) => {
+        if (!this.started || channel !== this.channel(this.options.nodeId))
+            return;
+        // Authenticate before anything else: a message without a valid MAC, fresh timestamp and new
+        // sequence is dropped without resetting live traffic, so a Redis client cannot inject or DoS.
+        const envelope = this.frames.open({ channel, message: raw });
+        if (!envelope) {
+            this.options.onRejectedFrame?.();
+            return;
+        }
+        const bytes = Buffer.byteLength(raw);
+        if (this.incomingBytes + bytes > DEFAULT_TUNNEL_LIMITS.maxBufferedBytes) {
+            this.onRelayOverload();
+            return;
+        }
+        this.incomingBytes += bytes;
+        const generation = this.generation;
+        this.receiving = this.receiving.then(async () => {
+            if (this.started && generation === this.generation)
+                await this.receive(envelope);
+        }).catch(() => this.onRelayOverload()).finally(() => { this.incomingBytes -= bytes; });
+    };
+    publish(nodeId, envelope) {
+        const channel = this.channel(nodeId);
+        // Sealed in call order, so each destination sees this node's sequence numbers ascending.
+        const payload = this.frames.seal({ channel, envelope });
+        const bytes = Buffer.byteLength(payload);
+        if (this.outgoingBytes + bytes > DEFAULT_TUNNEL_LIMITS.maxBufferedBytes)
+            return Promise.reject(new Error('Tunnel relay publish queue exceeded'));
+        this.outgoingBytes += bytes;
+        const generation = this.generation;
+        const sending = this.publishing.then(async () => {
+            if (envelope.type !== 'close' && (generation !== this.generation || !this.started || this.closed))
+                throw new Error('Tunnel relay generation changed');
+            if (await this.options.publisher.publish(channel, payload) < 1)
+                throw new Error('Tunnel node is offline');
+        });
+        this.publishing = sending.catch(() => undefined).finally(() => { this.outgoingBytes -= bytes; });
+        return sending;
+    }
+    envelope(lease, connection, type, destination, frame) {
+        return { type, destination, source: this.options.nodeId, connection, sessionId: lease.sessionId, epoch: lease.epoch, ...(frame === undefined ? {} : { frame }) };
+    }
+    async current(lease, nodeId) {
+        const owner = await this.options.ownership.lookup(lease.sessionId);
+        if (lease.environment !== this.options.namespace || owner?.epoch !== lease.epoch || owner.nodeId !== nodeId)
+            return false;
+        lease.expiresAt = owner.expiresAt;
+        return owner.expiresAt > Date.now();
+    }
+    async verifiedLease(lease) {
+        const input = leaseSchema.parse(lease);
+        const recorded = await this.options.ownership.resolveLease(input.sessionId);
+        if (!recorded || input.environment !== this.options.namespace || Object.keys(recorded).some((key) => Reflect.get(recorded, key) !== Reflect.get(input, key)))
+            throw new Error('Tunnel lease is not current');
+        return input;
+    }
+    async attach(input, socket) {
+        try {
+            await this.attachOwned(input, socket);
+        }
+        catch (error) {
+            socket.terminate();
+            if (this.attached.get(input.sessionId)?.lease.epoch !== input.epoch) {
+                await this.options.ownership.release(input.sessionId, input.epoch, this.options.nodeId).catch(() => undefined);
+            }
+            throw error;
+        }
+    }
+    async attachOwned(input, socket) {
+        this.assertStarted();
+        const lease = await this.verifiedLease(input);
+        if (!(await this.current(lease, this.options.nodeId)) || socket.readyState !== 1)
+            throw new Error('Tunnel is owned by another node');
+        this.assertStarted();
+        const previous = this.attached.get(lease.sessionId);
+        if (previous && previous.lease.epoch >= lease.epoch)
+            throw new Error('Duplicate tunnel owner');
+        if (previous)
+            this.closeOwner(previous);
+        let checking = false;
+        const timer = setInterval(() => {
+            for (const remote of owner.remotes.values())
+                if (Date.now() - remote.lastSeen > 15_000) {
+                    this.closeRemote(owner, remote);
+                    void this.publish(remote.nodeId, this.envelope(lease, remote.connection, 'close', 'requester')).catch(() => undefined);
+                }
+            if (checking || owner.stopped)
+                return;
+            checking = true;
+            void this.current(lease, this.options.nodeId).then((valid) => { if (!valid)
+                this.closeOwner(owner); })
+                .catch(() => this.closeOwner(owner)).finally(() => { checking = false; });
+        }, 5000);
+        timer.unref();
+        const owner = { lease, socket, timer, remotes: new Map(), streams: new Map(), receiving: Promise.resolve(), queuedBytes: 0, stopped: false };
+        this.attached.set(lease.sessionId, owner);
+        socket.on('message', (data, binary) => this.fromDeveloper(owner, data, binary));
+        socket.once('close', () => this.closeOwner(owner));
+        socket.on('error', () => this.closeOwner(owner));
+    }
+    async connect(input) {
+        this.assertStarted();
+        const lease = await this.verifiedLease(input);
+        const owner = await this.options.ownership.lookup(lease.sessionId);
+        if (!owner || owner.epoch !== lease.epoch)
+            throw new Error('Tunnel owner unavailable');
+        this.assertStarted();
+        const id = randomUUID();
+        return new Promise((resolve, reject) => {
+            const socket = new RelaySocket(async (frame) => {
+                if (!(await this.current(lease, owner.nodeId)))
+                    throw new Error('Tunnel owner changed');
+                await this.publish(owner.nodeId, this.envelope(lease, id, 'frame', 'owner', frame));
+            }, () => {
+                this.closeConnection(id, connection);
+                void this.publish(owner.nodeId, this.envelope(lease, id, 'close', 'owner')).catch(() => undefined);
+            });
+            const timer = setTimeout(() => this.closeConnection(id, connection), this.options.connectTimeoutMs ?? 5000);
+            timer.unref();
+            const heartbeat = setInterval(() => {
+                if (socket.readyState === 1)
+                    void this.publish(owner.nodeId, this.envelope(lease, id, 'heartbeat', 'owner')).catch(() => socket.terminate());
+            }, 5000);
+            heartbeat.unref();
+            const connection = { lease, ownerNode: owner.nodeId, socket, timer, heartbeat, resolve, reject };
+            this.connected.set(id, connection);
+            void this.publish(owner.nodeId, this.envelope(lease, id, 'open', 'owner')).catch(() => this.closeConnection(id, connection));
+        });
+    }
+    async receive(message) {
+        if (message.destination === 'requester') {
+            await this.toRequester(message);
+            return;
+        }
+        const owner = this.attached.get(message.sessionId);
+        if (!owner || owner.lease.epoch !== message.epoch || !(await this.current(owner.lease, this.options.nodeId))) {
+            if (owner && owner.lease.epoch === message.epoch)
+                this.closeOwner(owner);
+            await this.publish(message.source, { ...message, type: 'close', destination: 'requester', source: this.options.nodeId, frame: undefined }).catch(() => undefined);
+            return;
+        }
+        if (message.type === 'revoke') {
+            this.closeOwner(owner);
+            return;
+        }
+        const remote = owner.remotes.get(message.connection);
+        if (message.type === 'open') {
+            if (remote || owner.remotes.size >= DEFAULT_TUNNEL_LIMITS.maxStreams)
+                throw new Error('Duplicate or excessive tunnel connections');
+            owner.remotes.set(message.connection, { nodeId: message.source, connection: message.connection, lastSeen: Date.now() });
+            await this.publish(message.source, this.envelope(owner.lease, message.connection, 'ready', 'requester'));
+            return;
+        }
+        if (!remote || remote.nodeId !== message.source)
+            return;
+        remote.lastSeen = Date.now();
+        if (message.type === 'heartbeat')
+            return;
+        if (message.type === 'close') {
+            this.closeRemote(owner, remote);
+            return;
+        }
+        if (message.type !== 'frame' || message.frame === undefined)
+            throw new Error('Invalid owner relay message');
+        await this.toDeveloper(owner, remote, message.frame);
+    }
+    async toRequester(message) {
+        const connection = this.connected.get(message.connection);
+        if (!connection || connection.ownerNode !== message.source || connection.lease.sessionId !== message.sessionId || connection.lease.epoch !== message.epoch)
+            return;
+        if (message.type === 'close' || !(await this.current(connection.lease, connection.ownerNode))) {
+            this.closeConnection(message.connection, connection);
+            return;
+        }
+        if (message.type === 'ready') {
+            if (connection.socket.readyState !== 0)
+                throw new Error('Duplicate tunnel ready');
+            clearTimeout(connection.timer);
+            connection.socket.readyState = 1;
+            connection.resolve(connection.socket);
+        }
+        else if (message.type === 'frame' && message.frame !== undefined && connection.socket.readyState === 1) {
+            parseTunnelFrame(message.frame);
+            connection.socket.emit('message', Buffer.from(message.frame), false);
+        }
+        else
+            throw new Error('Invalid requester relay message');
+    }
+    async toDeveloper(owner, remote, raw) {
+        const frame = parseTunnelFrame(raw);
+        if (frame.type === 'ready' || frame.type === 'response' || frame.type === 'ws-open')
+            throw new Error('Invalid requester frame direction');
+        const route = owner.streams.get(frame.id);
+        if (frame.type === 'request') {
+            if (route || owner.streams.size >= DEFAULT_TUNNEL_LIMITS.maxStreams) {
+                this.closeRemote(owner, remote);
+                await this.publish(remote.nodeId, this.envelope(owner.lease, remote.connection, 'close', 'requester'));
+                return;
+            }
+            owner.streams.set(frame.id, remote);
+        }
+        else if (!route || route.connection !== remote.connection || route.nodeId !== remote.nodeId)
+            return;
+        if (frame.type === 'cancel' || frame.type === 'ws-close')
+            owner.streams.delete(frame.id);
+        await this.writeDeveloper(owner, raw);
+    }
+    writeDeveloper(owner, raw) {
+        if (owner.stopped || owner.socket.readyState !== 1 || owner.socket.bufferedAmount + Buffer.byteLength(raw) > DEFAULT_TUNNEL_LIMITS.maxBufferedBytes) {
+            this.closeOwner(owner);
+            return Promise.reject(new Error('Developer tunnel disconnected or saturated'));
+        }
+        return new Promise((resolve, reject) => owner.socket.send(raw, (error) => error ? reject(error) : resolve()));
+    }
+    fromDeveloper(owner, data, binary) {
+        if (owner.stopped)
+            return;
+        if (binary || !(typeof data === 'string' || Buffer.isBuffer(data))) {
+            this.closeOwner(owner);
+            return;
+        }
+        const bytes = Buffer.byteLength(data);
+        if (bytes > DEFAULT_TUNNEL_LIMITS.maxFrameBytes || owner.queuedBytes + bytes > DEFAULT_TUNNEL_LIMITS.maxBufferedBytes) {
+            this.closeOwner(owner);
+            return;
+        }
+        const raw = typeof data === 'string' ? data : data.toString('utf8');
+        owner.queuedBytes += bytes;
+        owner.receiving = owner.receiving.then(async () => {
+            if (owner.stopped)
+                return;
+            if (!(await this.current(owner.lease, this.options.nodeId))) {
+                this.closeOwner(owner);
+                return;
+            }
+            const frame = parseTunnelFrame(data);
+            if (frame.type === 'request' || frame.type === 'ready')
+                throw new Error('Developer cannot initiate requests or readiness');
+            const remote = owner.streams.get(frame.id);
+            if (!remote)
+                return;
+            await this.publish(remote.nodeId, this.envelope(owner.lease, remote.connection, 'frame', 'requester', raw));
+            if (frame.type === 'end' || frame.type === 'cancel' || frame.type === 'ws-close')
+                owner.streams.delete(frame.id);
+        }).catch(() => this.closeOwner(owner)).finally(() => { owner.queuedBytes -= bytes; });
+    }
+    closeRemote(owner, remote) {
+        owner.remotes.delete(remote.connection);
+        for (const [id, route] of owner.streams) {
+            if (route.connection !== remote.connection)
+                continue;
+            owner.streams.delete(id);
+            void this.writeDeveloper(owner, JSON.stringify({ type: 'cancel', id })).catch(() => this.closeOwner(owner));
+        }
+    }
+    closeOwner(owner) {
+        if (owner.stopped)
+            return;
+        owner.stopped = true;
+        clearInterval(owner.timer);
+        if (this.attached.get(owner.lease.sessionId) === owner)
+            this.attached.delete(owner.lease.sessionId);
+        owner.socket.terminate();
+        for (const remote of owner.remotes.values())
+            void this.publish(remote.nodeId, this.envelope(owner.lease, remote.connection, 'close', 'requester')).catch(() => undefined);
+        owner.remotes.clear();
+        owner.streams.clear();
+        void this.options.ownership.release(owner.lease.sessionId, owner.lease.epoch, this.options.nodeId).catch(() => undefined);
+    }
+    closeConnection(id, connection) {
+        if (this.connected.get(id) !== connection)
+            return;
+        this.connected.delete(id);
+        clearTimeout(connection.timer);
+        clearInterval(connection.heartbeat);
+        connection.socket.finish();
+        connection.reject(new Error('Tunnel owner disconnected'));
+    }
+    disconnect(sessionId) {
+        identifier.parse(sessionId);
+        const owner = this.attached.get(sessionId);
+        if (owner)
+            this.closeOwner(owner);
+        for (const [id, connection] of this.connected)
+            if (connection.lease.sessionId === sessionId)
+                this.closeConnection(id, connection);
+        if (!owner)
+            void this.options.ownership.lookup(sessionId).then((remote) => {
+                if (remote)
+                    return this.publish(remote.nodeId, { type: 'revoke', destination: 'owner', source: this.options.nodeId, connection: randomUUID(), sessionId, epoch: remote.epoch });
+            }).catch(() => undefined);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.started = false;
+        this.generation++;
+        for (const owner of this.attached.values())
+            this.closeOwner(owner);
+        for (const connection of this.connected.values())
+            connection.socket.terminate();
+        await this.publishing;
+        this.removeListeners();
+        await this.options.subscriber.unsubscribe(this.channel(this.options.nodeId));
+    }
+}

package/dist/tunnel/transport.d.ts

@@ -0,0 +1,17 @@
+import type { EventEmitter } from 'node:events';
+import type { TunnelLease } from './broker.js';
+/** WebSocket-compatible framed transport. Remote transports use the same
+ * end-to-end ACK protocol; publishing a frame is not acknowledgement. */
+export interface TunnelSocket extends EventEmitter {
+    readonly readyState: number;
+    readonly bufferedAmount: number;
+    send(data: string, callback: (error?: Error) => void): void;
+    terminate(): void;
+}
+export interface TunnelRelay {
+    isReady?(): boolean;
+    attach(lease: TunnelLease, socket: TunnelSocket): Promise<void>;
+    connect(lease: TunnelLease): Promise<TunnelSocket>;
+    disconnect(sessionId: string): void;
+    close(): Promise<void>;
+}

package/dist/tunnel/transport.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -9,7 +9,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.6",
+  "version": "0.3.1",
   "description": "SDK types and CLI library for building Artifact Studio apps. Driven via `seq-studio artifact <sub>` (@sequenceholdings/studio-cli), which runs the `./cli` runCli export.",
   "type": "module",
   "exports": {
@@ -64,6 +64,62 @@
     "./child-environment": {
       "types": "./dist/child-environment.d.ts",
       "default": "./dist/child-environment.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./runtime-contracts": {
+      "types": "./dist/runtime-contracts.d.ts",
+      "default": "./dist/runtime-contracts.js"
+    },
+    "./artifact-ignore": {
+      "types": "./dist/artifact-ignore.d.ts",
+      "default": "./dist/artifact-ignore.js"
+    },
+    "./next-source-hash": {
+      "types": "./dist/next-source-hash.d.ts",
+      "default": "./dist/next-source-hash.js"
+    },
+    "./next-public-fonts": {
+      "types": "./dist/next-public-fonts.d.ts",
+      "default": "./dist/next-public-fonts.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./server/context": {
+      "types": "./dist/server/request-context.d.ts",
+      "default": "./dist/server/request-context.js"
+    },
+    "./server/broker-contract": {
+      "types": "./dist/server/broker-contract.d.ts",
+      "default": "./dist/server/broker-contract.js"
+    },
+    "./server/release-forms": {
+      "types": "./dist/server/release-forms.d.ts",
+      "default": "./dist/server/release-forms.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "default": "./dist/next.js"
+    },
+    "./next/protocol": {
+      "types": "./dist/next/protocol.d.ts",
+      "default": "./dist/next/protocol.js"
+    },
+    "./next-cache": {
+      "types": "./dist/next-cache/index.d.ts",
+      "default": "./dist/next-cache/index.js"
+    },
+    "./next-cache/config": {
+      "types": "./dist/next-cache/config.d.ts",
+      "default": "./dist/next-cache/config.js"
+    },
+    "./tunnel": {
+      "types": "./dist/tunnel/index.d.ts",
+      "default": "./dist/tunnel/index.js"
     }
   },
   "files": [
@@ -72,7 +128,7 @@
     "VERSION-PIN.md"
   ],
   "dependencies": {
-    "@sequenceholdings/atlas-ui": "3.1.2",
+    "@sequenceholdings/atlas-ui": "3.3.0",
     "@tailwindcss/postcss": "^4.1.8",
     "@tailwindcss/vite": "^4.1.8",
     "@tanstack/react-query": "^4.36.1",
@@ -85,14 +141,21 @@
     "tw-animate-css": "^1.4.0",
     "vite": "8.0.16",
     "zod": "^4.1.13",
+    "ws": "^8.21.0",
+    "ioredis": "^5.10.0",
+    "google-auth-library": "^10.5.0",
+    "server-only": "0.0.1",
+    "parse5": "7.3.0",
     "@sequenceholdings/lattice-form-renderer": "0.1.3",
-    "@sequenceholdings/storage": "0.1.0"
+    "@sequenceholdings/storage": "0.1.0",
+    "@sequenceholdings/orm": "2.1.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "typescript": "^5.6.0",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.11",
+    "@types/ws": "^8.18.1"
   },
   "scripts": {
     "build": "rm -rf dist && tsc && node scripts/copy-templates.mjs",

package/templates/nextjs/.artifactignore

@@ -0,0 +1,14 @@
+.git/
+node_modules/
+.next/
+next-env.d.ts
+.artifact/
+.artifact-studio/
+# Environment files are excluded by the source packager independently.
+.env
+.env.local
+.env.development.local
+.env.production.local
+tsconfig.tsbuildinfo
+coverage/
+.DS_Store