@cero-base/core 0.0.5 → 0.4.0

package/types/lib/spec/index.d.ts

@@ -0,0 +1,95 @@
+export function resolveStruct(name: any, v?: number): {
+    preencode(state: any, m: any): void;
+    encode(state: any, m: any): void;
+    decode(state: any): {
+        hash: any;
+        coreKey: any;
+        blockOffset: any;
+        blockLength: any;
+        byteOffset: any;
+        byteLength: any;
+        size: any;
+        createdAt: any;
+        meta: any;
+    } | {
+        status: any;
+        reason: any;
+        key: any;
+        encryptionKey: any;
+        extra: any;
+    } | {
+        data: any;
+    } | {
+        id: any;
+        name: any;
+    };
+};
+export function getStruct(name: any, v?: number): {
+    preencode(state: any, m: any): void;
+    encode(state: any, m: any): void;
+    decode(state: any): {
+        hash: any;
+        coreKey: any;
+        blockOffset: any;
+        blockLength: any;
+        byteOffset: any;
+        byteLength: any;
+        size: any;
+        createdAt: any;
+        meta: any;
+    } | {
+        status: any;
+        reason: any;
+        key: any;
+        encryptionKey: any;
+        extra: any;
+    } | {
+        data: any;
+    } | {
+        id: any;
+        name: any;
+    };
+};
+export function getEnum(name: any): void;
+export function getEncoding(name: any): {
+    preencode(state: any, m: any): void;
+    encode(state: any, m: any): void;
+    decode(state: any): {
+        status: any;
+        reason: any;
+        key: any;
+        encryptionKey: any;
+        extra: any;
+    };
+} | {
+    preencode(state: any, m: any): void;
+    encode(state: any, m: any): void;
+    decode(state: any): {
+        data: any;
+    };
+} | {
+    preencode(state: any, m: any): void;
+    encode(state: any, m: any): void;
+    decode(state: any): {
+        id: any;
+        name: any;
+    };
+} | {
+    preencode(state: any, m: any): void;
+    encode(state: any, m: any): void;
+    decode(state: any): {
+        hash: any;
+        coreKey: any;
+        blockOffset: any;
+        blockLength: any;
+        byteOffset: any;
+        byteLength: any;
+        size: any;
+        createdAt: any;
+        meta: any;
+    };
+};
+export function encode(name: any, value: any, v?: number): any;
+export function decode(name: any, buffer: any, v?: number): any;
+export function setVersion(v: any): void;
+export let version: number;

package/types/lib/utils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Generate a short opaque id (z32-encoded 16 random bytes).
+ *
+ * @returns {string}
+ */
+export function genId(): string;
+/**
+ * Stream-of-snapshots primitive. Couples a `get` (returns the latest value)
+ * with a `watch` (re-fires on change) and emits the newest snapshot every
+ * time `watch` ticks.
+ *
+ * @template T
+ * @param {object} args
+ * @param {() => Promise<T> | T} args.get
+ * @param {(fn: () => void) => (() => void) | void} args.watch  Returns an unsubscribe.
+ * @returns {import('streamx').Readable<T>}
+ */
+export function subscribe<T>({ get, watch }: {
+    get: () => Promise<T> | T;
+    watch: (fn: () => void) => (() => void) | void;
+}): any;
+/**
+ * z32-encode a 32-byte key into a canonical string id.
+ *
+ * @type {(key: Uint8Array) => string}
+ */
+export const toId: (key: Uint8Array) => string;
+/**
+ * Decode a canonical string id back into a 32-byte key.
+ *
+ * @type {(id: string) => Uint8Array}
+ */
+export const toKey: (id: string) => Uint8Array;
+/**
+ * Test whether a string is a well-formed canonical id.
+ *
+ * @type {(id: string) => boolean}
+ */
+export const isKeyId: (id: string) => boolean;

