HTTP endpoints and webhooks with doPost

{
  "timeZone": "Etc/UTC",
  "runtimeVersion": "V8",
  "oauthScopes": [],
  "webapp": {
    "access": "ANYONE_ANONYMOUS",
    "executeAs": "USER_DEPLOYING"
  }
}

{
  "timeZone": "Etc/UTC",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request"
  ]
}

// Fictional event data, not a real tracker ID or personal information.
const SAMPLE_EVENT_PAYLOAD = Object.freeze({
  type: 'request.note',
  requestId: 'REQ-001',
  note: 'Check step-free access before Friday.',
});

openssl rand -hex 32

{"protocol":1,"ok":true,"service":"custom-event-receiver"}

curl -L \
  -H 'Content-Type: application/json' \
  -d '{"foo":"bar"}' \
  'https://script.google.com/macros/s/DEPLOYMENT_ID/exec'

// Install an identical copy in each independent project. No shared library is used.
const EVENT_PROTOCOL = Object.freeze({
  version: 1,
  maxBodyBytes: 2048,
  freshMs: 5 * 60 * 1000,
  futureMs: 30 * 1000,
  retentionMs: 24 * 60 * 60 * 1000,
  maxReceipts: 8,
  maxStoreBytes: 7000,
});

/** @param {unknown} value @param {string[]} keys */
function exactKeys_(value, keys) {
  return value !== null && typeof value === 'object' && !Array.isArray(value) &&
    Object.keys(value).length === keys.length &&
    keys.every(function (key) { return Object.prototype.hasOwnProperty.call(value, key); });
}

/** @param {string} text */
function utf8Length_(text) {
  return Utilities.newBlob(text).getBytes().length;
}

/** @param {string} text @param {number} maxBytes @returns {*} */
function parseBoundedJson_(text, maxBytes) {
  if (typeof text !== 'string' || text.length === 0 || text.length > maxBytes ||
      utf8Length_(text) > maxBytes) {
    throw new Error('JSON text is missing or exceeds its byte limit.');
  }
  try {
    return JSON.parse(text);
  } catch (error) {
    // Do not include a parser message that might quote the input.
    throw new Error('Invalid JSON text.');
  }
}

/** @param {*} event */
function validEventFields_(event) {
  if (event.version !== EVENT_PROTOCOL.version ||
      typeof event.eventId !== 'string' ||
      !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(event.eventId) ||
      !Number.isSafeInteger(event.issuedAt) || event.issuedAt <= 0 ||
      !exactKeys_(event.payload, ['type', 'requestId', 'note'])) {
    return false;
  }
  const payload = event.payload;
  return payload.type === 'request.note' && typeof payload.requestId === 'string' &&
    /^REQ-[0-9]{3}$/.test(payload.requestId) &&
    typeof payload.note === 'string' && payload.note.trim().length > 0 &&
    payload.note.length <= 120 && !/[\u0000-\u001f\u007f]/.test(payload.note) &&
    utf8Length_(payload.note) <= 240;
}

/** @param {string} body */
function readEnvelope_(body) {
  const event = parseBoundedJson_(body, EVENT_PROTOCOL.maxBodyBytes);
  if (!exactKeys_(event, ['version', 'eventId', 'issuedAt', 'payload', 'signature']) ||
      !validEventFields_(event) || typeof event.signature !== 'string' ||
      !/^[0-9a-f]{64}$/.test(event.signature)) {
    throw new Error('Invalid event envelope.');
  }
  return event;
}

/** @param {*} event */
function eventFields_(event) {
  return {
    version: event.version,
    eventId: event.eventId,
    issuedAt: event.issuedAt,
    payload: {
      type: event.payload.type,
      requestId: event.payload.requestId,
      note: event.payload.note,
    },
  };
}

/** @param {*} event */
function canonicalEvent_(event) {
  // No pretty printing, trailing newline, Unicode normalization, or key sorting.
  return JSON.stringify([
    'apps-script-custom-event', event.version, event.eventId, event.issuedAt,
    event.payload.type, event.payload.requestId, event.payload.note,
  ]);
}

