@sequenceholdings/artifact-studio 0.2.6 → 0.3.0

package/dist/tunnel/redis-ownership.js

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import { normalizePublicOrigin } from './protocol.js';
+export const redisIdentifier = z.string().min(1).max(128).regex(/^[a-zA-Z0-9_-]+$/);
+/** An APP_ENV deployment identity (tenant ids like banksouth_mortgage, or <tenant_id>_staging), kept
+ * free of the ':' key delimiter and '{}' hash-tag braces used in Redis keys and channels. */
+export const redisNamespaceSchema = z.string().max(63).regex(/^[a-z][a-z0-9_-]*$/);
+export const redisLeaseSchema = z.object({
+    sessionId: redisIdentifier, epoch: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    ownerId: z.string().min(1).max(512), projectId: redisIdentifier, environment: redisNamespaceSchema,
+    expiresAt: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    publicOrigin: z.string().max(2048).transform(normalizePublicOrigin),
+}).strict();
+const ownershipSchema = z.object({ nodeId: redisIdentifier, lease: redisLeaseSchema }).strict();
+const MAX_LEASE_MS = 8 * 60 * 60 * 1000;
+const EPOCH_RETENTION_MS = 9 * 60 * 60 * 1000;
+const CLAIM = `-- artifact-tunnel-claim-v1
+local previous = tonumber(redis.call('GET', KEYS[2]) or '0')
+local epoch = tonumber(ARGV[1])
+local now = redis.call('TIME')
+local ttl = tonumber(ARGV[3]) - (tonumber(now[1]) * 1000 + math.floor(tonumber(now[2]) / 1000))
+if previous >= epoch or ttl <= 0 then return 0 end
+redis.call('SET', KEYS[2], ARGV[1], 'PX', ARGV[4])
+redis.call('SET', KEYS[1], ARGV[2], 'PX', ttl)
+return 1`;
+const RELEASE = `-- artifact-tunnel-release-v1
+local serialized = redis.call('GET', KEYS[1])
+if not serialized then return 0 end
+local owner = cjson.decode(serialized)
+if owner.lease.epoch ~= tonumber(ARGV[1]) or owner.nodeId ~= ARGV[2] then return 0 end
+redis.call('DEL', KEYS[1])
+return 1`;
+const RENEW = `-- artifact-tunnel-renew-v1
+local serialized = redis.call('GET', KEYS[1])
+if not serialized then return 0 end
+local previous = cjson.decode(serialized)
+local proposed = cjson.decode(ARGV[1])
+if previous.nodeId ~= proposed.nodeId then return 0 end
+for _, key in ipairs({'sessionId', 'epoch', 'ownerId', 'projectId', 'environment', 'publicOrigin'}) do
+  if previous.lease[key] ~= proposed.lease[key] then return 0 end
+end
+if previous.lease.expiresAt > proposed.lease.expiresAt then return 0 end
+local now = redis.call('TIME')
+local ttl = proposed.lease.expiresAt - (tonumber(now[1]) * 1000 + math.floor(tonumber(now[2]) / 1000))
+if ttl <= 0 then return 0 end
+redis.call('SET', KEYS[1], ARGV[1], 'PX', ttl)
+redis.call('PEXPIRE', KEYS[2], ARGV[2])
+return 1`;
+/** Retain epochs longer than any lease, including after owner disconnect. Atlas
+ * must still authenticate every claim against the durable session's lifetime;
+ * Redis is a routing fence, not a substitute for session authorization. */
+export class RedisTunnelOwnership {
+    options;
+    namespace;
+    constructor(options) {
+        this.options = options;
+        this.namespace = redisNamespaceSchema.parse(options.namespace);
+    }
+    key(sessionId) {
+        return `artifact-tunnel:${this.namespace}:{${redisIdentifier.parse(sessionId)}}:owner`;
+    }
+    async claim(input, nodeId) {
+        const lease = redisLeaseSchema.parse(input);
+        redisIdentifier.parse(nodeId);
+        if (lease.environment !== this.namespace || lease.expiresAt <= Date.now() || lease.expiresAt - Date.now() > MAX_LEASE_MS)
+            throw new Error('Invalid tunnel lease environment or expiry');
+        const key = this.key(lease.sessionId);
+        return await this.options.command.eval(CLAIM, 2, key, `${key}:epoch`, lease.epoch, JSON.stringify({ nodeId, lease }), lease.expiresAt, EPOCH_RETENTION_MS) === 1;
+    }
+    async read(sessionId) {
+        const value = await this.options.command.get(this.key(sessionId));
+        if (!value)
+            return null;
+        if (Buffer.byteLength(value) > 8192)
+            throw new Error('Invalid stored tunnel ownership');
+        const owner = ownershipSchema.parse(JSON.parse(value));
+        if (owner.lease.environment !== this.namespace || owner.lease.sessionId !== sessionId)
+            throw new Error('Mismatched tunnel ownership');
+        return owner.lease.expiresAt > Date.now() ? owner : null;
+    }
+    async lookup(sessionId) {
+        const owner = await this.read(sessionId);
+        return owner ? { nodeId: owner.nodeId, epoch: owner.lease.epoch, expiresAt: owner.lease.expiresAt } : null;
+    }
+    async resolveLease(sessionId) { return (await this.read(sessionId))?.lease ?? null; }
+    /** Call only after Atlas has authorized and renewed the backing session. */
+    async renew(input, nodeId) {
+        const lease = redisLeaseSchema.parse(input);
+        redisIdentifier.parse(nodeId);
+        if (lease.environment !== this.namespace || lease.expiresAt <= Date.now() || lease.expiresAt - Date.now() > MAX_LEASE_MS)
+            throw new Error('Invalid tunnel lease renewal');
+        const key = this.key(lease.sessionId);
+        return await this.options.command.eval(RENEW, 2, key, `${key}:epoch`, JSON.stringify({ nodeId, lease }), EPOCH_RETENTION_MS) === 1;
+    }
+    async release(sessionId, epoch, nodeId) {
+        redisIdentifier.parse(nodeId);
+        if (!Number.isSafeInteger(epoch) || epoch < 1)
+            throw new Error('Invalid tunnel epoch');
+        await this.options.command.eval(RELEASE, 1, this.key(sessionId), epoch, nodeId);
+    }
+}

