@real-life/trust-protocol 0.3.2 → 0.4.0

package/dist/adapters/vti-mediator.d.ts

@@ -0,0 +1,154 @@
+import type { CarrierPrincipal, CarrierScopedIdentity } from '../carrier-identity.js';
+import type { DeliveryReport, Outbound, ReceiverRefusalCode, SubmissionRef } from '../ports.js';
+export type { ReceiverRefusalCode } from '../ports.js';
+export declare const DECLARED: {
+    readonly giveUpHorizonMs: number;
+    readonly statusHorizonMs: 60000;
+    readonly queueFloorCount: 64;
+    readonly queueFloorBytes: 1048576;
+    readonly maxQueueBytes: 16777216;
+    readonly duplicateWindowMs: number;
+};
+export type WireErrorKind = 'unreachable' | 'refused-retriable' | 'refused-admission' | 'oversize';
+export declare class WireError extends Error {
+    kind: WireErrorKind;
+    constructor(kind: WireErrorKind, message?: string);
+}
+export interface MediatorWire {
+    authChallenge(did: string): Promise<{
+        challenge: string;
+        sessionId: string;
+    }>;
+    authenticate(answer: {
+        did: string;
+        challenge: string;
+        sessionId: string;
+    }): Promise<TokenSet>;
+    refresh(refreshToken: string): Promise<TokenSet>;
+    keylistUpdate(accessToken: string, rkids: string[]): Promise<void>;
+    deposit(accessToken: string, bytes: Uint8Array, egressDid: string): Promise<void>;
+    ackReceived(accessToken: string, queueIds: string[]): Promise<void>;
+    onDeliver(cb: (bytes: Uint8Array) => Promise<void>): void;
+    /** Optional truthful connectivity signal; absent means unknown. */
+    offline?(): boolean;
+}
+export interface TokenSet {
+    accessToken: string;
+    accessExpiresAt: number;
+    refreshToken: string;
+    refreshExpiresAt: number;
+}
+export type SubmissionState = {
+    state: 'awaiting-transport';
+    reason: 'offline' | 'transport-unreachable' | 'carrier-refused-retriable';
+} | {
+    state: 'accepted';
+} | {
+    state: 'delivered';
+    late: boolean;
+} | {
+    state: 'failed';
+    reason: 'unroutable' | 'oversize' | 'expired-by-adapter-policy';
+} | {
+    state: 'failed';
+    reason: 'rejected-by-receiver';
+    code: ReceiverRefusalCode;
+};
+/** The ports' DeliveryReport for a document `digest` in adapter state `st`
+ *  (Delivery §6.1): one-to-one, `late` and the refusal code carried over. */
+export declare function deliveryReportOf(digest: string, st: SubmissionState): DeliveryReport;
+export interface CollectedItem {
+    bytes: Uint8Array;
+    queueId: string;
+}
+export interface Collection {
+    id: string;
+    items: CollectedItem[];
+}
+/** Ack state for the host to persist (profile §4). Invariant: every
+ *  pending id names a concluded entry; violations are refused at
+ *  construction (fail-closed). */
+export interface AckState {
+    concluded: Array<{
+        queueId: string;
+        concludedAt: number;
+    }>;
+    pending: string[];
+}
+export declare class MediatorCarrierAdapter {
+    #private;
+    get principal(): string;
+    get connectionDid(): string;
+    get egressDid(): string;
+    /** The only way to build an adapter: the trio is DERIVED here from
+     *  one root, one carrier, one nonce — so principal, connection DID
+     *  and egress identity cannot come from different relationships
+     *  (R7-B2: the coupling is enforced by construction, not by
+     *  inspecting caller-supplied identities). */
+    static create(rootIkm: Uint8Array, carrier: string, nonce: Uint8Array, wire: MediatorWire, restored?: AckState, restoredAt?: number): Promise<MediatorCarrierAdapter>;
+    constructor(key: symbol, principal: CarrierPrincipal, connection: CarrierScopedIdentity, egress: CarrierScopedIdentity, wire: MediatorWire, restored?: AckState, restoredAt?: number);
+    /** Records the desired keylist and returns; synchronization runs
+     *  as a tracked background task and advance retries it until it
+     *  lands (review-4 B1). */
+    register(rkids: string[], rawNow: number): void;
+    get keylistSynced(): boolean;
+    /** Returns the submission id synchronously. Before the first
+     *  honest report exists, status() returns null — §6.1's own
+     *  pre-report window, represented as absence, not as a value. */
+    submit(envelopeBytes: Uint8Array, rawNow: number): string;
+    /** Files an Outbound (its envelope as JCS bytes) and returns the
+     *  SubmissionRef the holder's reports are keyed by: submission id ↔
+     *  document digest (note §4.3). */
+    submitOutbound(outbound: Pick<Outbound, 'digest' | 'envelope'>, rawNow: number): SubmissionRef;
+    /** The current state as the ports' DeliveryReport for holder.report(),
+     *  or null while no honest report exists (and for an unknown id). A
+     *  submission filed without a digest (submit) has no report form. */
+    report(id: string): DeliveryReport | null;
+    has(id: string): boolean;
+    /** Host teardown aid, NOT a port operation (profile §6): awaits
+     *  the in-flight background tasks so a host can drain before
+     *  persisting ackState. On a hanging wire it waits as long as the
+     *  wire does — a host bounds it externally (Promise.race) exactly
+     *  because this library holds no clock of its own. */
+    settle(): Promise<void>;
+    /** The §6.1 report, or null while none exists yet (has()
+     *  distinguishes an unknown id). status is a PORT: after close it
+     *  refuses like every other port operation (R5-B3).
+     *
+     *  The pre-transport report is an HONEST SNAPSHOT, derived at the
+     *  moment of observation by one precedence order (Option B of the
+     *  round-14 halt) — never a stored patchwork:
+     *    (a) the wire knows itself offline      → offline
+     *    (b) an attempt is overdue              → transport-unreachable
+     *    (c) the last completed attempt's kind  → its report
+     *    (d) otherwise                          → no report yet (null)
+     *  Terminal states and `accepted` are stored and stand. */
+    status(id: string): SubmissionState | null;
+    acknowledged(id: string): void;
+    /** Refusals act on live submissions only (§6.1 knows exactly one
+     *  late correction — the valid ack). The code set is closed and
+     *  TERMINAL: retryable counterpart conditions (unavailable,
+     *  internalError) are transport outcomes, never receiver verdicts
+     *  — they have no entry here, and an unknown code is refused
+     *  fail-closed rather than minted into a verdict (R6-B2). */
+    receiverRefused(id: string, code: ReceiverRefusalCode): void;
+    drainTransitions(): Array<{
+        id: string;
+        to: 'delivered';
+    }>;
+    collect(rawNow: number): Collection;
+    conclude(collection: {
+        id: string;
+    }, rawNow: number): void;
+    ackState(): AckState;
+    advance(rawNow: number): void;
+    /** §5a.10 lifecycle boundary: after close, every state port is
+     *  inert — port operations refuse, inbound reports (acknowledged,
+     *  receiverRefused) are no-ops, late wire resolutions mutate
+     *  nothing. Only ackState() stays readable for the host's final
+     *  persist. */
+    close(): void;
+    get closed(): boolean;
+}
+export declare const queueIdOf: (bytes: Uint8Array) => Promise<string>;
+//# sourceMappingURL=vti-mediator.d.ts.map