function readSecret_() {
  const secret = PropertiesService.getScriptProperties().getProperty('EVENT_SECRET_HEX');
  if (typeof secret !== 'string' || !/^[0-9a-f]{64}$/.test(secret)) {
    throw new Error('Set EVENT_SECRET_HEX to the generated 64-character lowercase hex value.');
  }
  return secret;
}

/** @param {*} event @param {string} secret */
function signEvent_(event, secret) {
  // The 64 hex characters are the literal UTF-8 key, NOT decoded hex bytes.
  return Utilities.computeHmacSha256Signature(
    canonicalEvent_(event), secret, Utilities.Charset.UTF_8,
  ).map(function (byte) {
    return ('0' + (byte & 255).toString(16)).slice(-2);
  }).join('');
}

/** @param {string} provided @param {string} expected */
function equalMac_(provided, expected) {
  if (typeof provided !== 'string' || typeof expected !== 'string' ||
      !/^[0-9a-f]{64}$/.test(provided) || !/^[0-9a-f]{64}$/.test(expected)) {
    return false;
  }
  let difference = 0;
  for (let i = 0; i < 64; i += 1) {
    difference |= provided.charCodeAt(i) ^ expected.charCodeAt(i);
  }
  // Fixed 64-position work, not a documented V8 constant-time primitive.
  return difference === 0;
}

/** @param {*} event @param {number} now */
function freshEvent_(event, now) {
  return now - event.issuedAt <= EVENT_PROTOCOL.freshMs &&
    event.issuedAt - now <= EVENT_PROTOCOL.futureMs;
}

/** @param {*} receipt @param {*} event */
function validReceipt_(receipt, event) {
  return exactKeys_(receipt, ['eventId', 'acceptedAt', 'expiresAt']) &&
    receipt.eventId === event.eventId && Number.isSafeInteger(receipt.acceptedAt) &&
    receipt.acceptedAt > 0 && Number.isSafeInteger(receipt.expiresAt) &&
    receipt.expiresAt === receipt.acceptedAt + EVENT_PROTOCOL.retentionMs &&
    freshEvent_(event, receipt.acceptedAt);
}

// Install an identical copy in each independent project. No shared library is used.
const EVENT_PROTOCOL = Object.freeze({
  version: 1,
  maxBodyBytes: 2048,
  freshMs: 5 * 60 * 1000,
  futureMs: 30 * 1000,
  retentionMs: 24 * 60 * 60 * 1000,
  maxReceipts: 8,
  maxStoreBytes: 7000,
});

/** @param {unknown} value @param {string[]} keys */
function exactKeys_(value, keys) {
  return value !== null && typeof value === 'object' && !Array.isArray(value) &&
    Object.keys(value).length === keys.length &&
    keys.every(function (key) { return Object.prototype.hasOwnProperty.call(value, key); });
}

/** @param {string} text */
function utf8Length_(text) {
  return Utilities.newBlob(text).getBytes().length;
}

/** @param {string} text @param {number} maxBytes @returns {*} */
function parseBoundedJson_(text, maxBytes) {
  if (typeof text !== 'string' || text.length === 0 || text.length > maxBytes ||
      utf8Length_(text) > maxBytes) {
    throw new Error('JSON text is missing or exceeds its byte limit.');
  }
  try {
    return JSON.parse(text);
  } catch (error) {
    // Do not include a parser message that might quote the input.
    throw new Error('Invalid JSON text.');
  }
}

/** @param {*} event */
function validEventFields_(event) {
  if (event.version !== EVENT_PROTOCOL.version ||
      typeof event.eventId !== 'string' ||
      !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(event.eventId) ||
      !Number.isSafeInteger(event.issuedAt) || event.issuedAt <= 0 ||
      !exactKeys_(event.payload, ['type', 'requestId', 'note'])) {
    return false;
  }
  const payload = event.payload;
  return payload.type === 'request.note' && typeof payload.requestId === 'string' &&
    /^REQ-[0-9]{3}$/.test(payload.requestId) &&
    typeof payload.note === 'string' && payload.note.trim().length > 0 &&
    payload.note.length <= 120 && !/[\u0000-\u001f\u007f]/.test(payload.note) &&
    utf8Length_(payload.note) <= 240;
}