package/dist/tunnel/redis-socket.d.ts

@@ -0,0 +1,13 @@
+import { EventEmitter } from 'node:events';
+import type { TunnelSocket } from './transport.js';
+export declare class RelaySocket extends EventEmitter implements TunnelSocket {
+    private readonly transmit;
+    private readonly disconnect;
+    readyState: number;
+    bufferedAmount: number;
+    private sending;
+    constructor(transmit: (data: string) => Promise<void>, disconnect: () => void);
+    send(data: string, callback: (error?: Error) => void): void;
+    terminate(): void;
+    finish(): void;
+}

package/dist/tunnel/redis-socket.js

@@ -0,0 +1,48 @@
+import { EventEmitter } from 'node:events';
+import { DEFAULT_TUNNEL_LIMITS, parseTunnelFrame } from './protocol.js';
+export class RelaySocket extends EventEmitter {
+    transmit;
+    disconnect;
+    readyState = 0;
+    bufferedAmount = 0;
+    sending = Promise.resolve();
+    constructor(transmit, disconnect) {
+        super();
+        this.transmit = transmit;
+        this.disconnect = disconnect;
+    }
+    send(data, callback) {
+        if (this.readyState !== 1) {
+            callback(new Error('Tunnel disconnected'));
+            return;
+        }
+        const bytes = Buffer.byteLength(data);
+        if (bytes > DEFAULT_TUNNEL_LIMITS.maxFrameBytes || this.bufferedAmount + bytes > DEFAULT_TUNNEL_LIMITS.maxBufferedBytes) {
+            this.terminate();
+            callback(new Error('Tunnel relay send limit exceeded'));
+            return;
+        }
+        this.bufferedAmount += bytes;
+        this.sending = this.sending.then(async () => {
+            if (this.readyState !== 1)
+                throw new Error('Tunnel disconnected');
+            parseTunnelFrame(data);
+            await this.transmit(data);
+        }).then(() => callback(), (error) => {
+            this.terminate();
+            callback(error instanceof Error ? error : new Error('Tunnel relay failed'));
+        }).finally(() => { this.bufferedAmount -= bytes; });
+    }
+    terminate() {
+        if (this.readyState === 3)
+            return;
+        this.finish();
+        this.disconnect();
+    }
+    finish() {
+        if (this.readyState === 3)
+            return;
+        this.readyState = 3;
+        this.emit('close', 1006, Buffer.alloc(0));
+    }
+}

package/dist/tunnel/redis-types.d.ts