package/dist/adapters/vti-mediator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vti-mediator.d.ts","sourceRoot":"","sources":["../../src/adapters/vti-mediator.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC/F,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAGtD,eAAO,MAAM,QAAQ;;;;;;;CAOX,CAAA;AAGV,MAAM,MAAM,aAAa,GACrB,aAAa,GAAG,mBAAmB,GAAG,mBAAmB,GAAG,UAAU,CAAA;AAE1E,qBAAa,SAAU,SAAQ,KAAK;IAClC,IAAI,EAAE,aAAa,CAAA;gBACN,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,MAAM;CAInD;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,CAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC9E,YAAY,CAAE,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAI/F,OAAO,CAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IACjD,aAAa,CAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnE,OAAO,CAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClF,WAAW,CAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpE,SAAS,CAAE,EAAE,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC1D,mEAAmE;IACnE,OAAO,CAAC,IAAK,OAAO,CAAA;CACrB;AAED,MAAM,WAAW,QAAQ;IACvB,WAAW,EAAE,MAAM,CAAA;IACnB,eAAe,EAAE,MAAM,CAAA;IACvB,YAAY,EAAE,MAAM,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AASD,MAAM,MAAM,eAAe,GACvB;IAAE,KAAK,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,SAAS,GAAG,uBAAuB,GAAG,2BAA2B,CAAA;CAAE,GAC1G;IAAE,KAAK,EAAE,UAAU,CAAA;CAAE,GACrB;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GACrC;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,YAAY,GAAG,UAAU,GAAG,2BAA2B,CAAA;CAAE,GACpF;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAC;IAAC,IAAI,EAAE,mBAAmB,CAAA;CAAE,CAAA;AAElF;6EAC6E;AAC7E,wBAAgB,gBAAgB,CAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,eAAe,GAAG,cAAc,CASrF;AAED,MAAM,WAAW,aAAa;IAAG,KAAK,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACrE,MAAM,WAAW,UAAU;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE;AAElE;;kCAEkC;AAClC,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC1D,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAmBD,qBAAa,sBAAsB;;IAOjC,IAAI,SAAS,IAAK,MAAM,CAA2B;IACnD,IAAI,aAAa,IAAK,MAAM,CAA+B;IAC3D,IAAI,SAAS,IAAK,MAAM,CAA2B;IA2BnD;;;;kDAI8C;WACjC,MAAM,CACjB,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EACvD,IAAI,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,EAAE,MAAM,GAC3D,OAAO,CAAC,sBAAsB,CAAC;gBAahC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,gBAAgB,EAC3B,UAAU,EAAE,qBAAqB,EACjC,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,YAAY,EAClB,QAAQ,CAAC,EAAE,QAAQ,EACnB,UAAU,CAAC,EAAE,MAAM;IAqIrB;;+BAE2B;IAC3B,QAAQ,CAAE,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAQhD,IAAI,aAAa,IAAK,OAAO,CAG5B;IAyBD;;qEAEiE;IACjE,MAAM,CAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAiB1D;;uCAEmC;IACnC,cAAc,CAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa;IAQ/F;;yEAEqE;IACrE,MAAM,CAAE,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAQ1C,GAAG,CAAE,EAAE,EAAE,MAAM,GAAG,OAAO;IAuCzB;;;;0DAIsD;IAChD,MAAM,IAAK,OAAO,CAAC,IAAI,CAAC;IAI9B;;;;;;;;;;;+DAW2D;IAC3D,MAAM,CAAE,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAe3C,YAAY,CAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAU/B;;;;;iEAK6D;IAC7D,eAAe,CAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,IAAI;IAgB7D,gBAAgB,IAAK,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,WAAW,CAAA;KAAE,CAAC;IAM3D,OAAO,CAAE,MAAM,EAAE,MAAM,GAAG,UAAU;IAapC,QAAQ,CAAE,UAAU,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAc3D,QAAQ,IAAK,QAAQ;IAkErB,OAAO,CAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IA8C9B;;;;mBAIe;IACf,KAAK,IAAK,IAAI;IAEd,IAAI,MAAM,IAAK,OAAO,CAAwB;CAC/C;AAED,eAAO,MAAM,SAAS,GAAU,OAAO,UAAU,KAAG,OAAO,CAAC,MAAM,CAA0B,CAAA"}