Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
18.0 KB
Raw Blame
/**
 * ORSEAL01: seals a byte stream to the omnirush.ai archive key (X25519 +
 * HKDF-SHA256 + AES-256-GCM in authenticated frames). The format, the key id
 * and the decoder's error rules are normative in
 * docs/omnirush-project-archive.md section 6 of the backend repository; the
 * shared vectors are in __fixtures__/orseal_vectors.json.
 */
import {
  createCipheriv,
  createDecipheriv,
  createHash,
  createPrivateKey,
  createPublicKey,
  diffieHellman,
  generateKeyPairSync,
  hkdfSync,
  randomBytes,
  type Hash,
  type KeyObject,
} from "node:crypto";
import { Transform, type TransformCallback } from "node:stream";

export const SEAL_MAGIC = Buffer.from("ORSEAL01", "ascii");
export const SEAL_ALG = "X25519-HKDF-SHA256-A256GCM";
export const SEAL_CONTENT = "tar+zstd";
export type SealContent = typeof SEAL_CONTENT | "zip";
/** The only chunk size production writers use. */
export const SEAL_CHUNK = 1 << 20;
export const SEAL_MIN_CHUNK = 16;
export const SEAL_MAX_CHUNK = 1 << 24;
export const SEAL_MAX_HEADER_LEN = 4096;
const TAG_LEN = 16;
const MAX_FRAMES = 2 ** 32;
const HKDF_INFO = Buffer.from("omnirush-seal-v1", "ascii");
const HEADER_KEYS = new Set(["alg", "chunk", "content", "epk", "kid", "salt", "v"]);
// DER wrappers that turn a raw 32-byte X25519 key into PKCS#8 / SPKI for Node's key objects.
const PKCS8_X25519_PREFIX = Buffer.from("302e020100300506032b656e04220420", "hex");
const SPKI_X25519_PREFIX = Buffer.from("302a300506032b656e032100", "hex");

export type SealErrorCode =
  | "bad_magic"
  | "bad_header"
  | "unsupported_version"
  | "unknown_kid"
  | "bad_frame_length"
  | "tag_mismatch"
  | "truncated"
  | "frame_after_final";

export class SealError extends Error {
  constructor(readonly code: SealErrorCode) {
    super(code);
    this.name = "SealError";
  }
}

function raw32(bytes: Uint8Array, what: string): Buffer {
  if (bytes.length !== 32) throw new TypeError(`${what} must be 32 bytes`);
  return Buffer.from(bytes);
}

export function x25519PrivateKey(raw: Uint8Array): KeyObject {
  return createPrivateKey({ key: Buffer.concat([PKCS8_X25519_PREFIX, raw32(raw, "X25519 private key")]), format: "der", type: "pkcs8" });
}

export function x25519PublicKey(raw: Uint8Array): KeyObject {
  return createPublicKey({ key: Buffer.concat([SPKI_X25519_PREFIX, raw32(raw, "X25519 public key")]), format: "der", type: "spki" });
}

/** The raw 32-byte public key of an X25519 private or public key object. */
export function x25519PublicRaw(key: KeyObject): Buffer {
  const publicKey = key.type === "private" ? createPublicKey(key) : key;
  const der = publicKey.export({ format: "der", type: "spki" });
  return Buffer.from(der.subarray(der.length - 32));
}

/** kid: the first 16 lowercase hex characters of SHA-256(raw public key). */
export function sealKid(publicRaw: Uint8Array): string {
  return createHash("sha256").update(raw32(publicRaw, "X25519 public key")).digest("hex").slice(0, 16);
}

function deriveKey(shared: Buffer, salt: Buffer, epk: Buffer, serverPublic: Buffer): Buffer {
  return Buffer.from(hkdfSync("sha256", shared, salt, Buffer.concat([HKDF_INFO, epk, serverPublic]), 32));
}