@@ -0,0 +1,70 @@
+import type { EventEmitter } from 'node:events';
+import { z } from 'zod';
+import type { TunnelLease } from './broker.js';
+import type { TunnelSocket } from './transport.js';
+import { type RedisTunnelOwnership } from './redis-ownership.js';
+import type { RelaySocket } from './redis-socket.js';
+export interface RedisTunnelPublisher {
+    readonly options: {
+        enableOfflineQueue?: boolean;
+        autoResendUnfulfilledCommands?: boolean;
+        maxRetriesPerRequest?: number | null;
+    };
+    publish(channel: string, message: string): Promise<number>;
+}
+export interface RedisTunnelSubscriber extends EventEmitter {
+    subscribe(channel: string): Promise<unknown>;
+    unsubscribe(channel: string): Promise<unknown>;
+}
+export declare const envelopeSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        ready: "ready";
+        close: "close";
+        open: "open";
+        frame: "frame";
+        revoke: "revoke";
+        heartbeat: "heartbeat";
+    }>;
+    destination: z.ZodEnum<{
+        owner: "owner";
+        requester: "requester";
+    }>;
+    source: z.ZodString;
+    connection: z.ZodString;
+    sessionId: z.ZodString;
+    epoch: z.ZodNumber;
+    frame: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type Envelope = z.infer<typeof envelopeSchema>;
+export type Remote = {
+    nodeId: string;
+    connection: string;
+    lastSeen: number;
+};
+export type Attached = {
+    lease: TunnelLease;
+    socket: TunnelSocket;
+    remotes: Map<string, Remote>;
+    streams: Map<string, Remote>;
+    timer: NodeJS.Timeout;
+    queuedBytes: number;
+    receiving: Promise<void>;
+    stopped: boolean;
+};
+export type Connected = {
+    lease: TunnelLease;
+    ownerNode: string;
+    socket: RelaySocket;
+    timer: NodeJS.Timeout;
+    heartbeat: NodeJS.Timeout;
+    resolve: (socket: TunnelSocket) => void;
+    reject: (error: Error) => void;
+};
+export interface RedisTunnelRelayOptions {
+    nodeId: string;
+    namespace: string;
+    ownership: RedisTunnelOwnership;
+    publisher: RedisTunnelPublisher;
+    subscriber: RedisTunnelSubscriber;
+    connectTimeoutMs?: number;
+}

package/dist/tunnel/redis-types.js

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import { DEFAULT_TUNNEL_LIMITS } from './protocol.js';
+import { redisIdentifier as identifier } from './redis-ownership.js';
+export const envelopeSchema = z.object({
+    type: z.enum(['open', 'ready', 'frame', 'close', 'revoke', 'heartbeat']),
+    destination: z.enum(['owner', 'requester']), source: identifier, connection: identifier,
+    sessionId: identifier, epoch: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    frame: z.string().max(DEFAULT_TUNNEL_LIMITS.maxFrameBytes).optional(),
+}).strict().refine((message) => (message.type === 'frame') === (message.frame !== undefined));

package/dist/tunnel/redis.d.ts

@@ -0,0 +1,53 @@
+import type { TunnelLease } from './broker.js';
+import type { TunnelRelay, TunnelSocket } from './transport.js';
+import { type RedisTunnelRelayOptions } from './redis-types.js';
+export { RedisTunnelOwnership } from './redis-ownership.js';
+export type { RedisTunnelCommands } from './redis-ownership.js';
+export type { RedisTunnelPublisher, RedisTunnelSubscriber, RedisTunnelRelayOptions } from './redis-types.js';
+/** Internal Redis channels contain authorized application traffic. Deploy them
+ * on the environment's private, authenticated Redis and disable command replay. */
+export declare class RedisTunnelRelay implements TunnelRelay {
+    private readonly options;
+    private started;
+    private closed;
+    private readonly attached;
+    private readonly connected;
+    private publishing;
+    private receiving;
+    private outgoingBytes;
+    private incomingBytes;
+    private generation;
+    private starting?;
+    constructor(options: RedisTunnelRelayOptions);
+    private channel;
+    private assertStarted;
+    isReady(): boolean;
+    start(): Promise<void>;
+    private subscribe;
+    private removeListeners;
+    private readonly onRedisFailure;
+    /**
+     * 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.
+     */
+    private readonly onRelayOverload;
+    private readonly onMessage;
+    private publish;
+    private envelope;
+    private current;
+    private verifiedLease;
+    attach(input: TunnelLease, socket: TunnelSocket): Promise<void>;
+    private attachOwned;
+    connect(input: TunnelLease): Promise<TunnelSocket>;
+    private receive;
+    private toRequester;
+    private toDeveloper;
+    private writeDeveloper;
+    private fromDeveloper;
+    private closeRemote;
+    private closeOwner;
+    private closeConnection;
+    disconnect(sessionId: string): void;
+    close(): Promise<void>;
+}