/** @param {string} body */
function readEnvelope_(body) {
  const event = parseBoundedJson_(body, EVENT_PROTOCOL.maxBodyBytes);
  if (!exactKeys_(event, ['version', 'eventId', 'issuedAt', 'payload', 'signature']) ||
      !validEventFields_(event) || typeof event.signature !== 'string' ||
      !/^[0-9a-f]{64}$/.test(event.signature)) {
    throw new Error('Invalid event envelope.');
  }
  return event;
}

/** @param {*} event */
function eventFields_(event) {
  return {
    version: event.version,
    eventId: event.eventId,
    issuedAt: event.issuedAt,
    payload: {
      type: event.payload.type,
      requestId: event.payload.requestId,
      note: event.payload.note,
    },
  };
}

/** @param {*} event */
function canonicalEvent_(event) {
  // No pretty printing, trailing newline, Unicode normalization, or key sorting.
  return JSON.stringify([
    'apps-script-custom-event', event.version, event.eventId, event.issuedAt,
    event.payload.type, event.payload.requestId, event.payload.note,
  ]);
}

function readSecret_() {
  const secret = PropertiesService.getScriptProperties().getProperty('EVENT_SECRET_HEX');
  if (typeof secret !== 'string' || !/^[0-9a-f]{64}$/.test(secret)) {
    throw new Error('Set EVENT_SECRET_HEX to the generated 64-character lowercase hex value.');
  }
  return secret;
}

/** @param {*} event @param {string} secret */
function signEvent_(event, secret) {
  // The 64 hex characters are the literal UTF-8 key, NOT decoded hex bytes.
  return Utilities.computeHmacSha256Signature(
    canonicalEvent_(event), secret, Utilities.Charset.UTF_8,
  ).map(function (byte) {
    return ('0' + (byte & 255).toString(16)).slice(-2);
  }).join('');
}

/** @param {string} provided @param {string} expected */
function equalMac_(provided, expected) {
  if (typeof provided !== 'string' || typeof expected !== 'string' ||
      !/^[0-9a-f]{64}$/.test(provided) || !/^[0-9a-f]{64}$/.test(expected)) {
    return false;
  }
  let difference = 0;
  for (let i = 0; i < 64; i += 1) {
    difference |= provided.charCodeAt(i) ^ expected.charCodeAt(i);
  }
  // Fixed 64-position work, not a documented V8 constant-time primitive.
  return difference === 0;
}

/** @param {*} event @param {number} now */
function freshEvent_(event, now) {
  return now - event.issuedAt <= EVENT_PROTOCOL.freshMs &&
    event.issuedAt - now <= EVENT_PROTOCOL.futureMs;
}

/** @param {*} receipt @param {*} event */
function validReceipt_(receipt, event) {
  return exactKeys_(receipt, ['eventId', 'acceptedAt', 'expiresAt']) &&
    receipt.eventId === event.eventId && Number.isSafeInteger(receipt.acceptedAt) &&
    receipt.acceptedAt > 0 && Number.isSafeInteger(receipt.expiresAt) &&
    receipt.expiresAt === receipt.acceptedAt + EVENT_PROTOCOL.retentionMs &&
    freshEvent_(event, receipt.acceptedAt);
}

const RECEIPTS_PROPERTY = 'EVENT_RECEIPTS_V1';

/** @param {*} e */
function doGet(e) {
  if (e && (e.queryString || e.pathInfo)) return jsonReply_(failure_('bad_request', false));
  // Liveness only: no secret, receipt, configuration, or readiness disclosure.
  return jsonReply_({ protocol: 1, ok: true, service: 'custom-event-receiver' });
}

/** @param {*} e */
function doPost(e) {
  try {
    const post = e && e.postData;
    if (!post || e.queryString || e.pathInfo ||
        !Number.isInteger(e.contentLength) || e.contentLength <= 0 ||
        e.contentLength > EVENT_PROTOCOL.maxBodyBytes || post.length !== e.contentLength ||
        typeof post.type !== 'string' ||
        !/^application\/json(?:\s*;\s*charset=utf-8)?$/i.test(post.type)) {
      return jsonReply_(failure_('bad_request', false));
    }
    let event;
    try {
      event = readEnvelope_(post.contents);
    } catch (error) {
      return jsonReply_(failure_('bad_request', false));
    }
    const expected = signEvent_(event, readSecret_());
    if (!equalMac_(event.signature, expected)) {
      return jsonReply_(failure_('unauthorized', false));
    }
    if (!freshEvent_(event, Date.now())) return jsonReply_(failure_('stale', false));
    // No lock acquisition or receipt-store access occurs before authentication.
    return jsonReply_(receiveEvent_(event));
  } catch (error) {
    // Storage failure or response failure can follow acceptance. Do not echo errors.
    return jsonReply_(failure_('unavailable', true));
  }
}

