@sequenceholdings/artifact-studio 0.2.6 → 0.3.1

package/dist/tunnel/redis-auth.js

@@ -0,0 +1,92 @@
+import { createHmac, hkdfSync, timingSafeEqual } from 'node:crypto';
+import { z } from 'zod';
+import { DEFAULT_TUNNEL_LIMITS } from './protocol.js';
+import { envelopeSchema } from './redis-types.js';
+const WIRE_VERSION = 'v1';
+/** Frames older (or further in the future) than this are replays or come from a stalled node. */
+export const RELAY_FRAME_MAX_AGE_MS = 30_000;
+/** An envelope quotes a frame as a JSON string: at most double its size, plus fixed fields and the MAC. */
+export const RELAY_MESSAGE_MAX_BYTES = DEFAULT_TUNNEL_LIMITS.maxFrameBytes * 2 + 4096;
+const PEER_RETENTION_MS = RELAY_FRAME_MAX_AGE_MS * 4;
+const MAX_TRACKED_PEERS = 1024;
+const wireSchema = z.object({
+    sequence: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    sentAt: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    envelope: envelopeSchema,
+}).strict();
+/**
+ * The relay's frame key: an HKDF-SHA256 subkey of the gateway-only session key, bound to one
+ * environment. Atlas and every other Redis client lack that key, so they cannot forge frames, and
+ * the session key itself is never used as a MAC key for anything but cookies.
+ */
+export function deriveRelayFrameKey({ secret, namespace }) {
+    if (Buffer.byteLength(secret) < 32)
+        throw new Error('Tunnel relay authentication requires a gateway secret of at least 32 bytes');
+    return Buffer.from(hkdfSync('sha256', secret, 'atlas-artifact-next', `artifact-next/tunnel-relay/v1:${namespace}`, 32));
+}
+function mac({ key, channel, body }) {
+    return createHmac('sha256', key).update(`${WIRE_VERSION}\n${channel}\n${body}`).digest();
+}
+/**
+ * Authenticates relay messages: the MAC binds the destination channel, so a captured frame cannot be
+ * redirected to another node, and each source's strictly increasing sequence plus a freshness window
+ * rejects replays. A single publisher connection per node keeps Redis delivery in sequence order.
+ */
+export class RelayFrameAuthenticator {
+    key;
+    now;
+    sequence = 0;
+    peers = new Map();
+    constructor(key, now = Date.now) {
+        this.key = key;
+        this.now = now;
+        if (key.length !== 32)
+            throw new Error('Invalid tunnel relay frame key');
+    }
+    seal({ channel, envelope }) {
+        const body = JSON.stringify({ sequence: ++this.sequence, sentAt: this.now(), envelope });
+        return `${WIRE_VERSION}.${mac({ key: this.key, channel, body }).toString('base64url')}.${body}`;
+    }
+    /** Null for any frame that is oversized, unauthenticated, stale, replayed or malformed. */
+    open({ channel, message }) {
+        if (Buffer.byteLength(message) > RELAY_MESSAGE_MAX_BYTES || !message.startsWith(`${WIRE_VERSION}.`))
+            return null;
+        const separator = message.indexOf('.', WIRE_VERSION.length + 1);
+        if (separator < 0)
+            return null;
+        const signature = message.slice(WIRE_VERSION.length + 1, separator), body = message.slice(separator + 1);
+        if (!/^[A-Za-z0-9_-]{43}$/.test(signature))
+            return null;
+        const expected = mac({ key: this.key, channel, body }), actual = Buffer.from(signature, 'base64url');
+        if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
+            return null;
+        let wire;
+        try {
+            wire = wireSchema.parse(JSON.parse(body));
+        }
+        catch {
+            return null;
+        }
+        const now = this.now();
+        if (Math.abs(now - wire.sentAt) > RELAY_FRAME_MAX_AGE_MS)
+            return null;
+        const source = wire.envelope.source;
+        const peer = this.peers.get(source);
+        if (peer && wire.sequence <= peer.sequence)
+            return null;
+        this.peers.delete(source);
+        this.peers.set(source, { sequence: wire.sequence, seenAt: now });
+        this.forgetIdlePeers(now);
+        return wire.envelope;
+    }
+    /** Forgotten peers can only send frames newer than the freshness window, which rejects replays. */
+    forgetIdlePeers(now) {
+        if (this.peers.size <= MAX_TRACKED_PEERS)
+            return;
+        for (const [source, peer] of this.peers) {
+            if (now - peer.seenAt <= PEER_RETENTION_MS)
+                break;
+            this.peers.delete(source);
+        }
+    }
+}

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

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import type { TunnelLease, TunnelOwner, TunnelOwnershipStore } from './broker.js';
+export interface RedisTunnelCommands {
+    get(key: string): Promise<string | null>;
+    eval(script: string, numberOfKeys: number, ...arguments_: (string | number)[]): Promise<unknown>;
+}
+export declare const redisIdentifier: z.ZodString;
+/** 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 declare const redisNamespaceSchema: z.ZodString;
+export declare const redisLeaseSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    epoch: z.ZodNumber;
+    ownerId: z.ZodString;
+    projectId: z.ZodString;
+    environment: z.ZodString;
+    expiresAt: z.ZodNumber;
+    publicOrigin: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strict>;
+/** 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 declare class RedisTunnelOwnership implements TunnelOwnershipStore {
+    private readonly options;
+    readonly namespace: string;
+    constructor(options: {
+        command: RedisTunnelCommands;
+        namespace: string;
+    });
+    private key;
+    claim(input: TunnelLease, nodeId: string): Promise<boolean>;
+    private read;
+    lookup(sessionId: string): Promise<TunnelOwner | null>;
+    resolveLease(sessionId: string): Promise<TunnelLease | null>;
+    /** Call only after Atlas has authorized and renewed the backing session. */
+    renew(input: TunnelLease, nodeId: string): Promise<boolean>;
+    release(sessionId: string, epoch: number, nodeId: string): Promise<void>;
+}

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,75 @@
+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;
+    /** Gateway-only key material shared by every replica (the session key). Frames are authenticated
+     * with an HKDF subkey of it; the value itself never leaves the process. */
+    secret: string;
+    /** Called for each relay message dropped as unauthenticated, stale, replayed or oversized. */
+    onRejectedFrame?: () => void;
+}

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,56 @@
+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.
+ * Every message is authenticated with a gateway-only key: other Redis clients
+ * can neither inject, redirect nor replay tunnel frames. */
+export declare class RedisTunnelRelay implements TunnelRelay {
+    private readonly options;
+    private started;
+    private closed;
+    private readonly attached;
+    private readonly connected;
+    private readonly frames;
+    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>;
+}