@amritk/nish-x86_64-linux 0.16.0 → 0.18.0

package/std/secret.ts

@@ -0,0 +1,62 @@
+/**
+ * `nish:secret` — key material, and the rules that keep it in
+ * (docs/LANGUAGE.md, "Secrets").
+ *
+ *     import { Secret, expose, secret, wipe } from "nish:secret"
+ *
+ *     const key: Secret<u8[]> = secret(readKey())
+ *     const tag: u8[] = expose(key, (k: u8[]): u8[] => hmacSha256(k, message))
+ *     wipe(key)
+ *
+ * This file is the source behind the builtin module, and it is imported only
+ * by that name: `nish/secret` is refused, so there is one spelling for the
+ * checker's rules to be read under. What is written here is the meaning; what
+ * makes a `Secret` worth having is in `src/secret.ts`, which knows this module
+ * by its path and package:
+ *
+ *   - a `Secret` is opaque. Nothing outside this file reads its field, builds
+ *     one with `new`, prints it, interpolates it, compares it with anything but
+ *     another `Secret` or `null`, branches on it, indexes it, stores it in a
+ *     field, an array or a `Result`, or hands it to a builtin;
+ *   - a `Secret` a function makes leaves it returned or wiped, on every path;
+ *   - `expose` is the one way in, and the function it runs may reach no I/O and
+ *     no C, may not keep the value, may not write the argument `exposeWith`
+ *     hands it, and returns a declared type that holds no `Secret`;
+ *   - `wipe` is a volatile store of zeros over the value's whole storage,
+ *     which no optimiser may remove (`src/emit-secret.ts`).
+ *
+ * Under Node the module is answered by `runtime/shim.mjs`, where a `Secret` is
+ * a plain wrapper and `wipe` zero-fills it.
+ */
+
+/**
+ * Key material: an array of integers (`u8[]`, `u32[]`, ...) or a record whose
+ * every field is an integer. Made by `secret`, read only through `expose`.
+ */
+export class Secret<T> {
+  /** The wrapped value. Only this module reads or writes it (`src/secret.ts`). */
+  value: T
+
+  constructor(value: T) {
+    this.value = value
+  }
+}
+
+/** `value`, wrapped. The argument is moved: a local handed in is not read again. */
+export const secret = <T>(value: T): Secret<T> => new Secret<T>(value)
+
+/** `f(value)`: the one way to compute with what a `Secret` holds. */
+export const expose = <T, R>(s: Secret<T>, f: (value: T) => R): R => f(s.value)
+
+/** `f(value, arg)`: `expose` with one more argument, because an arrow captures nothing. */
+export const exposeWith = <T, A, R>(s: Secret<T>, arg: A, f: (value: T, arg: A) => R): R => f(s.value, arg)
+
+/**
+ * Zero every byte of `target`'s storage: a `Secret`'s value, or an array or
+ * record of integers that `expose`'s function holds. Natively the compiler
+ * gives each instance a body of its own, one volatile `llvm.memset`
+ * (`src/emit-secret.ts`); this one is never emitted.
+ */
+export const wipe = <T>(_target: T): void => {
+  // Lowered by the compiler: see above.
+}

package/std/text.ts

@@ -191,3 +191,80 @@ export const firstDifference = (left: string[], right: string[]): i32 => {
   }
   return leftLength === rightLength ? -1 : i
 }
+
+/** The most bytes `indexOfAny` takes in its set: what one 16-byte vector of the runtime kernel compares. */
+const INDEX_OF_ANY_MAX_SET: i32 = 16
+
+/** The first byte that is not ASCII; `indexOfAny`'s set must stay below it. */
+const NON_ASCII: i32 = 128
+
+/**
+ * The first index at or after `from` whose byte is one of `bytes`, or -1.
+ *
+ * `bytes` is a set of 1 to 16 ASCII bytes, and anything else panics: an empty
+ * set matches nothing, more than 16 is more than one vector of the runtime
+ * kernel compares, and an ASCII set is what keeps the answer the same under Node,
+ * where `charCodeAt` reads a UTF-16 unit rather than a byte. An ASCII byte
+ * never occurs inside a multi-byte UTF-8 sequence, so a non-ASCII `text`
+ * passes through and only its ASCII bytes can match — as in `splitLines`, the
+ * index is a byte offset natively. `from` is clamped to `[0, text.length]`,
+ * as `substring` clamps, so a negative `from` searches from the start and one
+ * past the end answers -1.
+ *
+ * Natively the search is the runtime's `nish_str_index_of_any`, which reads
+ * 16 or 32 bytes at a time (docs/LANGUAGE.md, "Byte search"). It is
+ * **variable-time**: how long it takes says where the first match is, so it is
+ * never for secret data.
+ */
+export const indexOfAny = (text: string, bytes: string, from: i32): i32 => {
+  const count: i32 = toI32(bytes.length)
+  if (count < 1 || count > INDEX_OF_ANY_MAX_SET) {
+    panic("indexOfAny: the set must hold 1 to 16 bytes")
+  }
+  let j: i32 = 0
+  while (j < count) {
+    if (toI32(bytes.charCodeAt(j)) >= NON_ASCII) {
+      panic("indexOfAny: every byte of the set must be ASCII")
+    }
+    j += 1
+  }
+  const length: i32 = toI32(text.length)
+  let start: i32 = from
+  if (start < 0) {
+    start = 0
+  }
+  if (start > length) {
+    start = length
+  }
+  return indexOfAnyFrom(text, bytes, start)
+}
+
+/**
+ * `indexOfAny`'s walk, once its arguments are checked: the first index at or
+ * after `from` whose byte is in `bytes`, or -1.
+ *
+ * This loop is what runs under Node. Natively the compiler recognises the one
+ * call `indexOfAny` makes to it and calls the runtime kernel instead
+ * (`src/kernels.ts`), so the loop is the kernel's meaning written in the
+ * language rather than its implementation. The name is long for the reason
+ * `isTextBlankByte`'s is.
+ */
+const indexOfAnyFrom = (text: string, bytes: string, from: i32): i32 => {
+  const length: i32 = toI32(text.length)
+  const count: i32 = toI32(bytes.length)
+  let i: i32 = from
+  // `from` is never negative, because `indexOfAny` clamped it; the test is
+  // written because it is what proves `i` within `text`, as in `splitLines`.
+  while (i >= 0 && i < length) {
+    const code: i32 = toI32(text.charCodeAt(i))
+    let j: i32 = 0
+    while (j < count) {
+      if (toI32(bytes.charCodeAt(j)) === code) {
+        return i
+      }
+      j += 1
+    }
+    i += 1
+  }
+  return -1
+}