/** @param {*} event */
function receiveEvent_(event) {
  const lock = LockService.getScriptLock();
  if (!lock.tryLock(1000)) return failure_('busy', true);
  try {
    const store = PropertiesService.getScriptProperties();
    const records = readReceipts_(store);
    const now = Date.now();
    // Include time spent waiting for the lock and reading/validating the ledger.
    if (!freshEvent_(event, now)) return failure_('stale', false);
    const live = records.filter(/** @param {*} record */ function (record) { return record.expiresAt > now; });
    const existing = live.find(/** @param {*} record */ function (record) { return record.event.eventId === event.eventId; });
    if (existing) {
      if (canonicalEvent_(existing.event) !== canonicalEvent_(event)) {
        return failure_('conflict', false);
      }
      // A duplicate does not refresh either timestamp or rewrite the ledger.
      return receiptReply_('duplicate', existing);
    }
    if (live.length >= EVENT_PROTOCOL.maxReceipts) return failure_('capacity', true);
    const record = {
      event: eventFields_(event),
      acceptedAt: now,
      expiresAt: now + EVENT_PROTOCOL.retentionMs,
    };
    live.push(record);
    const serialized = JSON.stringify({ version: 1, receipts: live });
    if (utf8Length_(serialized) > EVENT_PROTOCOL.maxStoreBytes) return failure_('capacity', true);
    // One value contains both the harmless event and its receipt. No external action.
    store.setProperty(RECEIPTS_PROPERTY, serialized);
    return receiptReply_('accepted', record);
  } finally {
    lock.releaseLock();
  }
}

/** @param {PropertiesService.Properties} store */
function readReceipts_(store) {
  const raw = store.getProperty(RECEIPTS_PROPERTY);
  if (raw === null) return [];
  const ledger = parseBoundedJson_(raw, EVENT_PROTOCOL.maxStoreBytes);
  if (!exactKeys_(ledger, ['version', 'receipts']) || ledger.version !== 1 ||
      !Array.isArray(ledger.receipts) || ledger.receipts.length > EVENT_PROTOCOL.maxReceipts) {
    throw new Error('Invalid receipt ledger; stop and inspect rather than resetting it.');
  }
  const seen = new Set();
  for (const record of ledger.receipts) {
    if (!exactKeys_(record, ['event', 'acceptedAt', 'expiresAt']) ||
        !exactKeys_(record.event, ['version', 'eventId', 'issuedAt', 'payload']) ||
        !validEventFields_(record.event) ||
        !validReceipt_({
          eventId: record.event.eventId, acceptedAt: record.acceptedAt, expiresAt: record.expiresAt,
        }, record.event) || seen.has(record.event.eventId)) {
      throw new Error('Invalid receipt ledger; stop and inspect rather than resetting it.');
    }
    seen.add(record.event.eventId);
  }
  return ledger.receipts;
}

function checkReceiverSetup() {
  readSecret_();
  const lock = LockService.getScriptLock();
  if (!lock.tryLock(1000)) throw new Error('Receiver busy; try this editor check later.');
  try {
    const records = readReceipts_(PropertiesService.getScriptProperties());
    console.log(JSON.stringify({ configurationShapeChecked: true, storedReceipts: records.length }));
  } finally {
    lock.releaseLock();
  }
}

