@hediet/linkrpc-hub 0.0.1

package/dist/chunks/index-CLIUrV88.d.ts

@@ -0,0 +1,481 @@
+import "./nodeTransit-cmtZgdpW.js";
+import { Et as Hub, Ot as IDisposable, Tt as AttachedLink } from "./hubConnectionAcceptor-BwydvFa4.js";
+import { AcceptedRootIssuer, Base64Sha256, Capability, IMessageTransport, Identity, Keypair, LinkRpcConnection, ManagedIdentityStorageBackend, Permission, PrincipalId, PublicSigningIdentity, SignedCapability, SigningIdentity, X25519Keypair } from "@hediet/linkrpc";
+import { ServiceId } from "@hediet/linkrpc/hub/common";
+//#region src/hub/server/routing/forwardingTable.d.ts
+/**
+ * A longest-prefix routing table keyed by {@link ServiceId} prefixes — the
+ * hub's equivalent of an IP forwarding table.
+ *
+ * A prefix `"a/b"` owns every serviceId equal to it or beneath it
+ * (`"a/b"`, `"a/b/c"`, …) *unless* a longer claimed prefix matches first.
+ * Matching is segment-aware: `"a/bc"` is **not** under `"a/b"`.
+ *
+ * The table is intentionally a plain stateful container with no opinion on
+ * *who* may claim what — that policy lives in {@link Hub.claimPrefix}. This
+ * keeps the data structure trivially testable in isolation.
+ */
+declare class ForwardingTable<T> {
+  private readonly _entries;
+  /**
+   * Reverse index: value → the set of prefixes claimed for it. Kept in
+   * lock-step with {@link _entries} so {@link deleteByValue} (used when a
+   * link detaches) is O(claims-for-that-value) instead of an O(size) scan.
+   */
+  private readonly _prefixesByValue;
+  /** Number of claimed prefixes. */
+  get size(): number;
+  has(prefix: ServiceId): boolean;
+  get(prefix: ServiceId): T | undefined;
+  /**
+   * Claim `prefix` for `value`. Overwrites any existing claim — callers
+   * that want claim-once semantics must check {@link has} first (the hub
+   * does).
+   */
+  set(prefix: ServiceId, value: T): void;
+  delete(prefix: ServiceId): boolean;
+  /**
+   * Remove every claim bound to `value` (matched by reference/equality).
+   * O(number of prefixes that value owns). Returns the removed prefixes.
+   */
+  deleteByValue(value: T): ServiceId[];
+  private _dropFromIndex;
+  entries(): IterableIterator<[ServiceId, T]>;
+  prefixes(): ServiceId[];
+  /**
+   * Find the value owning the longest claimed prefix of `serviceId`.
+   * Walks up the `'/'` segments — `"a/b/c"` tries `"a/b/c"`, `"a/b"`,
+   * `"a"` in that order — and returns the first hit, or `undefined` if
+   * none of its ancestors are claimed.
+   */
+  longestPrefixMatch(serviceId: ServiceId): {
+    prefix: ServiceId;
+    value: T;
+  } | undefined;
+}
+/**
+ * Validate a forwarding-table **prefix**: a non-root {@link ServiceId}. The
+ * root (`""`) is a valid service id but cannot be claimed as a prefix (it
+ * would capture every address); the uplink is the route of last resort
+ * instead. Returns an error string, or `undefined` when well-formed.
+ */
+declare function validatePrefix(prefix: unknown): string | undefined;
+//#endregion
+//#region src/hub/server/hubRegisterServiceId.d.ts
+/**
+ * Register an **in-process** service on `hub` under `serviceId`, returning a
+ * {@link RegisteredServiceId} whose `connection` serves its interfaces.
+ *
+ * This is the hubv2 replacement for the v1 `hub.attachParticipant(pair.a)` +
+ * `LinkRpcConnection.fromTransport(pair.b)` + `enableReflection({ serviceId })`
+ * dance that every built-in extension service performed. It:
+ *
+ * 1. attaches an in-memory link to the hub and claims `serviceId` on it, so
+ *    the hub routes every fully-qualified `serviceId::…` call to this service;
+ * 2. exposes a {@link LinkRpcConnection} whose registered interfaces answer
+ *    those calls (register them with `{ serviceId }`); and
+ * 3. enables reflection under `serviceId` so the hub's aggregating
+ *    `directory::list` surfaces this service.
+ *
+ * Disposing the returned handle (`svc.dispose()`) closes the connection and
+ * detaches the link, releasing the claimed prefix.
+ *
+ * Unlike an accepted *participant* (which gets a {@link RootOverlay} and only
+ * reaches the hub through its uplink), an in-process service is attached
+ * directly to the hub as a prefix owner. It is fully trusted — no provenance,
+ * identity, or forwarded-call gating applies to traffic it receives.
+ */
+declare function hubRegisterServiceId(hub: Hub, serviceId: ServiceId): RegisteredServiceId;
+/**
+ * Handle to an in-process service registered on a {@link Hub} via
+ * {@link hubRegisterServiceId}. Owns both the {@link LinkRpcConnection} the
+ * service serves its interfaces on and the hub {@link AttachedLink} that routes
+ * traffic to it. {@link dispose} closes the connection and detaches the link
+ * (releasing the claimed prefix) — wire it into the owning feature's disposal.
+ */
+declare class RegisteredServiceId implements IDisposable {
+  /** Serve the service's interfaces here (register them with `{ serviceId }`). */
+  readonly connection: LinkRpcConnection;
+  private readonly _link;
+  constructor(
+  /** Serve the service's interfaces here (register them with `{ serviceId }`). */
+  connection: LinkRpcConnection, _link: AttachedLink);
+  dispose(): void;
+}
+//#endregion
+//#region src/hub/server/mintCapability.d.ts
+interface MintCapabilityOptions {
+  /** The admin identity that issues (signs) the capability. */
+  readonly issuer: SigningIdentity;
+  /** The holder allowed to wield the capability. */
+  readonly audience: PrincipalId;
+  /** What the holder may do. A call matches iff it matches any permission. */
+  readonly permissions: readonly Permission[];
+  /** Unix milliseconds. Omit for a capability that never expires. */
+  readonly expiresAtMs?: number;
+  /**
+   * Per-cap distinguisher (base64url). Defaults to a fresh random 128-bit
+   * value.
+   */
+  readonly nonce?: string;
+  /** Delegation parent: the content hash (`signedHash("capability", parent)`) of the parent capability. */
+  readonly parentHash?: Base64Sha256<Capability>;
+}
+/**
+ * Assemble and sign a {@link Capability} with the admin identity.
+ *
+ * This replaces the v1 `hub.proposeCapability` / `signProposedCapability`
+ * pair: the consent engine decides the permissions (e.g. from
+ * {@link resolveAccessCandidates} + the user's consent selection) and mints
+ * the capability bound to the consumer's PrincipalId as `audience`.
+ */
+declare function mintCapability(options: MintCapabilityOptions): Promise<SignedCapability>;
+//#endregion
+//#region src/hub/server/verifiedSignature.d.ts
+/**
+ * Wrap an inbound transport so every request's `$hubrpc` signature is verified
+ * **eagerly, at the door** — a pure authenticity gate with no capability check:
+ *
+ * - a **valid** signature → the request is delivered unchanged;
+ * - an **invalid** signature → the request is **rejected** here (an error
+ *   response is sent and the message is never delivered);
+ * - an **unsigned** call (no envelope) → delivered unchanged, so keyless
+ *   connections still work.
+ *
+ * This is the signature half of the hub's trust model. *Authorization*
+ * (capability chains) is **not** this wrapper's job — that is enforced
+ * separately by {@link import('./forwardedCallGate').withForwardedCallGate} on
+ * the hub-facing (forwarded) path. The root overlay uses this wrapper on its own
+ * root-form calls (consent / identity front doors), which never pass through the
+ * forwarded-call gate and so need their authenticity established here.
+ *
+ * When `verifySignatures` is not `true`, the transport is returned unchanged (no
+ * verification, every message passes verbatim).
+ *
+ * Verification is async but in-order delivery is preserved via a per-link
+ * promise chain.
+ */
+declare function withVerifiedSignature(link: IMessageTransport, options?: {
+  readonly verifySignatures?: boolean;
+}): IMessageTransport;
+//#endregion
+//#region src/hub/server/forwardedCallGate.d.ts
+/** Options common to both gate modes (authenticity-only and capability). */
+interface ForwardedCallGateBaseOptions {
+  /**
+   * ServiceId prefixes whose calls pass **verbatim**, unverified — an
+   * opt-in escape hatch. **Empty by default**: reflection and forwarded
+   * service calls are gated like any other. The consent front door
+   * (`hubAccess::*`) is served at the connection root (never forwarded), so it
+   * is reached directly and never passes through this gate.
+   */
+  readonly exemptPrefixes?: Iterable<string>;
+  /** Override the clock (Unix milliseconds) used for skew / expiry checks. Testing seam. */
+  readonly nowMs?: () => number;
+}
+/**
+ * Per-service trust anchors, consulted with the call's `serviceId`. A
+ * capability authorises only if its chain roots at one of the anchors returned
+ * for that service, so a participant cannot self-issue authority. An empty
+ * result rejects every capability (fail closed) — there is deliberately no
+ * "accept any root" affordance. Anchors flagged `isPublic` are named in
+ * rejection messages.
+ */
+type AcceptedRootIssuerResolver = (serviceId: string) => readonly AcceptedRootIssuer[];
+/**
+ * Gate configuration. A **discriminated union on `requireCapability`** so the
+ * type system enforces the one combination that is actually safe:
+ *
+ * - **authenticity only** (`requireCapability` omitted / `false`): a valid
+ *   `$hubrpc` signature is enough; *authorization* is left to the target
+ *   service / capability layer. `acceptedRootIssuers` is optional here.
+ * - **capability mode** (`requireCapability: true`): a bare signature is not
+ *   enough — the request must also present a capability that {@link permits}
+ *   the concrete call, rooted at an accepted issuer. Because there is no safe
+ *   default trust anchor, either fixed `trustedRoots` or a service-specific
+ *   `acceptedRootIssuers` resolver is **required at compile time**. This makes
+ *   it impossible to request enforcement while silently forgetting whose
+ *   capabilities to trust.
+ */
+type ForwardedCallGateOptions = (ForwardedCallGateBaseOptions & {
+  readonly requireCapability?: false;
+  readonly acceptedRootIssuers?: AcceptedRootIssuerResolver;
+  readonly trustedRoots?: never;
+}) | (ForwardedCallGateBaseOptions & {
+  readonly requireCapability: true;
+} & ({
+  readonly acceptedRootIssuers: AcceptedRootIssuerResolver;
+  readonly trustedRoots?: never;
+} | {
+  /** Fixed public trust roots accepted for every forwarded service. */
+  readonly trustedRoots: readonly PublicSigningIdentity[];
+  readonly acceptedRootIssuers?: never;
+}));
+/**
+ * A **signature front door** for fully-qualified calls. Wrap an incoming
+ * transport with this before attaching it to a hub or constructing the serving
+ * connection, so every `serviceId::interfaceId::member` call must carry a
+ * valid `$hubrpc` signature.
+ * Unsigned or tampered calls are rejected with an error response and never
+ * reach the downstream hub or connection.
+ *
+ * What passes **verbatim** (ungated):
+ * - responses;
+ * - root-addressed requests (`interfaceId::member`) and bare requests
+ *   (`member`) — these always terminate at the connection root and are never
+ *   forwarded; and
+ * - requests targeting an {@link ForwardedCallGateOptions.exemptPrefixes exempt
+ *   prefix} (the hub's own services, which gate themselves).
+ *
+ * The gate **does not strip** the envelope: signed wire params keep the real
+ * call params at the top level alongside `$hubrpc`/`$hubrpcUnsigned`, so the
+ * target's typed handler recovers them via schema-stripping while a target that
+ * cares may re-verify as defense-in-depth. Authorization is *not* this gate's
+ * job (unless {@link ForwardedCallGateOptions.requireCapability} is set): it
+ * proves *who* is calling, leaving *whether they may* to the capability layer.
+ *
+ * In-order delivery toward the hub is preserved across the async verification:
+ * inbound messages are processed through a single serial queue.
+ */
+declare function withForwardedCallGate(inner: IMessageTransport, options: ForwardedCallGateOptions): IMessageTransport;
+/** Explicitly named alias for {@link withForwardedCallGate}. */
+declare function withFullyQualifiedCallGate(inner: IMessageTransport, options: ForwardedCallGateOptions): IMessageTransport;
+//#endregion
+//#region src/hub/server/identityKeystore.d.ts
+/**
+ * On-disk encrypted keystore for managed identities. State is keyed by
+ * {@link SlotId} (the absolute path to the entry HTML / Node entry point).
+ * Each slot owns up to four files under `storageDir`, mode `0o600`,
+ * AES-256-GCM-sealed under `keystoreSecret`:
+ *
+ *   - `<hash>.bin`         — the managed identity keypair
+ *   - `<hash>.storage.bin` — the per-slot persistent KV store
+ *   - `<hash>.keys.bin`    — the access-key allow-list (gate)
+ *   - `<hash>.snooze.bin`  — the consent re-prompt suppression (optional)
+ *   - `<hash>.filesdir.bin`— the recorded path of the plaintext app-files
+ *                            folder (optional; the folder itself lives
+ *                            wherever the owner placed it, NOT here)
+ *
+ * `<hash>` is `sha256(id).slice(0,16)`. The slot id is bound into each
+ * file's AEAD AAD so swapping files between slots fails the auth tag.
+ *
+ * The `keystoreSecret` itself is opaque bytes — the keystore does not
+ * know or care where it came from. In the extension, it's loaded from
+ * `vscode.SecretStorage`.
+ */
+interface IdentityKeystoreOptions {
+  /** Absolute directory path. Created if missing. */
+  readonly storageDir: string;
+  /** 32+ bytes of secret material used to seal identity files. */
+  readonly keystoreSecret: Uint8Array;
+}
+/**
+ * Stable slot identity: the absolute path to the entry HTML / Node entry
+ * point. One slot ⇒ one managed identity + one storage backend, shared
+ * across every approved {@link SlotAccessKey}.
+ */
+type SlotId = string;
+/**
+ * An access key: a small, exact-match qualifier tuple a caller must
+ * present to reach a slot's identity/storage. Conventionally
+ * `{ appId, bundleHash }`, but the keystore treats it opaquely. Compared
+ * by canonical (sorted-field) JSON equality.
+ */
+type SlotAccessKey = Readonly<Record<string, string>>;
+/**
+ * Result of `slotByIdAndKey`. Either the resolved
+ * slot, or a discriminated error:
+ *   - `slotDoesNotExist` — no slot has ever been created for this id.
+ *   - `unknownKey`       — the slot exists but `key` is not in its
+ *                          allow-list (a different/unapproved bundle).
+ */
+type SlotByIdAndKeyResult = IdentitySlot | {
+  readonly error: "slotDoesNotExist";
+} | {
+  readonly error: "unknownKey";
+};
+/**
+ * Result of `slotByIdAndTime`. Either the resolved slot (access is currently
+ * time-authorized) or a single discriminated error:
+ *   - `consentRequired` — the slot holds inheritable state and no active
+ *                         snooze covers the supplied time, so the caller
+ *                         must obtain fresh consent before granting identity.
+ */
+type SlotByIdAndTimeResult = IdentitySlot | {
+  readonly error: "consentRequired";
+};
+/**
+ * A time-boxed, scoped suppression of identity-access consent re-prompts for
+ * a slot. Set from the consent dialog's "don't ask for file changes for 24h"
+ * checkbox; read on each load to decide whether a content change can load
+ * silently. Cleared by {@link IdentitySlot.delete}.
+ *
+ *   - `scope: "entry"` — covers entry-HTML content changes only.
+ *   - `scope: "all"`   — covers entry-HTML AND external-file content changes.
+ *   - `expiresAt`      — absolute epoch ms; expired snoozes are ignored.
+ *
+ * A snooze never suppresses a *new external path* — that is always a fresh
+ * blast-radius decision the user must see.
+ */
+interface IdentitySnooze {
+  readonly scope: "entry" | "all";
+  readonly expiresAt: number;
+}
+interface IdentitySlot {
+  readonly id: SlotId;
+  /** The slot's managed identity; generated + persisted on first call. */
+  getOrCreateIdentity(): Promise<Identity>;
+  /** Existing identity or `undefined` — never creates. */
+  peekIdentity(): Promise<Identity | undefined>;
+  /** Per-slot persistent KV (caps + app data). File created on first write. */
+  readonly storage: ManagedIdentityStorageBackend;
+  /**
+   * Absolute path of the slot's *plaintext* app-files folder, or
+   * `undefined` if none has been recorded yet. The keystore only stores
+   * and wipes this opaque string — the owner (the extension) chooses the
+   * path (typically `<globalStorage>/app-files/<appId>` with a collision
+   * counter) and performs the actual file IO.
+   *
+   * Recording the path in the slot is deliberate: the folder name is not
+   * derivable from the app id alone (the counter breaks that), so an app
+   * can only reach its own folder by looking it up through its slot. This
+   * both isolates apps from each other and prevents accidental access to a
+   * sibling's folder.
+   */
+  getFilesDir(): Promise<string | undefined>;
+  /** Record the chosen absolute path of this slot's app-files folder. */
+  setFilesDir(absPath: string): Promise<void>;
+  /**
+   * `true` iff a files folder is recorded AND it currently holds ≥1 entry.
+   * Counts toward {@link hasState} so a content change to a privileged app
+   * still trips the consent gate even when the app stored only files (and
+   * never created an identity or KV state).
+   */
+  hasFiles(): Promise<boolean>;
+  /**
+   * Delete every entry inside the recorded files folder but keep the
+   * folder itself and its slot record (so the path stays stable for the
+   * user). No-op when no folder is recorded. Used by the consent dialog's
+   * "wipe app files" option on a *keep-identity* load.
+   */
+  wipeFiles(): Promise<void>;
+  /**
+   * `true` iff there is anything a consumer could inherit: an identity
+   * has been created, storage holds ≥1 entry, OR the app-files folder
+   * holds ≥1 entry. When `false`, granting access exposes nothing — the
+   * consent prompt can be skipped safely.
+   */
+  hasState(): Promise<boolean>;
+  /** All keys currently allowed to access this slot. */
+  listKeys(): Promise<SlotAccessKey[]>;
+  /** `true` iff `key` (exact canonical match) is in the allow-list. */
+  hasKey(key: SlotAccessKey): Promise<boolean>;
+  /** Add keys to the allow-list (creating the slot if needed). Idempotent. */
+  addKeys(...keys: SlotAccessKey[]): Promise<void>;
+  /** Remove one key. Returns `true` iff it was present. */
+  deleteKey(key: SlotAccessKey): Promise<boolean>;
+  /**
+   * The active, unexpired snooze for this slot, or `undefined`. Lazily
+   * treats an expired snooze as absent (does not rewrite the file).
+   */
+  getSnooze(): Promise<IdentitySnooze | undefined>;
+  /** Persist a snooze for this slot (overwrites any previous one). */
+  setSnooze(snooze: IdentitySnooze): Promise<void>;
+  /** Remove any snooze for this slot. Idempotent. */
+  clearSnooze(): Promise<void>;
+  /** Wipe identity, storage, AND all access keys for this slot. */
+  delete(): Promise<void>;
+}
+interface IdentityKeystore {
+  /**
+   * Resolve the slot for `id`, enforcing the access gate. Returns the
+   * slot on success, or a discriminated error if the slot does not exist
+   * or `key` is not in its allow-list. Use this on the privileged path
+   * (registering `identity::*` on an iframe overlay) so an unapproved
+   * bundle can never reach prior state.
+   */
+  slotByIdAndKey(id: SlotId, key: SlotAccessKey): Promise<SlotByIdAndKeyResult>;
+  /**
+   * Resolve the slot for `id`, gated on *time* rather than a content key.
+   * Returns the slot when access is currently authorized — either the slot
+   * holds nothing inheritable ({@link IdentitySlot.hasState} is `false`, so
+   * granting exposes nothing) or an active, unexpired snooze covers `nowMs`.
+   * Otherwise returns `consentRequired`, meaning the slot holds state the
+   * caller must obtain fresh consent for. Used on the privileged path for
+   * URL apps, which have no content key to present to {@link slotByIdAndKey}
+   * but may inherit the slot's identity under a time-boxed grant.
+   */
+  slotByIdAndTime(id: SlotId, nowMs: number): Promise<SlotByIdAndTimeResult>;
+  /**
+   * Create the slot for `id` (if missing) and add `key` to its
+   * allow-list. Idempotent: re-creating an existing slot just ensures the
+   * key is present. Returns the resolved slot. This is the only way to
+   * bootstrap a brand-new slot before {@link slotByIdAndKey} can succeed.
+   */
+  createSlotWithKey(id: SlotId, key: SlotAccessKey): Promise<IdentitySlot>;
+  /**
+   * Unsafe: return the slot handle for `id` with NO key check. Used to
+   * inspect `hasState`/`listKeys` and to run the consent decision before
+   * a key has been added. Never register the identity returned from here
+   * without having checked/added a key.
+   */
+  slotById(id: SlotId): IdentitySlot;
+}
+declare function createIdentityKeystore(opts: IdentityKeystoreOptions): IdentityKeystore;
+//#endregion
+//#region src/hub/server/sqliteIdentityKeystore.d.ts
+type DatabaseSync = import("node:sqlite").DatabaseSync;
+/**
+ * SQLite-backed {@link IdentityKeystore} — a drop-in alternative to the
+ * file-per-slot {@link import('./identityKeystore').createIdentityKeystore}.
+ * All slot state (identity keypair, per-slot KV storage, the access-key gate,
+ * the consent snooze, and the recorded app-files folder) lives in **one**
+ * database file across three tables, so the whole keystore is a single
+ * `DatabaseSync` connection instead of four files per slot.
+ *
+ * The model is identical to the file keystore — `id` (the slot), `keys` (the
+ * gate), and `time` (the snooze) — even though config/CLI hubs only exercise
+ * the `id` + storage axes today. Keeping the full surface means the extension
+ * and node-runner can adopt this backend unchanged later.
+ *
+ * ## Encryption seam
+ *
+ * This backend currently runs in **unencrypted mode**: secret-bearing columns
+ * (identity private keys, storage values) are stored plaintext via the
+ * identity {@link _codec}. When at-rest encryption is added, swap {@link _codec}
+ * for an AEAD codec keyed by a `keystoreSecret` with `slotId` bound into the
+ * AAD (mirroring the file keystore's per-file AAD). The columns stay `TEXT`
+ * (ciphertext is base64url), so enabling encryption is a codec swap plus a
+ * one-time re-encode — not a schema migration.
+ *
+ * Uses the built-in `node:sqlite` `DatabaseSync`, matching the monorepo's
+ * other SQLite stores. The module is loaded only when a keystore opens a
+ * database, so consumers that only import the Hub package do not receive
+ * Node's SQLite experimental warning.
+ */
+interface SqliteIdentitySlot extends IdentitySlot {
+  /**
+   * Write a **specific** keypair into this slot iff it has no identity yet,
+   * and return the resulting identity. Used to import a legacy plaintext
+   * identity while preserving its principal. If an identity already exists
+   * it is returned unchanged (the import is a no-op).
+   */
+  importIdentity(ed: Keypair, wrap: X25519Keypair): Promise<Identity>;
+}
+interface SqliteIdentityKeystore extends IdentityKeystore {
+  slotById(id: SlotId): SqliteIdentitySlot;
+}
+interface SqliteIdentityKeystoreOptions {
+  /**
+   * Path to the SQLite database file (created if missing) or `":memory:"`.
+   * Ignored when {@link db} is provided.
+   */
+  readonly dbPath?: string;
+  /** An existing connection to reuse (share one file across stores). */
+  readonly db?: DatabaseSync;
+}
+/** Open (creating if needed) a SQLite-backed {@link IdentityKeystore}. */
+declare function createSqliteIdentityKeystore(opts: SqliteIdentityKeystoreOptions): SqliteIdentityKeystore;
+//#endregion
+export { validatePrefix as C, ForwardingTable as S, withVerifiedSignature as _, IdentityKeystore as a, RegisteredServiceId as b, IdentitySnooze as c, SlotByIdAndTimeResult as d, SlotId as f, withFullyQualifiedCallGate as g, withForwardedCallGate as h, createSqliteIdentityKeystore as i, SlotAccessKey as l, ForwardedCallGateOptions as m, SqliteIdentityKeystoreOptions as n, IdentityKeystoreOptions as o, createIdentityKeystore as p, SqliteIdentitySlot as r, IdentitySlot as s, SqliteIdentityKeystore as t, SlotByIdAndKeyResult as u, MintCapabilityOptions as v, hubRegisterServiceId as x, mintCapability as y };
+//# sourceMappingURL=index-CLIUrV88.d.ts.map