@swal/edge-mesh 0.0.0-stage → 0.1.0

package/dist/web/secstate.d.ts

@@ -0,0 +1,213 @@
+import { isEpoch, type Role, type TrustRoot } from "./admission.js";
+import { type RotDoc } from "./rotation.js";
+import type { MeshStore } from "./store.js";
+import { type Signer } from "./trust/keys.js";
+import { type TrustStore } from "./trust/store.js";
+import type { Grant, Revocation, TrustSchema } from "./trust/types.js";
+/** Module every mesh grant names (apps may add their own modules to the schema). */
+export declare const MESH_MODULE = "mesh";
+export declare const MESH_SCHEMA: TrustSchema;
+/** A device's key-agreement keys (rotation wraps), signed by the device's own ML-DSA-65 identity key. */
+export interface KexDoc {
+    t: "kex";
+    v: 1;
+    inst: string;
+    dev: string;
+    /** raw P-256 public key, base64url */
+    ecdh: string;
+    /** ML-KEM-768 encapsulation key, base64url */
+    kem: string;
+    /** the device's own counter: the highest one wins (a device that changes its keys publishes n + 1) */
+    n: number;
+    sig: string;
+}
+export type SecDoc = Grant | Revocation | KexDoc | RotDoc;
+export interface AddOutcome {
+    status: "accepted" | "duplicate" | "pending" | "rejected";
+    id?: string;
+    reason?: string;
+}
+/** Members an admin's grants can make (its lowest grant ids count; R5-S3: an admin cannot flood the recipient list). */
+export declare const MAX_MEMBERS_PER_ADMIN = 256;
+/** Grants of one non-root issuer kept at all (beyond: the cap-N smallest ids are kept, see `applyCap`). */
+export declare const MAX_STORED_PER_ISSUER: number;
+/** Revocations of one target grant by one issuer kept (beyond: the cap-N smallest ids are kept, see `applyCap`). */
+export declare const MAX_REVS_PER_ISSUER_TARGET = 4;
+/** Recent owner rotations kept in full (with their wraps) to serve stragglers; their cuts are kept for good. */
+export declare const MAX_ROTATIONS_KEPT = 32;
+/** R6-S5: a count alone does not bound memory: one deferred document may carry a large `upTo`/wrap list. */
+export declare const MAX_DOC_BYTES: number;
+/** R6-S5: total bytes held by deferred documents (the auditor measured 126 MiB from 64 deferred revocations). */
+export declare const MAX_DEFERRED_BYTES: number;
+export interface MemberInfo {
+    deviceId: string;
+    pub: string;
+    role: Exclude<Role, "owner">;
+    grant: Grant;
+}
+export declare class SecurityState {
+    readonly trust: TrustStore;
+    readonly root: TrustRoot;
+    private readonly store;
+    private readonly now;
+    private readonly kex;
+    private readonly rots;
+    private readonly cuts;
+    /** inventory: keys of every document held */
+    private readonly have;
+    /** keys of documents dropped for good (superseded key records, pruned rotations): never asked for again */
+    private readonly gone;
+    /** hashes of whole documents that failed verification (a forged copy never blocks the genuine one) */
+    private readonly bad;
+    /** R6-B1: documents waiting for their parent/target, by the hash of the WHOLE document (never by the id it claims) */
+    private readonly deferred;
+    /** R6-S2b: who sent each parked document, so the retry charges that sender's waiting slots and not the parent's. */
+    private readonly deferredFrom;
+    /** R6-S5: bytes held by `deferred` (kept exact: every set and every drop goes through defer/unpark) */
+    private deferredBytesHeld;
+    private readonly listeners;
+    private queue;
+    private capIndex;
+    version: number;
+    private constructor();
+    static open(o: {
+        root: TrustRoot;
+        store: MeshStore;
+        schema?: TrustSchema;
+        now?: () => number;
+    }): Promise<SecurityState>;
+    get inst(): string;
+    onChange(cb: () => void): () => void;
+    /**
+     * Add documents (any order, any source). Serialized; listeners fire once when anything was accepted.
+     * `opts.from` (R6-S2b) is the transport-level id of the peer that sent them: the trust store charges the waiting
+     * slots they park to that sender, so one peer cannot take the whole waiting set by signing with fresh random keys.
+     * Leave it undefined for local/own documents (a pair's own, ours, restored from storage): no sender is charged.
+     */
+    addMany(xs: readonly unknown[], opts?: {
+        from?: string;
+    }): Promise<AddOutcome[]>;
+    add(x: unknown): Promise<AddOutcome>;
+    private ingest;
+    /**
+     * Park a document until its parent/target arrives. Returns a reason if it was dropped instead.
+     * R6-B1: keyed by the hash of the WHOLE document received, never by the id it claims, so a forged copy parked under
+     * somebody else's id can neither shadow the genuine one nor take its key out of `missing()`.
+     * R6-S2b: remembers which peer sent it, so the retry charges that sender's waiting slots and not the parent's.
+     */
+    private defer;
+    /** Drop a parked document and give its bytes back. */
+    private unpark;
+    /** Bytes held by parked documents (R6-S5 accounting). */
+    deferredBytes(): number;
+    private retryDeferred;
+    private ingestTrust;
+    /**
+     * R6-S4 (order-independent caps). A cap used to be "the first N that arrive are kept", so two devices holding the
+     * same documents concluded different things: different revocations kept give a different seq cut-off, and different
+     * grants kept give a different membership. The rule is now on the set, not on the arrival order: for each bucket
+     * (grants per issuer, revocations per (issuer, target)) the kept documents are the cap-N ones with the SMALLEST
+     * content address, and a document arriving with a smaller address evicts the largest kept one. Keeping the smallest
+     * ids is incremental (each arrival leaves the cap-N smallest of everything seen so far), so every device ends with
+     * the same set whatever the order, and it agrees with the existing `withinCap` rule for members.
+     * Returns true when the document just accepted is itself the one pushed out.
+     */
+    private applyCap;
+    /** Identity key of a device: the root's, or the subject key of any of its grants (revoked ones too). */
+    identityOf(dev: string): string | undefined;
+    private ingestKex;
+    private ingestRot;
+    private saving;
+    private dirty;
+    /** Persist, coalesced: at most one write in flight and one more queued. */
+    private scheduleSave;
+    /** Resolves once everything accepted so far is in the local store. */
+    flush(): Promise<void>;
+    private save;
+    private load;
+    /** Grant ids executed by an owner rotation (authoritative cuts). */
+    isCut(grantId: string): boolean;
+    executedCuts(): string[];
+    private chainOf;
+    /** The grant was cut off by an owner rotation (itself or an ancestor: revocations cascade). */
+    private executed;
+    /** R5-S3: an admin's grants count up to MAX_MEMBERS_PER_ADMIN (its lowest grant ids: the same on every device). */
+    private withinCap;
+    /** The grant that makes `dev` a member now (best role), or null. Never null for the root (its own authority). */
+    memberGrant(dev: string): Grant | null;
+    roleOf(dev: string): Role | null;
+    /** Every device with a grant (members and former members), except the root. */
+    knownDevices(): string[];
+    /**
+     * Results of the whole-set queries. Valid while no document is added (both counters unchanged)
+     * AND within the same second: membership depends on the clock (grants expire / start), so a
+     * cache keyed only on versions would keep an expired member listed until the next document.
+     */
+    private memo;
+    private memoFor;
+    members(): MemberInfo[];
+    private computeMembers;
+    /** Has grants, none of which makes it a member any more. */
+    isOut(dev: string): boolean;
+    /**
+     * R5-B2: devices that lost membership through a revocation the owner has not executed yet: whoever they are, and
+     * whenever they were paired, they may hold the current key. Executed = cut by an owner rotation (itself or an
+     * ancestor). Returns the devices, the grant ids to cut and the revocation documents behind them.
+     */
+    unexecuted(only?: ReadonlySet<string>): {
+        devices: string[];
+        cut: string[];
+        revs: string[];
+    };
+    private computeUnexecuted;
+    /** Best key-agreement record of a device (root or one with a grant). */
+    keyAgreement(dev: string): {
+        ecdh: string;
+        kem: string;
+    } | null;
+    kexDoc(dev: string): KexDoc | null;
+    rotations(): Array<RotDoc & {
+        id: string;
+    }>;
+    rotation(id: string): (RotDoc & {
+        id: string;
+    }) | undefined;
+    inventory(): string[];
+    /**
+     * Keys among `ids` this device does not hold (nor dropped for good, nor knows to be bad).
+     * R6-B1: parked documents do NOT hide a key. Only a VERIFIED (accepted) document with that id stops it from being
+     * asked for again: otherwise one forged copy parked under an id withholds the genuine one from every peer.
+     */
+    missing(ids: readonly unknown[]): string[];
+    get(keys: readonly string[]): Promise<SecDoc[]>;
+    /** Grant for `subjectPub` signed by `signer` (the root, or a member whose own grant may delegate). */
+    issueGrant(signer: Signer, subjectPub: string, o: {
+        role: "admin" | "member";
+        name?: string;
+        epoch?: number;
+        permissions?: Record<string, "ver" | "editar" | "administrar">;
+        now?: number;
+    }): Promise<Grant>;
+    /**
+     * Revocations of every grant of `target` that `signer` may revoke (root: all of them; an admin: those it issued,
+     * directly or below). `heads` (web/oplog `headIds()`) keep the target's history up to there; omitted = none kept.
+     */
+    revocationsFor(signer: Signer, target: string, o?: {
+        heads?: Readonly<Record<string, number | {
+            seq: number;
+            id: string;
+        }>>;
+        reason?: string;
+        now?: number;
+    }): Promise<Revocation[]>;
+    /** This device's own key-agreement record (counter `n` above every record of it seen so far). */
+    kexRecord(signer: Signer, ecdh: string, kem: string): Promise<KexDoc>;
+}
+/** A web/trust Signer over a mesh vault (ML-DSA-65 identity key). */
+export declare function vaultSigner(v: {
+    deviceId: string;
+    devicePublicKey: Uint8Array;
+    sign(d: Uint8Array): Promise<Uint8Array>;
+}, pubB64: string): Signer;
+export { isEpoch };
+//# sourceMappingURL=secstate.d.ts.map

package/dist/web/secstate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secstate.d.ts","sourceRoot":"","sources":["../../src/web/secstate.ts"],"names":[],"mappings":"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"}