function inspectReceipts() {
  const lock = LockService.getScriptLock();
  if (!lock.tryLock(1000)) throw new Error('Receiver busy; inspect again later.');
  try {
    const records = readReceipts_(PropertiesService.getScriptProperties());
    const now = Date.now();
    // Only editor-visible identifiers/timestamps, not notes, signatures, or secrets.
    console.log(JSON.stringify(records.map(/** @param {*} record */ function (record) {
      return {
        eventId: record.event.eventId,
        requestId: record.event.payload.requestId,
        issuedAt: record.event.issuedAt,
        acceptedAt: record.acceptedAt,
        expiresAt: record.expiresAt,
        expired: record.expiresAt <= now,
      };
    })));
  } finally {
    lock.releaseLock();
  }
}

function pruneExpiredReceipts() {
  const lock = LockService.getScriptLock();
  if (!lock.tryLock(1000)) throw new Error('Receiver busy; prune later.');
  try {
    const store = PropertiesService.getScriptProperties();
    const records = readReceipts_(store);
    const now = Date.now();
    const live = records.filter(/** @param {*} record */ function (record) { return record.expiresAt > now; });
    if (live.length !== records.length) {
      store.setProperty(RECEIPTS_PROPERTY, JSON.stringify({ version: 1, receipts: live }));
    }
    console.log(JSON.stringify({ removedExpired: records.length - live.length, retained: live.length }));
  } finally {
    lock.releaseLock();
  }
}

/** @param {string} status @param {*} record */
function receiptReply_(status, record) {
  return {
    protocol: 1,
    ok: true,
    status: status,
    receipt: {
      eventId: record.event.eventId,
      acceptedAt: record.acceptedAt,
      expiresAt: record.expiresAt,
    },
  };
}

/** @param {string} code @param {boolean} retryable */
function failure_(code, retryable) {
  return { protocol: 1, ok: false, code: code, retryable: retryable };
}

/** @param {*} body */
function jsonReply_(body) {
  return ContentService.createTextOutput(JSON.stringify(body)).setMimeType(ContentService.MimeType.JSON);
}

const PENDING_PROPERTY = 'EVENT_PENDING_V1';

function checkSenderSetup() {
  readSenderConfig_();
  console.log('Sender configuration shape checked; no request sent.');
}

function prepareSampleEvent() {
  return withSenderLock_(function () {
    const config = readSenderConfig_();
    const store = PropertiesService.getScriptProperties();
    if (store.getProperty(PENDING_PROPERTY) !== null) {
      throw new Error('A pending event already exists. Inspect it; do not replace an uncertain identity.');
    }
    const event = {
      version: 1,
      eventId: Utilities.getUuid().toLowerCase(),
      issuedAt: Date.now(),
      payload: {
        type: SAMPLE_EVENT_PAYLOAD.type,
        requestId: SAMPLE_EVENT_PAYLOAD.requestId,
        note: SAMPLE_EVENT_PAYLOAD.note,
      },
      signature: '',
    };
    if (!validEventFields_(event)) throw new Error('Correct the bounded fictional payload in Sample.gs.');
    event.signature = signEvent_(event, config.secret);
    const body = JSON.stringify(event);
    readEnvelope_(body);
    savePending_(store, {
      endpointUrl: config.url, body: body, attemptedAt: null, receipt: null,
    });
    console.log(JSON.stringify({ state: 'prepared', eventId: event.eventId, issuedAt: event.issuedAt }));
  });
}

function sendPendingEvent() {
  return withSenderLock_(function () {
    const config = readSenderConfig_();
    const store = PropertiesService.getScriptProperties();
    const pending = requirePending_(store, config);
    if (!freshEvent_(pending.event, Date.now())) {
      throw new Error('Pending timestamp is outside the send window. Inspect/reconcile; do not re-sign or restamp.');
    }
    if (pending.stored.attemptedAt === null) {
      // Save the possibility of dispatch before the HTTP call. A crash can follow this write.
      pending.stored.attemptedAt = Date.now();
      savePending_(store, pending.stored);
    }
    const result = postEnvelope_(config.url, pending.stored.body, pending.event);
    if (result.ok) {
      const previous = pending.stored.receipt;
      if (previous && (previous.acceptedAt !== result.receipt.acceptedAt ||
          previous.expiresAt !== result.receipt.expiresAt)) {
        throw new Error('The receipt changed. Stop and reconcile the receiver; keep the original pending record.');
      }
      if (!previous) {
        pending.stored.receipt = result.receipt;
        savePending_(store, pending.stored);
      }
    }
    // postEnvelope_ permits only known fields; no raw response/body/URL/secret logging.
    console.log(JSON.stringify(result));
    return result;
  });
}