function agree(privateKey: KeyObject, publicKey: KeyObject): Buffer | null {
  let shared: Buffer;
  try {
    shared = diffieHellman({ privateKey, publicKey });
  } catch {
    return null;
  }
  // A low-order point yields an all-zero secret; Node already throws on it,
  // the explicit check keeps that guarantee independent of the runtime.
  return shared.every((byte) => byte === 0) ? null : shared;
}

function frameNonce(index: number): Buffer {
  const nonce = Buffer.alloc(12);
  nonce.writeBigUInt64BE(BigInt(index), 4);
  return nonce;
}

function frameAad(headerHash: Buffer, index: number, final: boolean): Buffer {
  const aad = Buffer.alloc(41);
  headerHash.copy(aad, 0);
  aad.writeBigUInt64BE(BigInt(index), 32);
  aad[40] = final ? 1 : 0;
  return aad;
}

/** One frame as pieces (length prefix, ciphertext, tag): no second copy of the ciphertext is made. */
function encryptFrame(key: Buffer, headerHash: Buffer, index: number, final: boolean, plaintext: Buffer): Buffer[] {
  const cipher = createCipheriv("aes-256-gcm", key, frameNonce(index));
  cipher.setAAD(frameAad(headerHash, index, final));
  const length = Buffer.allocUnsafe(4);
  length.writeUInt32BE(plaintext.length + TAG_LEN, 0);
  const body = cipher.update(plaintext);
  const tail = cipher.final();
  const pieces = [length, body];
  if (tail.length > 0) pieces.push(tail);
  pieces.push(cipher.getAuthTag());
  return pieces;
}

function decryptFrame(key: Buffer, headerHash: Buffer, index: number, final: boolean, frame: Buffer): Buffer | null {
  try {
    const decipher = createDecipheriv("aes-256-gcm", key, frameNonce(index));
    decipher.setAAD(frameAad(headerHash, index, final));
    decipher.setAuthTag(frame.subarray(frame.length - TAG_LEN));
    const head = decipher.update(frame.subarray(0, frame.length - TAG_LEN));
    const tail = decipher.final();
    return tail.length === 0 ? head : Buffer.concat([head, tail]);
  } catch {
    return null;
  }
}

export type SealOptions = {
  /** Native Claude checkpoints preserve their exact ZIP bytes; project archives retain tar+zstd. */
  content?: SealContent;
  /** The recipient's raw 32-byte X25519 public key (GET /omnirush/archives/key). */
  publicKey: Uint8Array;
  /** Plaintext bytes per frame. Production MUST leave the default (1 MiB); the vectors use 16. */
  chunk?: number;
  /**
   * TEST VECTORS ONLY. Fixes the ephemeral private key and the salt so a seal
   * reproduces orseal_vectors.json byte for byte. Production code never sets
   * it: every archive gets a fresh ephemeral key and salt from the CSPRNG.
   */
  testOnlyFixedSecrets?: { ephemeralPrivateKey: Uint8Array; salt: Uint8Array };
};

export type SealResult = { size: number; sha256: string };

/**
 * The ORSEAL01 framing core, shared by SealStream and sealBuffer. It holds at
 * most one chunk of plaintext: a full chunk becomes a non-final frame only
 * once more input arrives, and whatever is held at the end (possibly a full
 * chunk, or nothing) becomes the final frame. It counts and hashes its own
 * output, which the create request needs.
 */
class FrameSealer {
  readonly kid: string;
  private readonly key: Buffer;
  private readonly headerHash: Buffer;
  private readonly prefix: Buffer;
  private readonly chunk: number;
  private readonly pending: Buffer;
  private pendingLength = 0;
  private index = 0;
  private started = false;
  private readonly outputHash: Hash = createHash("sha256");
  private outputBytes = 0;
  private sealed: SealResult | null = null;