package/types/network/discovery.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Handle for a single topic membership on a {@link Network}. Wraps a hyperswarm
+ * PeerDiscovery session and lets it switch between active/passive announce/lookup.
+ */
+export class Discovery {
+    /**
+     * @param {import('./index.js').Network} network  Owning network.
+     * @param {any} session  Hyperswarm PeerDiscovery session from `swarm.join()`.
+     * @param {'active' | 'passive'} mode
+     */
+    constructor(network: import("./index.js").Network, session: any, mode: "active" | "passive");
+    network: import("./index.js").Network;
+    session: any;
+    _mode: "active" | "passive";
+    _destroyed: boolean;
+    /** @returns {'active' | 'passive'} */
+    get mode(): "active" | "passive";
+    /** @returns {boolean} */
+    get destroyed(): boolean;
+    /**
+     * Switch to active (client+server) announce/lookup.
+     *
+     * @returns {Promise<void>}
+     */
+    activate(): Promise<void>;
+    /**
+     * Switch to passive announce.
+     *
+     * @returns {Promise<void>}
+     */
+    deactivate(): Promise<void>;
+    /**
+     * Wait for the current announce/lookup to settle.
+     *
+     * @returns {Promise<void>}
+     */
+    flush(): Promise<void>;
+    /**
+     * Leave the topic and tear down the session. Idempotent.
+     *
+     * @returns {Promise<void>}
+     */
+    destroy(): Promise<void>;
+}