function sendTamperedProbe() {
  return sendProbe_('tampered');
}

function sendStaleProbe() {
  return sendProbe_('stale');
}

function sendConflictProbe() {
  return sendProbe_('conflict');
}

/** @param {string} kind */
function sendProbe_(kind) {
  return withSenderLock_(function () {
    const config = readSenderConfig_();
    const pending = requirePending_(PropertiesService.getScriptProperties(), config);
    if (!pending.stored.receipt) throw new Error('Confirm the normal event before running rejection probes.');
    if (!freshEvent_(pending.event, Date.now())) {
      throw new Error('The original event is too old for these probes. Finish this event before preparing a new example.');
    }
    // Change only a local parsed copy. The saved body, identity, and receipt stay intact.
    const event = pending.event;
    let expectedCode;
    if (kind === 'stale') {
      event.issuedAt -= 2 * EVENT_PROTOCOL.freshMs;
      event.signature = signEvent_(event, config.secret);
      expectedCode = 'stale';
    } else if (kind === 'tampered' || kind === 'conflict') {
      event.payload.note = event.payload.note === 'Changed probe note.'
        ? 'Different probe note.' : 'Changed probe note.';
      if (kind === 'conflict') event.signature = signEvent_(event, config.secret);
      expectedCode = kind === 'tampered' ? 'unauthorized' : 'conflict';
    } else {
      throw new Error('Unknown probe.');
    }
    const body = JSON.stringify(event);
    readEnvelope_(body);
    const result = postEnvelope_(config.url, body, event);
    if (result.ok || result.code !== expectedCode) {
      throw new Error('Probe did not receive its expected rejection. Inspect the receiver; no stored sender state was changed.');
    }
    console.log(JSON.stringify({ probe: kind, code: result.code, eventId: event.eventId }));
    return result;
  });
}

function inspectPendingEvent() {
  return withSenderLock_(function () {
    const pending = readPending_(PropertiesService.getScriptProperties());
    if (!pending) {
      console.log('No pending event.');
      return;
    }
    console.log(JSON.stringify({
      state: pending.stored.receipt ? 'confirmed' : pending.stored.attemptedAt === null ? 'prepared' : 'uncertain',
      eventId: pending.event.eventId,
      requestId: pending.event.payload.requestId,
      issuedAt: pending.event.issuedAt,
      attemptedAt: pending.stored.attemptedAt,
      receipt: pending.stored.receipt,
    }));
  });
}

function forgetConfirmedEvent() {
  return withSenderLock_(function () {
    const store = PropertiesService.getScriptProperties();
    const pending = readPending_(store);
    if (!pending || !pending.stored.receipt) {
      throw new Error('No confirmed event to forget. An unconfirmed event requires reconciliation, not a new identity.');
    }
    store.deleteProperty(PENDING_PROPERTY);
    console.log('Confirmed sender record removed; receiver receipt was not changed.');
  });
}

function readSenderConfig_() {
  const url = PropertiesService.getScriptProperties().getProperty('EVENT_ENDPOINT_URL');
  if (!validEndpointUrl_(url)) {
    throw new Error('Set EVENT_ENDPOINT_URL to the approved canonical HTTPS /macros/s/deployment-ID/exec URL, without query or suffix.');
  }
  return { url: url, secret: readSecret_() };
}

/** @param {unknown} url @returns {url is string} */
function validEndpointUrl_(url) {
  return typeof url === 'string' &&
    /^https:\/\/script\.google\.com\/macros\/s\/[A-Za-z0-9_-]{20,200}\/exec$/.test(url);
}

