Skip to content

A spy satellite simulator in your browser, except the data is real. Live open source spatial intelligence on a photorealistic 3D globe.

8.0 KB
Raw Blame
/**
 * Byte-level primitives for the compact share-view format: base64url text,
 * protobuf-style varints, and a tag-length-value reader and writer.
 *
 * Pure: no DOM, no Cesium, no platform buffers. Every integrity failure is a
 * {@link ShareWireError} with a stable `reason`, so the view codec can turn it
 * into a rejected link instead of an exception at app start.
 */

/** Wire types. Field numbers and their wire types are permanent. */
export const WIRE_VARINT = 0;
export const WIRE_FIXED64 = 1;
export const WIRE_LEN = 2;
export const WIRE_FIXED32 = 5;

/** Field numbers stay inside protobuf's range so tags fit in five bytes. */
export const MAX_FIELD_NUMBER = 2 ** 29 - 1;
const MAX_VARINT_BYTES = 8; // 56 bits covers every safe integer.

/** A malformed or out-of-bounds payload. `reason` is a stable code. */
export class ShareWireError extends Error {
  constructor(reason, detail = '') {
    super(detail ? `${reason}: ${detail}` : reason);
    this.name = 'ShareWireError';
    this.reason = reason;
  }
}

const BASE64URL =
  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
const BASE64URL_INDEX = new Map(
  [...BASE64URL].map((char, index) => [char, index]),
);

/** Unpadded base64url text for `bytes`. */
export function encodeBase64Url(bytes) {
  let out = '';
  for (let i = 0; i < bytes.length; i += 3) {
    const a = bytes[i];
    const b = i + 1 < bytes.length ? bytes[i + 1] : 0;
    const c = i + 2 < bytes.length ? bytes[i + 2] : 0;
    const triple = (a << 16) | (b << 8) | c;
    out += BASE64URL[(triple >> 18) & 63] + BASE64URL[(triple >> 12) & 63];
    if (i + 1 < bytes.length) out += BASE64URL[(triple >> 6) & 63];
    if (i + 2 < bytes.length) out += BASE64URL[triple & 63];
  }
  return out;
}

/**
 * Bytes for unpadded base64url text. Rejects padding, foreign characters, an
 * impossible length and non-zero trailing bits, so every payload has exactly
 * one spelling.
 */
export function decodeBase64Url(text) {
  if (typeof text !== 'string' || text.length === 0)
    throw new ShareWireError('empty');
  if (text.length % 4 === 1) throw new ShareWireError('bad-base64');
  const bytes = new Uint8Array(Math.floor((text.length * 3) / 4));
  let buffer = 0;
  let bits = 0;
  let out = 0;
  for (const char of text) {
    const value = BASE64URL_INDEX.get(char);
    if (value === undefined) throw new ShareWireError('bad-base64');
    buffer = ((buffer << 6) | value) & 0xffffff;
    bits += 6;
    if (bits >= 8) {
      bits -= 8;
      bytes[out++] = (buffer >> bits) & 0xff;
    }
  }
  if (bits > 0 && (buffer & ((1 << bits) - 1)) !== 0)
    throw new ShareWireError('bad-base64', 'non-zero trailing bits');
  return bytes;
}

/**
 * CRC-8 (polynomial x⁸ + x² + x + 1, 0x07; initial value 0; no reflection;
 * no final XOR) of `bytes`. A degree-8 CRC detects every error burst of up to
 * 8 bits, so any one mistyped base64url character (6 bits) is caught.
 */
export function crc8(bytes) {
  let crc = 0;
  for (const byte of bytes) {
    crc ^= byte;
    for (let bit = 0; bit < 8; bit += 1)
      crc = crc & 0x80 ? ((crc << 1) ^ 0x07) & 0xff : (crc << 1) & 0xff;
  }
  return crc;
}

/** Map a signed integer onto the unsigned varint space (0,-1,1,-2 → 0,1,2,3). */
export function zigzag(value) {
  return value >= 0 ? value * 2 : -value * 2 - 1;
}

/** Inverse of {@link zigzag}. */
export function unzigzag(value) {
  return value % 2 === 0 ? value / 2 : -(value + 1) / 2;
}

/** Largest magnitude a zigzag field can carry without losing precision. */
export const MAX_ZIGZAG_MAGNITUDE = Math.floor(Number.MAX_SAFE_INTEGER / 2);

/** Append-only byte sink with protobuf-style field helpers. */
export class WireWriter {
  constructor() {
    this.bytes = [];
  }