  constructor(options: SealOptions) {
    const content = options.content ?? SEAL_CONTENT;
    if (content !== SEAL_CONTENT && content !== "zip") throw new TypeError("invalid seal content");
    const chunk = options.chunk ?? SEAL_CHUNK;
    if (!Number.isInteger(chunk) || chunk < SEAL_MIN_CHUNK || chunk > SEAL_MAX_CHUNK) throw new RangeError("invalid seal chunk size");
    const serverPublicRaw = raw32(options.publicKey, "X25519 public key");
    const ephemeral = options.testOnlyFixedSecrets
      ? x25519PrivateKey(options.testOnlyFixedSecrets.ephemeralPrivateKey)
      : generateKeyPairSync("x25519").privateKey;
    const salt = options.testOnlyFixedSecrets ? raw32(options.testOnlyFixedSecrets.salt, "salt") : randomBytes(32);
    const epk = x25519PublicRaw(ephemeral);
    const shared = agree(ephemeral, x25519PublicKey(serverPublicRaw));
    if (!shared) throw new RangeError("the archive public key is not a valid X25519 point");
    this.kid = sealKid(serverPublicRaw);
    this.chunk = chunk;
    this.key = deriveKey(shared, salt, epk, serverPublicRaw);
    // Key order alg, chunk, content, epk, kid, salt, v: sorted, as the format requires.
    const header = Buffer.from(JSON.stringify({
      alg: SEAL_ALG,
      chunk,
      content,
      epk: epk.toString("base64"),
      kid: this.kid,
      salt: salt.toString("base64"),
      v: 1,
    }), "utf8");
    const length = Buffer.alloc(4);
    length.writeUInt32BE(header.length, 0);
    this.prefix = Buffer.concat([SEAL_MAGIC, length, header]);
    this.headerHash = createHash("sha256").update(this.prefix).digest();
    this.pending = Buffer.allocUnsafe(chunk);
  }

  get result(): SealResult | null {
    return this.sealed;
  }

  private emit(bytes: Buffer, out: (bytes: Buffer) => void): void {
    this.outputHash.update(bytes);
    this.outputBytes += bytes.length;
    out(bytes);
  }

  private start(out: (bytes: Buffer) => void): void {
    if (this.started) return;
    this.started = true;
    this.emit(this.prefix, out);
  }

  private frame(final: boolean, out: (bytes: Buffer) => void): void {
    if (this.index >= MAX_FRAMES) throw new RangeError("too many seal frames");
    for (const piece of encryptFrame(this.key, this.headerHash, this.index, final, this.pending.subarray(0, this.pendingLength))) this.emit(piece, out);
    this.index += 1;
    this.pendingLength = 0;
  }

  update(bytes: Buffer, out: (bytes: Buffer) => void): void {
    if (this.sealed) throw new Error("the seal is already finished");
    this.start(out);
    let offset = 0;
    while (offset < bytes.length) {
      if (this.pendingLength === this.chunk) this.frame(false, out);
      const take = Math.min(bytes.length - offset, this.chunk - this.pendingLength);
      bytes.copy(this.pending, this.pendingLength, offset, offset + take);
      this.pendingLength += take;
      offset += take;
    }
  }

  finish(out: (bytes: Buffer) => void): SealResult {
    if (this.sealed) throw new Error("the seal is already finished");
    this.start(out);
    this.frame(true, out);
    this.sealed = { size: this.outputBytes, sha256: this.outputHash.digest("hex") };
    return this.sealed;
  }
}

/** Streaming ORSEAL01 sealer (section 6.6); memory is one chunk plus stream buffers. */
export class SealStream extends Transform {
  private readonly sealer: FrameSealer;

  constructor(options: SealOptions) {
    super();
    this.sealer = new FrameSealer(options);
  }

  get kid(): string {
    return this.sealer.kid;
  }

  /** Ciphertext size and SHA-256; available once the stream has finished. */
  result(): SealResult {
    const result = this.sealer.result;
    if (!result) throw new Error("the seal stream has not finished");
    return result;
  }

  override _transform(data: Buffer | string, encoding: BufferEncoding, callback: TransformCallback): void {
    try {
      this.sealer.update(typeof data === "string" ? Buffer.from(data, encoding) : data, (bytes) => this.push(bytes));
      callback();
    } catch (error) {
      callback(error instanceof Error ? error : new Error(String(error)));
    }
  }