/** @param {PropertiesService.Properties} store */
function readPending_(store) {
  const raw = store.getProperty(PENDING_PROPERTY);
  if (raw === null) return null;
  const stored = parseBoundedJson_(raw, EVENT_PROTOCOL.maxStoreBytes);
  if (!exactKeys_(stored, ['endpointUrl', 'body', 'attemptedAt', 'receipt']) ||
      !validEndpointUrl_(stored.endpointUrl) ||
      !(stored.attemptedAt === null || (Number.isSafeInteger(stored.attemptedAt) && stored.attemptedAt > 0))) {
    throw new Error('Invalid pending record; stop and inspect rather than replacing it.');
  }
  const event = readEnvelope_(stored.body);
  if (stored.receipt !== null &&
      (stored.attemptedAt === null || !validReceipt_(stored.receipt, event))) {
    throw new Error('Invalid pending receipt; stop and inspect rather than replacing it.');
  }
  return { stored: stored, event: event };
}

/** @param {PropertiesService.Properties} store @param {*} config */
function requirePending_(store, config) {
  const pending = readPending_(store);
  if (!pending) throw new Error('Run prepareSampleEvent once before sending.');
  if (pending.stored.endpointUrl !== config.url) {
    throw new Error('The configured receiver changed. Reconcile the original event before changing its destination.');
  }
  if (!equalMac_(pending.event.signature, signEvent_(pending.event, config.secret))) {
    throw new Error('The pending signature no longer matches the key. Reconcile after rotation; do not silently re-sign.');
  }
  return pending;
}

/** @param {PropertiesService.Properties} store @param {*} pending */
function savePending_(store, pending) {
  const serialized = JSON.stringify(pending);
  if (utf8Length_(serialized) > EVENT_PROTOCOL.maxStoreBytes) throw new Error('Pending record exceeds its byte limit.');
  store.setProperty(PENDING_PROPERTY, serialized);
}

/** @param {string} url @param {string} body @param {*} event */
function postEnvelope_(url, body, event) {
  let response;
  try {
    response = UrlFetchApp.fetch(url, {
      method: 'post',
      contentType: 'application/json; charset=utf-8',
      payload: body,
      followRedirects: true,
      muteHttpExceptions: true,
      validateHttpsCertificates: true,
      timeoutSeconds: 30,
    });
  } catch (error) {
    throw new Error('Transport failed or timed out; acceptance is unknown. Keep the pending event.');
  }
  const status = response.getResponseCode();
  if (status !== 200) throw new Error('HTTP ' + status + '; acceptance is unknown. Keep the pending event.');
  const headers = response.getAllHeaders();
  const names = Object.keys(headers).filter(/** @param {string} name */ function (name) { return name.toLowerCase() === 'content-type'; });
  const type = names.length === 1 ? headers[names[0]] : null;
  if (typeof type !== 'string' || type.split(';')[0].trim().toLowerCase() !== 'application/json') {
    throw new Error('Expected a JSON response, not an authorization or error page. Acceptance is unknown.');
  }
  let result;
  try {
    result = parseBoundedJson_(response.getContentText('UTF-8'), EVENT_PROTOCOL.maxBodyBytes);
  } catch (error) {
    throw new Error('Response JSON is malformed or too large; acceptance is unknown.');
  }
  if (result && result.protocol === 1 && result.ok === true &&
      exactKeys_(result, ['protocol', 'ok', 'status', 'receipt']) &&
      (result.status === 'accepted' || result.status === 'duplicate') && validReceipt_(result.receipt, event)) {
    return result;
  }
  if (result && result.protocol === 1 && result.ok === false &&
      exactKeys_(result, ['protocol', 'ok', 'code', 'retryable']) && typeof result.code === 'string' &&
      rejectionMatches_(result.code, result.retryable)) {
    return result;
  }
  throw new Error('Unexpected response envelope or receipt; acceptance is unknown.');
}

/** @param {string} code @param {boolean} retryable */
function rejectionMatches_(code, retryable) {
  switch (code) {
    case 'bad_request':
    case 'unauthorized':
    case 'stale':
    case 'conflict':
      return retryable === false;
    case 'capacity':
    case 'busy':
    case 'unavailable':
      return retryable === true;
    default:
      return false;
  }
}

/** @param {function(): *} work */
function withSenderLock_(work) {
  const lock = LockService.getScriptLock();
  if (!lock.tryLock(1000)) throw new Error('Another sender operation is running. Let it finish.');
  try {
    // This local lock also prevents forgetting/replacing an event during its fetch.
    return work();
  } finally {
    lock.releaseLock();
  }
}