  varint(value) {
    if (!Number.isSafeInteger(value) || value < 0)
      throw new RangeError(`varint out of range: ${value}`);
    let rest = value;
    while (rest >= 0x80) {
      this.bytes.push((rest % 0x80) | 0x80);
      rest = Math.floor(rest / 0x80);
    }
    this.bytes.push(rest);
    return this;
  }

  tag(field, wireType) {
    if (!Number.isInteger(field) || field < 1 || field > MAX_FIELD_NUMBER)
      throw new RangeError(`field number out of range: ${field}`);
    return this.varint(field * 8 + wireType);
  }

  uintField(field, value) {
    return this.tag(field, WIRE_VARINT).varint(value);
  }

  sintField(field, value) {
    if (!Number.isSafeInteger(value) || Math.abs(value) > MAX_ZIGZAG_MAGNITUDE)
      throw new RangeError(`signed value out of range: ${value}`);
    return this.tag(field, WIRE_VARINT).varint(zigzag(value));
  }

  bytesField(field, bytes) {
    this.tag(field, WIRE_LEN).varint(bytes.length);
    for (const byte of bytes) this.bytes.push(byte);
    return this;
  }

  /** ASCII-only text; every share-view string is drawn from ASCII grammars. */
  textField(field, text) {
    return this.bytesField(field, asciiBytes(text));
  }

  finish() {
    return Uint8Array.from(this.bytes);
  }
}

/** Printable-ASCII bytes for `text`; anything else is a programming error. */
export function asciiBytes(text) {
  const bytes = [];
  for (let i = 0; i < text.length; i += 1) {
    const code = text.charCodeAt(i);
    if (code < 0x20 || code > 0x7e)
      throw new RangeError('share-view text must be printable ASCII');
    bytes.push(code);
  }
  return bytes;
}

/** Printable-ASCII text from bytes; anything else is a malformed payload. */
export function asciiText(bytes) {
  let out = '';
  for (const byte of bytes) {
    if (byte < 0x20 || byte > 0x7e) throw new ShareWireError('bad-text');
    out += String.fromCharCode(byte);
  }
  return out;
}

/** Bounds-checked cursor over one message (or one packed blob). */
export class WireReader {
  constructor(bytes, start = 0, end = bytes.length) {
    this.bytes = bytes;
    this.pos = start;
    this.end = end;
  }

  get done() {
    return this.pos >= this.end;
  }

  /** One canonical varint no larger than Number.MAX_SAFE_INTEGER. */
  varint() {
    let value = 0;
    let scale = 1;
    for (let count = 0; count < MAX_VARINT_BYTES; count += 1) {
      if (this.pos >= this.end) throw new ShareWireError('truncated');
      const byte = this.bytes[this.pos++];
      value += (byte & 0x7f) * scale;
      if ((byte & 0x80) === 0) {
        // A zero final byte after a continuation is an overlong spelling.
        if (count > 0 && byte === 0)
          throw new ShareWireError('non-canonical-varint');
        if (!Number.isSafeInteger(value))
          throw new ShareWireError('varint-overflow');
        return value;
      }
      scale *= 0x80;
    }
    throw new ShareWireError('varint-overflow');
  }

  svarint() {
    return unzigzag(this.varint());
  }

  /** The next field's number and wire type, rejecting reserved wire types. */
  tag() {
    const key = this.varint();
    const field = Math.floor(key / 8);
    const wireType = key % 8;
    if (field < 1 || field > MAX_FIELD_NUMBER)
      throw new ShareWireError('bad-field-number');
    if (
      wireType !== WIRE_VARINT &&
      wireType !== WIRE_FIXED64 &&
      wireType !== WIRE_LEN &&
      wireType !== WIRE_FIXED32
    )
      throw new ShareWireError('bad-wire-type', String(wireType));
    return { field, wireType };
  }

  /** A length-delimited body as a sub-reader over the same bytes. */
  lengthDelimited() {
    const length = this.varint();
    if (length > this.end - this.pos)
      throw new ShareWireError('truncated', 'length exceeds payload');
    const reader = new WireReader(this.bytes, this.pos, this.pos + length);
    this.pos += length;
    return reader;
  }

  /** Remaining bytes of this reader as a fresh array. */
  rest() {
    const out = this.bytes.slice(this.pos, this.end);
    this.pos = this.end;
    return out;
  }

  /** Skip one value of `wireType`, so newer fields cost older decoders nothing. */
  skip(wireType) {
    if (wireType === WIRE_VARINT) this.varint();
    else if (wireType === WIRE_LEN) this.lengthDelimited();
    else {
      const size = wireType === WIRE_FIXED64 ? 8 : 4;
      if (size > this.end - this.pos) throw new ShareWireError('truncated');
      this.pos += size;
    }
  }
}