@sigil-security/core 0.0.0

package/dist/index.js

@@ -0,0 +1,575 @@
+// src/web-crypto-provider.ts
+var WebCryptoCryptoProvider = class {
+  /**
+   * Signs data with HMAC-SHA256 using WebCrypto.
+   * Returns full 256-bit (32-byte) MAC, NO truncation.
+   */
+  async sign(key, data) {
+    return globalThis.crypto.subtle.sign("HMAC", key, data);
+  }
+  /**
+   * Verifies an HMAC-SHA256 signature using WebCrypto.
+   * Inherently constant-time via crypto.subtle.verify.
+   */
+  async verify(key, signature, data) {
+    return globalThis.crypto.subtle.verify("HMAC", key, signature, data);
+  }
+  /**
+   * Derives an HMAC-SHA256 signing key from a master secret via HKDF-SHA256.
+   *
+   * HKDF (RFC 5869) with:
+   * - Hash: SHA-256
+   * - Salt: encoded string
+   * - Info: encoded string (includes domain separation)
+   * - Output: HMAC-SHA256 key, 256-bit, non-extractable
+   */
+  async deriveKey(master, salt, info) {
+    const encoder = new TextEncoder();
+    const baseKey = await globalThis.crypto.subtle.importKey("raw", master, { name: "HKDF" }, false, [
+      "deriveKey"
+    ]);
+    return globalThis.crypto.subtle.deriveKey(
+      {
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: encoder.encode(salt),
+        info: encoder.encode(info)
+      },
+      baseKey,
+      { name: "HMAC", hash: "SHA-256", length: 256 },
+      false,
+      ["sign", "verify"]
+    );
+  }
+  /**
+   * Generates cryptographically secure random bytes via crypto.getRandomValues.
+   * NEVER uses Math.random.
+   */
+  randomBytes(length) {
+    const buffer = new Uint8Array(length);
+    globalThis.crypto.getRandomValues(buffer);
+    return buffer;
+  }
+  /**
+   * Computes SHA-256 hash via WebCrypto.
+   * Returns full 256-bit (32-byte) digest.
+   */
+  async hash(data) {
+    return globalThis.crypto.subtle.digest("SHA-256", data);
+  }
+};
+
+// src/key-derivation.ts
+var HKDF_SALT = "sigil-v1";
+var DOMAIN_INFO_PREFIX = {
+  csrf: "csrf-signing-key-",
+  oneshot: "oneshot-signing-key-",
+  internal: "internal-signing-key-"
+};
+async function deriveSigningKey(cryptoProvider, master, kid, domain) {
+  const info = `${DOMAIN_INFO_PREFIX[domain]}${String(kid)}`;
+  return cryptoProvider.deriveKey(master, HKDF_SALT, info);
+}
+
+// src/key-manager.ts
+var MAX_KEYS = 3;
+var KID_MIN = 0;
+var KID_MAX = 255;
+function validateKid(kid) {
+  if (!Number.isInteger(kid) || kid < KID_MIN || kid > KID_MAX) {
+    throw new RangeError(
+      `kid must be an integer in the range ${String(KID_MIN)}\u2013${String(KID_MAX)}, got ${String(kid)}`
+    );
+  }
+}
+async function createKeyring(cryptoProvider, masterSecret, initialKid, domain) {
+  validateKid(initialKid);
+  const cryptoKey = await deriveSigningKey(cryptoProvider, masterSecret, initialKid, domain);
+  const entry = {
+    kid: initialKid,
+    cryptoKey,
+    createdAt: Date.now()
+  };
+  return {
+    keys: [entry],
+    activeKid: initialKid,
+    domain
+  };
+}
+async function rotateKey(keyring, cryptoProvider, masterSecret, newKid) {
+  validateKid(newKid);
+  const cryptoKey = await deriveSigningKey(
+    cryptoProvider,
+    masterSecret,
+    newKid,
+    keyring.domain
+  );
+  const entry = {
+    kid: newKid,
+    cryptoKey,
+    createdAt: Date.now()
+  };
+  const keys = [entry, ...keyring.keys].slice(0, MAX_KEYS);
+  return {
+    keys,
+    activeKid: newKid,
+    domain: keyring.domain
+  };
+}
+function resolveKey(keyring, kid) {
+  return keyring.keys.find((k) => k.kid === kid);
+}
+function getActiveKey(keyring) {
+  return resolveKey(keyring, keyring.activeKid);
+}
+
+// src/types.ts
+var KID_SIZE = 1;
+var NONCE_SIZE = 16;
+var TIMESTAMP_SIZE = 8;
+var CONTEXT_SIZE = 32;
+var MAC_SIZE = 32;
+var ACTION_SIZE = 32;
+var TOKEN_RAW_SIZE = KID_SIZE + NONCE_SIZE + TIMESTAMP_SIZE + CONTEXT_SIZE + MAC_SIZE;
+var ONESHOT_RAW_SIZE = NONCE_SIZE + TIMESTAMP_SIZE + ACTION_SIZE + CONTEXT_SIZE + MAC_SIZE;
+var TOKEN_OFFSETS = {
+  /** kid starts at byte 0 */
+  KID: 0,
+  /** nonce starts at byte 1 */
+  NONCE: KID_SIZE,
+  /** timestamp starts at byte 17 */
+  TIMESTAMP: KID_SIZE + NONCE_SIZE,
+  /** context starts at byte 25 */
+  CONTEXT: KID_SIZE + NONCE_SIZE + TIMESTAMP_SIZE,
+  /** mac starts at byte 57 */
+  MAC: KID_SIZE + NONCE_SIZE + TIMESTAMP_SIZE + CONTEXT_SIZE
+};
+var ONESHOT_OFFSETS = {
+  /** nonce starts at byte 0 */
+  NONCE: 0,
+  /** timestamp starts at byte 16 */
+  TIMESTAMP: NONCE_SIZE,
+  /** action starts at byte 24 */
+  ACTION: NONCE_SIZE + TIMESTAMP_SIZE,
+  /** context starts at byte 56 */
+  CONTEXT: NONCE_SIZE + TIMESTAMP_SIZE + ACTION_SIZE,
+  /** mac starts at byte 88 */
+  MAC: NONCE_SIZE + TIMESTAMP_SIZE + ACTION_SIZE + CONTEXT_SIZE
+};
+var DEFAULT_TOKEN_TTL_MS = 20 * 60 * 1e3;
+var DEFAULT_GRACE_WINDOW_MS = 60 * 1e3;
+var DEFAULT_ONESHOT_TTL_MS = 5 * 60 * 1e3;
+var DEFAULT_NONCE_CACHE_MAX = 1e4;
+var DEFAULT_NONCE_CACHE_TTL_MS = 5 * 60 * 1e3;
+
+// src/encoding.ts
+function toBase64Url(buffer) {
+  let binary = "";
+  for (const byte of buffer) {
+    binary += String.fromCharCode(byte);
+  }
+  const base64 = btoa(binary);
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(encoded) {
+  let base64 = encoded.replace(/-/g, "+").replace(/_/g, "/");
+  const padLength = (4 - base64.length % 4) % 4;
+  base64 += "=".repeat(padLength);
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+function writeUint64BE(buffer, value, offset) {
+  const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+  const high = Math.floor(value / 4294967296);
+  const low = value % 4294967296;
+  view.setUint32(offset, high, false);
+  view.setUint32(offset + 4, low, false);
+}
+function readUint64BE(buffer, offset) {
+  const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+  const high = view.getUint32(offset, false);
+  const low = view.getUint32(offset + 4, false);
+  return high * 4294967296 + low;
+}
+function toArrayBuffer(uint8) {
+  const copy = uint8.slice();
+  return copy.buffer;
+}
+
+// src/context.ts
+var ZERO_BYTE = new Uint8Array([0]);
+async function computeContext(cryptoProvider, ...bindings) {
+  if (bindings.length === 0) {
+    return emptyContext(cryptoProvider);
+  }
+  const encoder = new TextEncoder();
+  const parts = [];
+  for (const binding of bindings) {
+    parts.push(`${String(binding.length)}:${binding}\0`);
+  }
+  const data = encoder.encode(parts.join(""));
+  const hash = await cryptoProvider.hash(data);
+  return new Uint8Array(hash);
+}
+async function emptyContext(cryptoProvider) {
+  const hash = await cryptoProvider.hash(ZERO_BYTE);
+  return new Uint8Array(hash);
+}
+
+// src/token.ts
+async function generateToken(cryptoProvider, key, context, ttlMs = DEFAULT_TOKEN_TTL_MS, now = Date.now()) {
+  try {
+    const nonce = cryptoProvider.randomBytes(NONCE_SIZE);
+    const ts = now;
+    const ctx = context ?? await emptyContext(cryptoProvider);
+    const payloadSize = KID_SIZE + NONCE_SIZE + TIMESTAMP_SIZE + CONTEXT_SIZE;
+    const payload = new Uint8Array(payloadSize);
+    payload[0] = key.kid & 255;
+    payload.set(nonce, KID_SIZE);
+    writeUint64BE(payload, ts, KID_SIZE + NONCE_SIZE);
+    payload.set(ctx, KID_SIZE + NONCE_SIZE + TIMESTAMP_SIZE);
+    const macBuffer = await cryptoProvider.sign(key.cryptoKey, payload);
+    const mac = new Uint8Array(macBuffer);
+    const tokenRaw = new Uint8Array(TOKEN_RAW_SIZE);
+    tokenRaw.set(payload, 0);
+    tokenRaw.set(mac, payloadSize);
+    const token = toBase64Url(tokenRaw);
+    return {
+      success: true,
+      token,
+      expiresAt: ts + ttlMs
+    };
+  } catch {
+    return {
+      success: false,
+      reason: "token_generation_failed"
+    };
+  }
+}
+function parseToken(tokenString) {
+  let raw;
+  try {
+    raw = fromBase64Url(tokenString);
+  } catch {
+    return null;
+  }
+  if (raw.length !== TOKEN_RAW_SIZE) {
+    return null;
+  }
+  const kid = raw[TOKEN_OFFSETS.KID];
+  if (kid === void 0) {
+    return null;
+  }
+  const nonce = raw.slice(TOKEN_OFFSETS.NONCE, TOKEN_OFFSETS.NONCE + NONCE_SIZE);
+  const timestamp = readUint64BE(raw, TOKEN_OFFSETS.TIMESTAMP);
+  const context = raw.slice(TOKEN_OFFSETS.CONTEXT, TOKEN_OFFSETS.CONTEXT + CONTEXT_SIZE);
+  const mac = raw.slice(TOKEN_OFFSETS.MAC, TOKEN_OFFSETS.MAC + MAC_SIZE);
+  return { kid, nonce, timestamp, context, mac };
+}
+function assemblePayload(parsed) {
+  const payload = new Uint8Array(KID_SIZE + NONCE_SIZE + TIMESTAMP_SIZE + CONTEXT_SIZE);
+  payload[0] = parsed.kid & 255;
+  payload.set(parsed.nonce, KID_SIZE);
+  writeUint64BE(payload, parsed.timestamp, KID_SIZE + NONCE_SIZE);
+  payload.set(parsed.context, KID_SIZE + NONCE_SIZE + TIMESTAMP_SIZE);
+  return payload;
+}
+function serializeToken(kid, nonce, ts, ctx, mac) {
+  const tokenRaw = new Uint8Array(TOKEN_RAW_SIZE);
+  tokenRaw[0] = kid & 255;
+  tokenRaw.set(nonce, KID_SIZE);
+  writeUint64BE(tokenRaw, ts, KID_SIZE + NONCE_SIZE);
+  tokenRaw.set(ctx, KID_SIZE + NONCE_SIZE + TIMESTAMP_SIZE);
+  tokenRaw.set(mac, KID_SIZE + NONCE_SIZE + TIMESTAMP_SIZE + CONTEXT_SIZE);
+  return toBase64Url(tokenRaw);
+}
+
+// src/validation.ts
+var DUMMY_PAYLOAD = new Uint8Array(KID_SIZE + NONCE_SIZE + TIMESTAMP_SIZE + CONTEXT_SIZE);
+var DUMMY_MAC = new ArrayBuffer(32);
+async function validateToken(cryptoProvider, keyring, tokenString, expectedContext, ttlMs = DEFAULT_TOKEN_TTL_MS, graceWindowMs = DEFAULT_GRACE_WINDOW_MS, now = Date.now()) {
+  let valid = true;
+  let reason = "unknown";
+  const parsed = parseToken(tokenString);
+  const parseOk = parsed !== null;
+  valid &&= parseOk;
+  if (!parseOk) reason = "parse_failed";
+  const key = parseOk ? resolveKey(keyring, parsed.kid) : void 0;
+  const keyOk = key !== void 0;
+  valid &&= keyOk;
+  if (!keyOk) reason = "unknown_kid";
+  const ttlResult = parseOk ? validateTTL(parsed.timestamp, ttlMs, graceWindowMs, now) : { withinTTL: false, inGraceWindow: false };
+  const ttlOk = ttlResult.withinTTL || ttlResult.inGraceWindow;
+  valid &&= ttlOk;
+  if (!ttlOk) reason = "expired";
+  const macPayload = parseOk ? assemblePayload(parsed) : DUMMY_PAYLOAD;
+  const macSignature = parseOk ? toArrayBuffer(parsed.mac) : DUMMY_MAC;
+  const verifyKey = keyOk ? key.cryptoKey : keyring.keys[0]?.cryptoKey;
+  let macOk;
+  if (verifyKey !== void 0) {
+    const actualResult = await cryptoProvider.verify(verifyKey, macSignature, macPayload);
+    macOk = keyOk ? actualResult : false;
+  } else {
+    macOk = false;
+  }
+  valid &&= macOk;
+  if (!macOk) reason = "invalid_mac";
+  let contextOk = true;
+  if (expectedContext !== void 0) {
+    contextOk = parseOk ? constantTimeEqual(parsed.context, expectedContext) : false;
+  }
+  valid &&= contextOk;
+  if (!contextOk) reason = "context_mismatch";
+  return valid ? { valid: true } : { valid: false, reason };
+}
+function validateTTL(tokenTimestamp, ttlMs, graceWindowMs, now) {
+  const age = now - tokenTimestamp;
+  const withinTTL = age >= 0 && age <= ttlMs;
+  const inGraceWindow = !withinTTL && age > ttlMs && age <= ttlMs + graceWindowMs;
+  return { withinTTL, inGraceWindow };
+}
+function constantTimeEqual(a, b) {
+  const length = Math.max(a.length, b.length);
+  let result = a.length ^ b.length;
+  for (let i = 0; i < length; i++) {
+    result |= (a[i] ?? 0) ^ (b[i] ?? 0);
+  }
+  return result === 0;
+}
+
+// src/one-shot-token.ts
+var ONESHOT_PAYLOAD_SIZE = NONCE_SIZE + TIMESTAMP_SIZE + ACTION_SIZE + CONTEXT_SIZE;
+var DUMMY_ONESHOT_PAYLOAD = new Uint8Array(ONESHOT_PAYLOAD_SIZE);
+var DUMMY_MAC2 = new ArrayBuffer(32);
+async function computeAction(cryptoProvider, action) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(action);
+  const hash = await cryptoProvider.hash(data);
+  return new Uint8Array(hash);
+}
+async function generateOneShotToken(cryptoProvider, key, action, context, ttlMs = DEFAULT_ONESHOT_TTL_MS, now = Date.now()) {
+  try {
+    const nonce = cryptoProvider.randomBytes(NONCE_SIZE);
+    const ts = now;
+    const actionHash = await computeAction(cryptoProvider, action);
+    const ctx = context ?? await emptyContext(cryptoProvider);
+    const payload = new Uint8Array(ONESHOT_PAYLOAD_SIZE);
+    payload.set(nonce, 0);
+    writeUint64BE(payload, ts, NONCE_SIZE);
+    payload.set(actionHash, NONCE_SIZE + TIMESTAMP_SIZE);
+    payload.set(ctx, NONCE_SIZE + TIMESTAMP_SIZE + ACTION_SIZE);
+    const macBuffer = await cryptoProvider.sign(key.cryptoKey, payload);
+    const mac = new Uint8Array(macBuffer);
+    const tokenRaw = new Uint8Array(ONESHOT_RAW_SIZE);
+    tokenRaw.set(payload, 0);
+    tokenRaw.set(mac, ONESHOT_PAYLOAD_SIZE);
+    const token = toBase64Url(tokenRaw);
+    return {
+      success: true,
+      token,
+      expiresAt: ts + ttlMs
+    };
+  } catch {
+    return {
+      success: false,
+      reason: "oneshot_generation_failed"
+    };
+  }
+}
+function parseOneShotToken(tokenString) {
+  let raw;
+  try {
+    raw = fromBase64Url(tokenString);
+  } catch {
+    return null;
+  }
+  if (raw.length !== ONESHOT_RAW_SIZE) {
+    return null;
+  }
+  const nonce = raw.slice(ONESHOT_OFFSETS.NONCE, ONESHOT_OFFSETS.NONCE + NONCE_SIZE);
+  const timestamp = readUint64BE(raw, ONESHOT_OFFSETS.TIMESTAMP);
+  const action = raw.slice(ONESHOT_OFFSETS.ACTION, ONESHOT_OFFSETS.ACTION + ACTION_SIZE);
+  const context = raw.slice(ONESHOT_OFFSETS.CONTEXT, ONESHOT_OFFSETS.CONTEXT + CONTEXT_SIZE);
+  const mac = raw.slice(ONESHOT_OFFSETS.MAC, ONESHOT_OFFSETS.MAC + MAC_SIZE);
+  return { nonce, timestamp, action, context, mac };
+}
+async function validateOneShotToken(cryptoProvider, key, tokenString, expectedAction, nonceCache, expectedContext, ttlMs = DEFAULT_ONESHOT_TTL_MS, now = Date.now()) {
+  let valid = true;
+  let reason = "unknown";
+  const parsed = parseOneShotToken(tokenString);
+  const parseOk = parsed !== null;
+  valid &&= parseOk;
+  if (!parseOk) reason = "parse_failed";
+  const ttlResult = parseOk ? validateTTL(parsed.timestamp, ttlMs, 0, now) : { withinTTL: false, inGraceWindow: false };
+  const ttlOk = ttlResult.withinTTL;
+  valid &&= ttlOk;
+  if (!ttlOk) reason = "expired";
+  const expectedActionHash = await computeAction(cryptoProvider, expectedAction);
+  const actionOk = parseOk ? constantTimeEqual(parsed.action, expectedActionHash) : false;
+  valid &&= actionOk;
+  if (!actionOk) reason = "action_mismatch";
+  const macPayload = parseOk ? assembleOneShotPayload(parsed) : DUMMY_ONESHOT_PAYLOAD;
+  const macSignature = parseOk ? toArrayBuffer(parsed.mac) : DUMMY_MAC2;
+  const macOk = await cryptoProvider.verify(key.cryptoKey, macSignature, macPayload);
+  valid &&= macOk;
+  if (!macOk) reason = "invalid_mac";
+  let contextOk = true;
+  if (expectedContext !== void 0) {
+    contextOk = parseOk ? constantTimeEqual(parsed.context, expectedContext) : false;
+  }
+  valid &&= contextOk;
+  if (!contextOk) reason = "context_mismatch";
+  let nonceOk = true;
+  if (parseOk) {
+    const alreadyUsed = nonceCache.has(parsed.nonce);
+    if (alreadyUsed) {
+      nonceOk = false;
+    }
+  } else {
+    nonceOk = false;
+  }
+  valid &&= nonceOk;
+  if (!nonceOk) reason = "nonce_reused";
+  if (valid && parseOk) {
+    const consumed = nonceCache.markUsed(parsed.nonce);
+    if (!consumed) {
+      return { valid: false, reason: "nonce_reused" };
+    }
+  }
+  return valid ? { valid: true } : { valid: false, reason };
+}
+function assembleOneShotPayload(parsed) {
+  const payload = new Uint8Array(ONESHOT_PAYLOAD_SIZE);
+  payload.set(parsed.nonce, 0);
+  writeUint64BE(payload, parsed.timestamp, NONCE_SIZE);
+  payload.set(parsed.action, NONCE_SIZE + TIMESTAMP_SIZE);
+  payload.set(parsed.context, NONCE_SIZE + TIMESTAMP_SIZE + ACTION_SIZE);
+  return payload;
+}
+
+// src/nonce-cache.ts
+function nonceToKey(nonce) {
+  let key = "";
+  for (const byte of nonce) {
+    key += (byte >>> 4).toString(16);
+    key += (byte & 15).toString(16);
+  }
+  return key;
+}
+function createNonceCache(config) {
+  const maxEntries = config?.maxEntries ?? DEFAULT_NONCE_CACHE_MAX;
+  const defaultTTLMs = config?.defaultTTLMs ?? DEFAULT_NONCE_CACHE_TTL_MS;
+  const cache = /* @__PURE__ */ new Map();
+  function evictExpired() {
+    const now = Date.now();
+    for (const [key, entry] of cache) {
+      if (entry.expiresAt <= now) {
+        cache.delete(key);
+      }
+    }
+  }
+  function evictLRU() {
+    if (cache.size >= maxEntries) {
+      const firstKey = cache.keys().next().value;
+      if (firstKey !== void 0) {
+        cache.delete(firstKey);
+      }
+    }
+  }
+  return {
+    has(nonce) {
+      const key = nonceToKey(nonce);
+      const entry = cache.get(key);
+      if (entry === void 0) return false;
+      if (entry.expiresAt <= Date.now()) {
+        cache.delete(key);
+        return false;
+      }
+      return true;
+    },
+    markUsed(nonce) {
+      const key = nonceToKey(nonce);
+      const entry = cache.get(key);
+      if (entry === void 0) {
+        evictExpired();
+        evictLRU();
+        cache.set(key, {
+          expiresAt: Date.now() + defaultTTLMs,
+          used: true
+        });
+        return true;
+      }
+      if (entry.expiresAt <= Date.now()) {
+        cache.delete(key);
+        evictLRU();
+        cache.set(key, {
+          expiresAt: Date.now() + defaultTTLMs,
+          used: true
+        });
+        return true;
+      }
+      if (!entry.used) {
+        entry.used = true;
+        return true;
+      }
+      return false;
+    },
+    add(nonce, ttlMs) {
+      evictExpired();
+      evictLRU();
+      const key = nonceToKey(nonce);
+      cache.set(key, {
+        expiresAt: Date.now() + ttlMs,
+        used: false
+      });
+    },
+    get size() {
+      return cache.size;
+    }
+  };
+}
+export {
+  ACTION_SIZE,
+  CONTEXT_SIZE,
+  DEFAULT_GRACE_WINDOW_MS,
+  DEFAULT_NONCE_CACHE_MAX,
+  DEFAULT_NONCE_CACHE_TTL_MS,
+  DEFAULT_ONESHOT_TTL_MS,
+  DEFAULT_TOKEN_TTL_MS,
+  KID_SIZE,
+  MAC_SIZE,
+  NONCE_SIZE,
+  ONESHOT_OFFSETS,
+  ONESHOT_RAW_SIZE,
+  TIMESTAMP_SIZE,
+  TOKEN_OFFSETS,
+  TOKEN_RAW_SIZE,
+  WebCryptoCryptoProvider,
+  assemblePayload,
+  computeAction,
+  computeContext,
+  constantTimeEqual,
+  createKeyring,
+  createNonceCache,
+  deriveSigningKey,
+  emptyContext,
+  fromBase64Url,
+  generateOneShotToken,
+  generateToken,
+  getActiveKey,
+  parseOneShotToken,
+  parseToken,
+  resolveKey,
+  rotateKey,
+  serializeToken,
+  toArrayBuffer,
+  toBase64Url,
+  validateOneShotToken,
+  validateTTL,
+  validateToken
+};
+//# sourceMappingURL=index.js.map