package/types/network/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @typedef {object} NetworkOpts
+ * @property {import('../identity/index.js').Identity} [identity]  Long-lived keypair used as the swarm identity.
+ * @property {Array<{ host: string, port: number }>} [bootstrap]    Custom DHT bootstrap nodes.
+ * @property {(remotePublicKey: Uint8Array, payload: any) => boolean} [firewall]  Incoming-connection filter.
+ * @property {Uint8Array[]} [relayThrough]                          Relay public keys to tunnel through.
+ *
+ * @typedef {{ replicate: (stream: any) => any }} Replicable
+ */
+/**
+ * Hyperswarm peer-discovery + replication multiplexer. Wraps a swarm and a
+ * shared wakeup channel, replicating any attached resource onto every peer.
+ */
+export class Network extends ReadyResource {
+    /** @param {NetworkOpts} [opts] */
+    constructor({ identity, bootstrap, firewall, relayThrough }?: NetworkOpts);
+    identity: import("../index.js").Identity;
+    bootstrap: {
+        host: string;
+        port: number;
+    }[];
+    firewall: (remotePublicKey: Uint8Array, payload: any) => boolean;
+    relayThrough: Uint8Array<ArrayBufferLike>[];
+    swarm: any;
+    wakeup: any;
+    _replicateables: Set<any>;
+    _discoveries: Set<any>;
+    /** @returns {Map<string, any>} Known peers keyed by public-key string. */
+    get peers(): Map<string, any>;
+    /** @returns {Set<any>} Live connection streams. */
+    get connections(): Set<any>;
+    /** @returns {boolean} */
+    get suspended(): boolean;
+    /**
+     * Wait for pending DHT announces and lookups to settle, bounded by timeout.
+     *
+     * @param {{ timeout?: number }} [opts]
+     * @returns {Promise<void>}
+     */
+    flush({ timeout }?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Pause the swarm — keeps state, drops sockets. Idempotent.
+     *
+     * @returns {Promise<void>}
+     */
+    suspend(): Promise<void>;
+    /**
+     * Resume a suspended swarm. Idempotent.
+     *
+     * @returns {Promise<void>}
+     */
+    resume(): Promise<void>;
+    /**
+     * Announce/lookup on a 32-byte topic and return a Discovery handle.
+     *
+     * @param {Uint8Array} topic
+     * @param {{ mode?: 'active' | 'passive' }} [opts]  `active` = client+server, `passive` = server-only
+     * @returns {Discovery}
+     */
+    join(topic: Uint8Array, { mode }?: {
+        mode?: "active" | "passive";
+    }): Discovery;
+    /**
+     * Register a replicable resource (hypercore, autobee, hyperdb).
+     * It is replicated on every current and future swarm connection.
+     *
+     * @param {Replicable} core
+     * @returns {void}
+     */
+    attach(core: Replicable): void;
+    /**
+     * Unregister a previously attached resource. New connections will no
+     * longer replicate it (existing replication streams continue).
+     *
+     * @param {Replicable} core
+     * @returns {void}
+     */
+    detach(core: Replicable): void;
+    /**
+     * Replicate a one-off resource onto every current swarm connection
+     * without registering it as a long-lived attachment.
+     *
+     * @param {Replicable} target
+     * @returns {void}
+     */
+    replicate(target: Replicable): void;
+}
+export type NetworkOpts = {
+    /**
+     * Long-lived keypair used as the swarm identity.
+     */
+    identity?: import("../identity/index.js").Identity;
+    /**
+     * Custom DHT bootstrap nodes.
+     */
+    bootstrap?: Array<{
+        host: string;
+        port: number;
+    }>;
+    /**
+     * Incoming-connection filter.
+     */
+    firewall?: (remotePublicKey: Uint8Array, payload: any) => boolean;
+    /**
+     * Relay public keys to tunnel through.
+     */
+    relayThrough?: Uint8Array[];
+};
+export type Replicable = {
+    replicate: (stream: any) => any;
+};
+import ReadyResource from 'ready-resource';
+import { Discovery } from './discovery.js';

package/types/pairing/index.d.ts

@@ -0,0 +1,194 @@
+/**
+ * @typedef {object} PairingOpts
+ * @property {import('../network/index.js').Network} network         Network to host the BlindPairing member.
+ * @property {import('../identity/index.js').Identity} identity      Identity used to sign invites and derive the topic.
+ * @property {Uint8Array} [topic]                                    Optional override topic; defaults to `identity.publicKey`.
+ * @property {any} [inviteEncoding]                                  compact-encoding type for the invite payload `data`.
+ * @property {any} [joinerEncoding]                                  compact-encoding type for the joiner-supplied `userData`.
+ *
+ * @typedef {object} CreateInviteOpts
+ * @property {string} [role]                                         Role tag bound into the invite.
+ * @property {number} [expiresIn]                                    TTL in ms; `0`/omitted = no expiry.
+ * @property {any} [data]                                            Arbitrary payload (encoded via `inviteEncoding` when set).
+ *
+ * @typedef {object} JoinOpts
+ * @property {any} [userData]                                        Payload sent with the candidate request.
+ * @property {number} [timeout]                                      Deadline for the handshake, in ms. Defaults to 30000.
+ *
+ * @typedef {object} ConfirmOpts
+ * @property {Uint8Array} [key]                                      32-byte resource key delivered to the joiner; required at runtime.
+ * @property {Uint8Array | null} [encryptionKey]                     Optional 32-byte symmetric key.
+ * @property {Uint8Array | null} [additional]                        Extra opaque bytes piggybacked on the response.
+ *
+ * @typedef {{ key: Uint8Array, encryptionKey: Uint8Array | null, additional: Uint8Array | null }} JoinResult
+ *
+ * @typedef {object} CandidateOpts
+ * @property {Pairing} pairing                                       Owning Pairing instance.
+ * @property {any} req                                               blind-pairing candidate request being answered.
+ * @property {Invite} invite                                         Invite the candidate paired against.
+ * @property {Uint8Array} seed                                       Per-invite seed used to sign the response.
+ * @property {any} userData                                          Decoded joiner payload (raw bytes when no encoding).
+ * @property {() => void} onsettle                                   Called once when the candidate is confirmed or denied.
+ */
+/**
+ * Blind-pairing membership wrapper. Hosts invites, dispatches incoming
+ * candidates to the application for accept/deny, and provides the joiner
+ * side of the handshake. All wire payloads are signed and routed through
+ * the supplied network.
+ */
+export class Pairing extends ReadyResource {
+    /**
+     * Cheap structural test for a candidate invite string.
+     *
+     * @param {unknown} str
+     * @returns {boolean}
+     */
+    static isInvite(str: unknown): boolean;
+    /** @param {PairingOpts} [opts] */
+    constructor({ network, identity, topic, inviteEncoding, joinerEncoding }?: PairingOpts);
+    network: import("../index.js").Network;
+    identity: import("../index.js").Identity;
+    topic: Uint8Array<ArrayBufferLike>;
+    inviteEncoding: any;
+    joinerEncoding: any;
+    _blind: any;
+    _member: any;
+    _invites: Map<any, any>;
+    _candidates: Set<any>;
+    /**
+     * Mint a new pairing invite. Returns its canonical wire form (z32 string).
+     *
+     * @param {CreateInviteOpts} [opts]
+     * @returns {Promise<string>}
+     */
+    createInvite({ role, expiresIn, data }?: CreateInviteOpts): Promise<string>;
+    /**
+     * Forget a previously-minted invite. New candidates carrying it will be
+     * dropped silently.
+     *
+     * @param {string} inviteStr
+     * @returns {boolean}
+     */
+    revoke(inviteStr: string): boolean;
+    /**
+     * Joiner side — start a pairing handshake against `inviteStr` and resolve
+     * with the host's response when the host confirms.
+     *
+     * @param {string} inviteStr
+     * @param {JoinOpts} [opts]
+     * @returns {Promise<JoinResult>}
+     */
+    join(inviteStr: string, { userData, timeout }?: JoinOpts): Promise<JoinResult>;
+    /**
+     * Whether the underlying blind-pairing layer is suspended.
+     *
+     * @returns {boolean}
+     */
+    get suspended(): boolean;
+    /**
+     * Pause blind-pairing — keeps state, drops sockets. Idempotent.
+     *
+     * @returns {Promise<void>}
+     */
+    suspend(): Promise<void>;
+    /**
+     * Resume a suspended blind-pairing layer. Idempotent.
+     *
+     * @returns {Promise<void>}
+     */
+    resume(): Promise<void>;
+    _onCandidate(req: any): Promise<void>;
+}
+export type PairingOpts = {
+    /**
+     * Network to host the BlindPairing member.
+     */
+    network: import("../network/index.js").Network;
+    /**
+     * Identity used to sign invites and derive the topic.
+     */
+    identity: import("../identity/index.js").Identity;
+    /**
+     * Optional override topic; defaults to `identity.publicKey`.
+     */
+    topic?: Uint8Array;
+    /**
+     * compact-encoding type for the invite payload `data`.
+     */
+    inviteEncoding?: any;
+    /**
+     * compact-encoding type for the joiner-supplied `userData`.
+     */
+    joinerEncoding?: any;
+};
+export type CreateInviteOpts = {
+    /**
+     * Role tag bound into the invite.
+     */
+    role?: string;
+    /**
+     * TTL in ms; `0`/omitted = no expiry.
+     */
+    expiresIn?: number;
+    /**
+     * Arbitrary payload (encoded via `inviteEncoding` when set).
+     */
+    data?: any;
+};
+export type JoinOpts = {
+    /**
+     * Payload sent with the candidate request.
+     */
+    userData?: any;
+    /**
+     * Deadline for the handshake, in ms. Defaults to 30000.
+     */
+    timeout?: number;
+};
+export type ConfirmOpts = {
+    /**
+     * 32-byte resource key delivered to the joiner; required at runtime.
+     */
+    key?: Uint8Array;
+    /**
+     * Optional 32-byte symmetric key.
+     */
+    encryptionKey?: Uint8Array | null;
+    /**
+     * Extra opaque bytes piggybacked on the response.
+     */
+    additional?: Uint8Array | null;
+};
+export type JoinResult = {
+    key: Uint8Array;
+    encryptionKey: Uint8Array | null;
+    additional: Uint8Array | null;
+};
+export type CandidateOpts = {
+    /**
+     * Owning Pairing instance.
+     */
+    pairing: Pairing;
+    /**
+     * blind-pairing candidate request being answered.
+     */
+    req: any;
+    /**
+     * Invite the candidate paired against.
+     */
+    invite: Invite;
+    /**
+     * Per-invite seed used to sign the response.
+     */
+    seed: Uint8Array;
+    /**
+     * Decoded joiner payload (raw bytes when no encoding).
+     */
+    userData: any;
+    /**
+     * Called once when the candidate is confirmed or denied.
+     */
+    onsettle: () => void;
+};
+import ReadyResource from 'ready-resource';
+import { Invite } from './invite.js';

package/types/pairing/invite.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @typedef {object} InviteFields
+ * @property {Uint8Array} publicKey                 Signer's long-lived public key.
+ * @property {string} role                          Optional role tag baked into the signed body.
+ * @property {number} expires                       Absolute expiry timestamp; `0` means never.
+ * @property {Uint8Array | null} data               Encoded payload (raw or via `encoding`).
+ * @property {Uint8Array} blindInvite               Raw blind-pairing invite handed to candidates.
+ * @property {Uint8Array} [sig]                     Ed25519 signature over the canonical body.
+ * @property {string | null} [_str]                 Cached z32 string form.
+ *
+ * @typedef {object} CreateInviteOpts
+ * @property {Uint8Array} secretKey                 64-byte Ed25519 secret key used to sign.
+ * @property {Uint8Array} publicKey                 32-byte Ed25519 public key matching `secretKey`.
+ * @property {string} role                          Optional role tag for the joiner.
+ * @property {number} expiresIn                     TTL in ms from now; `0` means never expires.
+ * @property {any} data                             Caller payload; encoded via `encoding` when provided.
+ * @property {Uint8Array} blindInvite               Raw blind-pairing invite to wrap.
+ * @property {any} [encoding]                       compact-encoding type used to encode `data`.
+ *
+ * @typedef {object} ParseInviteOpts
+ * @property {any} [encoding]                       compact-encoding type used to decode the embedded payload.
+ */
+/**
+ * Signed, expirable pairing invite. Wraps a blind-pairing invite with a
+ * role, optional payload and an Ed25519 signature so the host can be
+ * authenticated by the joiner before any handshake happens.
+ *
+ * @property {any} [_rawData]                         Decoded payload kept alongside the encoded `data` for convenience.
+ * @property {any} _blind                             Lazily-decoded blind-pairing invite view (cache).
+ */
+export class Invite {
+    /**
+     * Build and sign a new invite envelope wrapping a blind-pairing invite.
+     *
+     * @param {CreateInviteOpts} opts
+     * @returns {Invite}
+     */
+    static create({ secretKey, publicKey, role, expiresIn, data, blindInvite, encoding }: CreateInviteOpts): Invite;
+    /**
+     * Parse a z32 invite string, verify its signature and (optionally) decode
+     * its payload.
+     *
+     * @param {string} str
+     * @param {ParseInviteOpts} [opts]
+     * @returns {Invite}
+     */
+    static parse(str: string, { encoding }?: ParseInviteOpts): Invite;
+    /**
+     * Cheap structural test — does `str` decode as an invite envelope? Does not
+     * verify the signature.
+     *
+     * @param {unknown} str
+     * @returns {boolean}
+     */
+    static isInvite(str: unknown): boolean;
+    /** @param {InviteFields} fields */
+    constructor(fields: InviteFields);
+    version: number;
+    publicKey: Uint8Array<ArrayBufferLike>;
+    role: string;
+    expires: number;
+    data: Uint8Array<ArrayBufferLike>;
+    blindInvite: Uint8Array<ArrayBufferLike>;
+    sig: Uint8Array<ArrayBufferLike>;
+    _str: string;
+    _blind: any;
+    /**
+     * Whether the invite is past its TTL (always `false` when `expires === 0`).
+     *
+     * @returns {boolean}
+     */
+    get expired(): boolean;
+    /**
+     * Lazily-decoded view of the underlying blind-pairing invite.
+     *
+     * @returns {any}
+     */
+    get blind(): any;
+    /**
+     * Verify the embedded signature against the encoded body.
+     *
+     * @returns {boolean}
+     */
+    verify(): boolean;
+    /**
+     * Serialise to the canonical z32 wire form (cached).
+     *
+     * @returns {string}
+     */
+    toString(): string;
+}
+export type InviteFields = {
+    /**
+     * Signer's long-lived public key.
+     */
+    publicKey: Uint8Array;
+    /**
+     * Optional role tag baked into the signed body.
+     */
+    role: string;
+    /**
+     * Absolute expiry timestamp; `0` means never.
+     */
+    expires: number;
+    /**
+     * Encoded payload (raw or via `encoding`).
+     */
+    data: Uint8Array | null;
+    /**
+     * Raw blind-pairing invite handed to candidates.
+     */
+    blindInvite: Uint8Array;
+    /**
+     * Ed25519 signature over the canonical body.
+     */
+    sig?: Uint8Array;
+    /**
+     * Cached z32 string form.
+     */
+    _str?: string | null;
+};
+export type CreateInviteOpts = {
+    /**
+     * 64-byte Ed25519 secret key used to sign.
+     */
+    secretKey: Uint8Array;
+    /**
+     * 32-byte Ed25519 public key matching `secretKey`.
+     */
+    publicKey: Uint8Array;
+    /**
+     * Optional role tag for the joiner.
+     */
+    role: string;
+    /**
+     * TTL in ms from now; `0` means never expires.
+     */
+    expiresIn: number;
+    /**
+     * Caller payload; encoded via `encoding` when provided.
+     */
+    data: any;
+    /**
+     * Raw blind-pairing invite to wrap.
+     */
+    blindInvite: Uint8Array;
+    /**
+     * compact-encoding type used to encode `data`.
+     */
+    encoding?: any;
+};
+export type ParseInviteOpts = {
+    /**
+     * compact-encoding type used to decode the embedded payload.
+     */
+    encoding?: any;
+};

package/types/rpc/client.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Client-side RPC adapter. Mirror of `RPCServer` — wraps an IPC duplex
+ * in a length-framed stream and constructs the spec's hrpc binding ready
+ * to issue requests. Frames are paused until `_open` runs so handlers
+ * registered before `ready()` see a clean slate.
+ */
+export class RPCClient extends ReadyResource {
+    /**
+     * @param {any} ipc                                Duplex IPC stream (e.g. a socket or pipe).
+     * @param {import('./index.js').Spec} spec         Spec object exposing `rpc` and `schema`.
+     */
+    constructor(ipc: any, spec: import("./index.js").Spec);
+    ipc: any;
+    spec: import("./index.js").Spec;
+    framed: any;
+    rpc: any;
+}
+import ReadyResource from 'ready-resource';