  override _flush(callback: TransformCallback): void {
    try {
      this.sealer.finish((bytes) => this.push(bytes));
      callback();
    } catch (error) {
      callback(error instanceof Error ? error : new Error(String(error)));
    }
  }
}

/** Seals a buffer in one call (tests and small payloads). */
export function sealBuffer(plaintext: Uint8Array, options: SealOptions): { sealed: Buffer; kid: string } & SealResult {
  const sealer = new FrameSealer(options);
  const out: Buffer[] = [];
  const push = (bytes: Buffer) => out.push(bytes);
  sealer.update(Buffer.from(plaintext.buffer, plaintext.byteOffset, plaintext.byteLength), push);
  const result = sealer.finish(push);
  return { sealed: Buffer.concat(out), kid: sealer.kid, ...result };
}

// --- opening -------------------------------------------------------------------

export type SealKey = { kid: string; privateKey: KeyObject; publicRaw: Buffer };
/** kid -> key, every configured private key (current first). */
export type SealKeyring = Map<string, SealKey>;

export function sealKeyring(privateKeys: readonly Uint8Array[]): SealKeyring {
  const keyring: SealKeyring = new Map();
  for (const raw of privateKeys) {
    const privateKey = x25519PrivateKey(raw);
    const publicRaw = x25519PublicRaw(privateKey);
    const kid = sealKid(publicRaw);
    if (!keyring.has(kid)) keyring.set(kid, { kid, privateKey, publicRaw });
  }
  return keyring;
}

/** Exact reads plus a one-byte look-ahead over an async byte source. */
class ByteReader {
  private readonly iterator: AsyncIterator<Uint8Array>;
  private buffered: Buffer[] = [];
  private length = 0;
  private done = false;

  constructor(source: AsyncIterable<Uint8Array>) {
    this.iterator = source[Symbol.asyncIterator]();
  }

  private async fill(wanted: number): Promise<void> {
    while (this.length < wanted && !this.done) {
      const next = await this.iterator.next();
      if (next.done) {
        this.done = true;
        break;
      }
      if (next.value.length === 0) continue;
      const piece = Buffer.from(next.value.buffer, next.value.byteOffset, next.value.byteLength);
      this.buffered.push(piece);
      this.length += piece.length;
    }
  }

  /** Up to `count` bytes; fewer only at the end of the source. */
  async read(count: number): Promise<Buffer> {
    await this.fill(count);
    const take = Math.min(count, this.length);
    const joined = this.buffered.length === 1 ? this.buffered[0]! : Buffer.concat(this.buffered, this.length);
    const out = Buffer.from(joined.subarray(0, take));
    const rest = joined.subarray(take);
    this.buffered = rest.length > 0 ? [rest] : [];
    this.length = rest.length;
    return out;
  }

  async more(): Promise<boolean> {
    await this.fill(1);
    return this.length > 0;
  }

  async close(): Promise<void> {
    await this.iterator.return?.();
  }
}

const UTF8 = new TextDecoder("utf-8", { fatal: true });
const B64_32 = /^[A-Za-z0-9+/]{43}=$/;

