nervur 0.21.4 → 0.22.0

package/dist/{contract → core/contract}/index.d.ts

@@ -29,13 +29,14 @@ export type Module = {
     readonly version: string;
     readonly classes: readonly unknown[];
 };
-export type Loaded = Module & {
-    readonly from: string;
-};
 export declare abstract class Loader {
-    abstract load(from: string): Promise<Loaded | null>;
-    missing(_from: string): string | null;
+    abstract load(source: string, id: string): Promise<Module>;
 }
+export type Bundled = {
+    readonly source: string;
+    readonly module: Module;
+};
+export { bindKit, linked, moduleOf } from './link.ts';
 export declare abstract class Carrier {
     abstract carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
 }

package/dist/{contract → core/contract}/index.js

@@ -17,17 +17,16 @@ export class Memory {
 // secret a terrain holds.
 export class Custody {
 }
-// Code, by the name a harbor keeps for it, or null where this loader has
-// none. Code it has that does not load throws, saying why. Code never
-// crosses a door and never lives in a cell, so it is the
-// one thing beside the seed a terrain hands in: a map, an import, a bundle.
+// Bytes become a module. A module's source is one self-contained ES
+// module that imports nothing but `'nervur'`, and `id` is the git id of
+// its blob, the one name a bundle finds it by. What does not load throws,
+// saying why. How code runs differs by ground, an import of a data: URL,
+// of a Blob URL, or a lookup in the bundle an edge was deployed with, so
+// the loader is the one body beside the seed a terrain hands in that code
+// passes through.
 export class Loader {
-    // Why a name it found nothing under holds nothing, where it can say more
-    // than that: a bundle names that code comes from it alone.
-    missing(_from) {
-        return null;
-    }
 }
+export { bindKit, linked, moduleOf } from './link.js';
 // Bytes to a ward pk in; bytes, or null for nothing, out. A harbor hands a
 // terrain's carrier what it holds no route for; what it routes goes to its
 // carrier faculties.

package/dist/core/contract/link.d.ts

@@ -0,0 +1,4 @@
+import type { Module } from './index.ts';
+export declare const bindKit: (kit: object) => void;
+export declare const linked: (source: string) => string;
+export declare const moduleOf: (exported: unknown) => Module;

package/dist/core/contract/link.js

@@ -0,0 +1,45 @@
+const KITS = 'org.nervur.kits';
+const kits = () => {
+    const holder = globalThis;
+    return (holder[Symbol.for(KITS)] ??= new Map());
+};
+// This copy's token, the count of copies bound before it, since an edge
+// draws no random bytes while its script loads.
+let token;
+// This copy's exports, as a module's `'nervur'` reads them.
+export const bindKit = (kit) => {
+    const all = kits();
+    token ??= `kit${String(all.size)}`;
+    all.set(token, kit);
+};
+const IMPORT = /\bimport\s*(\{[^}]*\}|\*\s*as\s+[A-Za-z_$][\w$]*)\s*from\s*(['"])nervur\2\s*;?/g;
+const OTHER = /(^|[\n;{}])\s*(import\s*[\w{*'"]|export\s*(\*|\{[^}]*\})\s*from\b)/;
+// A module's source with its `'nervur'` imports read from this copy, or a
+// throw where it imports anything else.
+export const linked = (source) => {
+    if (token === undefined)
+        throw new Error('no kit is bound to link a module against');
+    const kit = `globalThis[Symbol.for(${JSON.stringify(KITS)})].get(${JSON.stringify(token)})`;
+    const out = source.replace(IMPORT, (_all, names) => {
+        if (names.startsWith('*'))
+            return `const ${names.replace(/^\*\s*as\s+/, '')} = ${kit};`;
+        const fields = names
+            .slice(1, -1)
+            .split(',')
+            .map((n) => n.trim())
+            .filter((n) => n !== '')
+            .map((n) => n.replace(/\s+as\s+/, ': '));
+        return `const { ${fields.join(', ')} } = ${kit};`;
+    });
+    if (OTHER.test(out))
+        throw new Error("a module imports nothing but 'nervur'");
+    return out;
+};
+// What a module's code exported, read as a module, or a throw saying what
+// it lacks.
+export const moduleOf = (exported) => {
+    const { module, version, classes } = (exported ?? {});
+    if (typeof module !== 'string' || typeof version !== 'string' || !Array.isArray(classes))
+        throw new Error('the code exports no module: module, version and classes');
+    return { module, version, classes };
+};

package/dist/{crypto → core/crypto}/ed25519.js

@@ -1,14 +1,17 @@
 // SPDX-License-Identifier: Apache-2.0
-// Ed25519 signs, as RFC 8032 defines it, and verifies with the cofactorless
-// check. The spec names exactly where a check fails, and Web Crypto promises
-// none of the decoding rules, so they are held here before Web Crypto runs:
+// Ed25519 signs, as RFC 8032 defines it, by `@noble/curves` in every
+// engine, since an engine's Web Crypto may refuse a secret the curve takes,
+// and verifies with the cofactorless check the spec names, which the
+// library's own verify does not make. The decoding rules are held here:
 //
 //   a signature of any length but sixty-four
 //   an `s` at or above the group order
 //   an `R` that does not decode, or whose bytes are not its point's encoding
 //   a public key that does not decode, or whose y is at or above the prime
 //   a public key of small order, in any spelling
-import { importSecret, own, publicOf, subtle } from './subtle.js';
+import { ed25519 } from '@noble/curves/ed25519.js';
+import { concat } from './bytes.js';
+import { own, subtle } from './subtle.js';
 const P = 2n ** 255n - 19n;
 const L = 2n ** 252n + 27742317777372353535851937790883648493n;
 const mod = (a) => ((a % P) + P) % P;
@@ -63,8 +66,14 @@ const smallOrder = (p) => {
         q = add(q, q);
     return q.x === 0n && q.y === q.z;
 };
-export const ed25519Public = async (secret) => publicOf(await importSecret('Ed25519', secret, ['sign']));
-export const sign = async (secret, message) => new Uint8Array(await subtle().sign('Ed25519', await importSecret('Ed25519', secret, ['sign']), own(message)));
+const secretOf = (secret) => {
+    if (secret.length !== 32)
+        throw new TypeError('a secret is thirty-two bytes');
+    return secret;
+};
+export const ed25519Public = async (secret) => ed25519.getPublicKey(secretOf(secret));
+export const sign = async (secret, message) => ed25519.sign(message, secretOf(secret));
+// The cofactorless check, `[s]B = R + [k]A`, on points decoded as above.
 export const verify = async (pk, message, signature) => {
     if (signature.length !== 64)
         return false;
@@ -73,13 +82,12 @@ export const verify = async (pk, message, signature) => {
         return false;
     if (decode(signature.subarray(0, 32)) === null)
         return false;
-    if (little(signature.subarray(32)) >= L)
-        return false;
-    try {
-        const imported = await subtle().importKey('raw', own(pk), { name: 'Ed25519' }, false, ['verify']);
-        return await subtle().verify('Ed25519', imported, own(signature), own(message));
-    }
-    catch {
+    const s = little(signature.subarray(32));
+    if (s >= L)
         return false;
-    }
+    const R = ed25519.Point.fromBytes(signature.subarray(0, 32));
+    const A = ed25519.Point.fromBytes(pk);
+    const hashed = new Uint8Array(await subtle().digest('SHA-512', own(concat(signature.subarray(0, 32), pk, message))));
+    const k = little(hashed) % L;
+    return ed25519.Point.BASE.multiplyUnsafe(s).equals(R.add(A.multiplyUnsafe(k)));
 };

package/dist/core/crypto/subtle.d.ts

@@ -0,0 +1,3 @@
+export declare const subtle: () => SubtleCrypto;
+export type Bytes = Uint8Array<ArrayBuffer>;
+export declare const own: (bytes: Uint8Array) => Bytes;

package/dist/core/crypto/subtle.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+// Web Crypto, read at every use. A page on a plain http origin has `crypto`
+// without `subtle`, and a terrain may install it after this module loads.
+export const subtle = () => {
+    const found = globalThis.crypto?.subtle;
+    if (!found)
+        throw new Error('this terrain has no crypto.subtle: a ward needs a secure context');
+    return found;
+};
+// Web Crypto takes a buffer it owns, so every input is copied into one.
+export const own = (bytes) => Uint8Array.from(bytes);

package/dist/core/crypto/x25519.js

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: Apache-2.0
+// X25519 agrees, by `@noble/curves` in every engine, since an engine's Web
+// Crypto may refuse a secret the curve takes. A secret is thirty-two bytes,
+// clamped by the function and never before.
+import { x25519 } from '@noble/curves/ed25519.js';
+import { zero } from './bytes.js';
+export const x25519Public = async (secret) => {
+    if (secret.length !== 32)
+        throw new TypeError('a secret is thirty-two bytes');
+    return x25519.getPublicKey(secret);
+};
+// The agreement, or null for a public key that takes no seal: one whose
+// agreement is thirty-two zero bytes.
+export const agree = async (secret, pk) => {
+    if (pk.length !== 32 || secret.length !== 32)
+        return null;
+    try {
+        const shared = x25519.getSharedSecret(secret, pk);
+        return zero(shared) ? null : shared;
+    }
+    catch {
+        return null;
+    }
+};

package/dist/core/edge/index.d.ts

@@ -0,0 +1,164 @@
+import { Custody, Loader, Memory, type Entropy, type Module } from '../contract/index.ts';
+import { type Carried, type Defaults, type Dialed, type GroundProbe, type Sockets, type TcpListening, type WebListen } from '../harbor/index.ts';
+import { PointerTerrain } from '../pointer/index.ts';
+export type { Carried } from '../harbor/index.ts';
+export declare const EDGE = "edge";
+export interface EdgeStorage {
+    get(key: string): Promise<unknown>;
+    put(entries: Record<string, unknown>): Promise<void>;
+    delete(keys: string[]): Promise<number>;
+    list(options: {
+        prefix: string;
+    }): Promise<Map<string, unknown>>;
+    transaction<T>(work: (txn: EdgeStorage) => Promise<T>): Promise<T>;
+}
+export interface EdgeState {
+    readonly storage: EdgeStorage;
+    blockConcurrencyWhile<T>(work: () => Promise<T>): Promise<T>;
+}
+export type EdgeEnv = {
+    readonly NERVUR_SECRET?: string;
+};
+export type EdgeGiven = {
+    readonly state: EdgeState;
+    readonly env: EdgeEnv;
+    readonly loader?: EdgeLoader;
+    readonly calls?: ChildCalls;
+    readonly package?: Packed;
+};
+export type CarriedModule = {
+    readonly blob: string;
+    readonly module: unknown;
+};
+export type CallContext = {
+    run<R>(call: number, work: () => R): R;
+    getStore(): number | undefined;
+};
+export declare class ChildCalls {
+    #private;
+    constructor(context?: CallContext);
+    run<R>(call: number, work: () => R): R;
+    refused(): void;
+    kept(): void;
+    again(call: number): boolean;
+}
+export declare class EdgeLoader extends Loader {
+    #private;
+    constructor(carried?: readonly CarriedModule[], calls?: ChildCalls);
+    get carried(): string[];
+    refuse(refused: Readonly<Record<string, string>>): void;
+    get refused(): ReadonlyMap<string, string>;
+    load(source: string, id: string): Promise<Module>;
+    get missing(): boolean;
+    missed(): Map<string, string>;
+}
+export type Packed = {
+    readonly sealed: string;
+    readonly places: Carried['places'];
+};
+export type Pack = Record<string, Packed>;
+export declare const isHarborName: (name: unknown) => name is string;
+export declare const readPack: (value: unknown) => Pack | null;
+export declare const sealSeed: (secret: string, seed: Uint8Array, entropy?: Entropy) => Promise<string>;
+export declare class EdgeMemory extends Memory {
+    #private;
+    constructor(storage: EdgeStorage, root?: string, voided?: () => boolean, calls?: ChildCalls);
+    read(place: string): Promise<Map<string, Uint8Array>>;
+    write(place: string, entries: ReadonlyMap<string, Uint8Array | null>): Promise<void>;
+    places(): Promise<string[]>;
+    forget(place: string): Promise<void>;
+}
+export declare class EdgeCustody extends Custody {
+    #private;
+    constructor(storage: EdgeStorage, secret: string | undefined, entropy?: Entropy, root?: string);
+    kept(): Promise<boolean>;
+    land(sealed: string, txn?: EdgeStorage): Promise<void>;
+    seed(): Promise<Uint8Array>;
+}
+export declare class EdgeSockets implements Sockets {
+    #private;
+    dial(address: string, pk: string, bytes: Uint8Array): Promise<Dialed>;
+    listen(): Promise<TcpListening>;
+    close(): Promise<void>;
+}
+export type EdgeParts = {
+    readonly given: EdgeGiven;
+    readonly defaults: Defaults;
+};
+export declare class EdgeTerrain extends PointerTerrain {
+    #private;
+    readonly given: EdgeGiven;
+    constructor(parts: EdgeParts);
+    get listening(): WebListen | undefined;
+    claim(): Promise<void>;
+}
+export declare const edgeGround: GroundProbe;
+export declare const harborNameOf: (request: Request) => string | null;
+export type Wanted = {
+    readonly live: string;
+    readonly liveBlobs: readonly string[];
+    readonly modules: Readonly<Record<string, string>>;
+    readonly missed: readonly string[];
+};
+export type Opened = {
+    readonly listen: WebListen | null;
+    readonly wanted: Wanted | null;
+};
+export type Arrived = {
+    readonly reply: Uint8Array | null;
+    readonly wanted: Wanted | null;
+    readonly again: boolean;
+};
+export declare const childKey: (live: string, blobs: readonly string[], liveBlobs: readonly string[]) => string;
+export declare class HarborChild {
+    #private;
+    constructor(state: EdgeState, env: EdgeEnv, key: string, carried: readonly CarriedModule[], context: CallContext);
+    open(name: string, host: string, port: number, packed: Packed | null, refused: Readonly<Record<string, string>>): Promise<Opened>;
+    arrive(pk: string, box: Uint8Array, call: number): Promise<Arrived>;
+}
+type WorkerCode = {
+    readonly compatibilityDate: string;
+    readonly compatibilityFlags?: readonly string[];
+    readonly mainModule: string;
+    readonly modules: Record<string, {
+        js: string;
+    }>;
+    readonly env: Record<string, unknown>;
+};
+type LoadedWorker = {
+    getDurableObjectClass(name: string): unknown;
+    getEntrypoint(): {
+        fetch(request: Request): Promise<Response>;
+    };
+};
+export type WorkerLoader = {
+    get(id: string, code: () => Promise<WorkerCode>): LoadedWorker;
+};
+type ChildStub = {
+    open(name: string, host: string, port: number, packed: Packed | null, refused: Record<string, string>): Promise<Opened>;
+    arrive(pk: string, box: Uint8Array, call: number): Promise<Arrived>;
+};
+type Facets = {
+    get(name: string, start: () => Promise<{
+        class: unknown;
+    }>): ChildStub;
+    abort(name: string, reason: unknown): void;
+};
+export type ShellState = {
+    readonly facets: Facets;
+};
+export type ShellEnv = EdgeEnv & {
+    readonly LOADER?: WorkerLoader;
+};
+export type HarborShellParts = {
+    readonly kit: string;
+    readonly pack: Pack | ((env: EdgeEnv) => Pack | undefined);
+};
+export type HarborShell = {
+    fetch(request: Request): Promise<Response>;
+};
+export type HarborShellClass = new (state: ShellState, env: ShellEnv) => HarborShell;
+export declare const harborShell: ({ kit, pack }: HarborShellParts) => HarborShellClass;
+export declare const harborWorker: (binding?: string) => {
+    fetch(request: Request, env: Record<string, unknown>): Promise<Response>;
+};