function canonicalBase64Of32(value: unknown): Buffer {
  if (typeof value !== "string" || !B64_32.test(value)) throw new SealError("bad_header");
  const raw = Buffer.from(value, "base64");
  if (raw.length !== 32 || raw.toString("base64") !== value) throw new SealError("bad_header");
  return raw;
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

type OpenedHeader = { chunk: number; key: Buffer; headerHash: Buffer; kid: string };

async function openHeader(reader: ByteReader, keyring: SealKeyring, expectedContent: SealContent): Promise<OpenedHeader> {
  const magic = await reader.read(8);
  if (!magic.equals(SEAL_MAGIC)) throw new SealError("bad_magic");
  const rawLength = await reader.read(4);
  if (rawLength.length < 4) throw new SealError("truncated");
  const length = rawLength.readUInt32BE(0);
  if (length === 0 || length > SEAL_MAX_HEADER_LEN) throw new SealError("bad_header");
  const head = await reader.read(length);
  if (head.length < length) throw new SealError("truncated");
  let header: unknown;
  try {
    header = JSON.parse(UTF8.decode(head));
  } catch {
    throw new SealError("bad_header");
  }
  if (!isRecord(header)) throw new SealError("bad_header");
  const version = header.v;
  if (typeof version !== "number" || !Number.isInteger(version)) throw new SealError("bad_header");
  if (version !== 1) throw new SealError("unsupported_version");
  const keys = Object.keys(header);
  const { chunk, kid } = header;
  if (
    keys.length !== HEADER_KEYS.size
    || !keys.every((key) => HEADER_KEYS.has(key))
    || header.alg !== SEAL_ALG
    || header.content !== expectedContent
    || typeof chunk !== "number"
    || !Number.isInteger(chunk)
    || chunk < SEAL_MIN_CHUNK
    || chunk > SEAL_MAX_CHUNK
    || typeof kid !== "string"
    || !/^[0-9a-f]{16}$/.test(kid)
  ) {
    throw new SealError("bad_header");
  }
  const epk = canonicalBase64Of32(header.epk);
  const salt = canonicalBase64Of32(header.salt);
  const recipient = keyring.get(kid);
  if (!recipient) throw new SealError("unknown_kid");
  let ephemeralPublic: KeyObject;
  try {
    ephemeralPublic = x25519PublicKey(epk);
  } catch {
    throw new SealError("bad_header");
  }
  const shared = agree(recipient.privateKey, ephemeralPublic);
  if (!shared) throw new SealError("bad_header");
  return {
    chunk,
    kid,
    key: deriveKey(shared, salt, epk, recipient.publicRaw),
    headerHash: createHash("sha256").update(Buffer.concat([magic, rawLength, head])).digest(),
  };
}

/**
 * Opens an ORSEAL01 stream frame by frame (section 6.7). The plaintext is
 * authentic only once the generator returns without throwing: a failing
 * stream can yield a verified prefix first, and a caller must discard
 * everything it received when a SealError is thrown.
 */
export async function* openSealed(source: AsyncIterable<Uint8Array>, keyring: SealKeyring, options: {expectedContent?: SealContent} = {}): AsyncGenerator<Buffer, { kid: string }> {
  const reader = new ByteReader(source);
  try {
    const { chunk, key, headerHash, kid } = await openHeader(reader, keyring, options.expectedContent ?? SEAL_CONTENT);
    for (let index = 0; ; index += 1) {
      const rawLength = await reader.read(4);
      if (rawLength.length < 4) throw new SealError("truncated");
      const length = rawLength.readUInt32BE(0);
      if (length < TAG_LEN || length > chunk + TAG_LEN) throw new SealError("bad_frame_length");
      const frame = await reader.read(length);
      if (frame.length < length) throw new SealError("truncated");
      const more = await reader.more();
      const full = length === chunk + TAG_LEN;
      const final = !full || !more;
      const plaintext = decryptFrame(key, headerHash, index, final, frame);
      if (!plaintext) {
        if (full && decryptFrame(key, headerHash, index, !final, frame)) {
          throw new SealError(final ? "truncated" : "frame_after_final");
        }
        throw new SealError("tag_mismatch");
      }
      yield plaintext;
      if (final) {
        if (more) throw new SealError("frame_after_final");
        return { kid };
      }
    }
  } finally {
    await reader.close();
  }
}

async function* once(bytes: Uint8Array): AsyncGenerator<Uint8Array> {
  yield bytes;
}

/** Opens a whole sealed buffer; throws SealError on any failure. */
export async function openSealedBuffer(sealed: Uint8Array, keyring: SealKeyring, options: {expectedContent?: SealContent} = {}): Promise<Buffer> {
  const pieces: Buffer[] = [];
  for await (const piece of openSealed(once(sealed), keyring, options)) pieces.push(piece);
  return Buffer.concat(pieces);
}