@drakkar.software/octobot-client 0.4.0

package/dist/client/mirror/writer.js

@@ -0,0 +1,50 @@
+import { createSpaceMirrorChannel } from '@drakkar.software/starfish-replica/space';
+import { mirrorDocPath, mirrorNodeTitleFor, mirrorTierFor, MIRROR_COLLECTIONS, MIRROR_SPACE_NAME, } from './collections.js';
+/**
+ * One full cloud-mirror sync cycle: find-or-create the wallet's mirror space,
+ * plan what changed since last cycle, create any newly-enabled collections'
+ * nodes, write every currently-enabled collection's projection, and clear any
+ * collection the user just disabled.
+ *
+ * The space/node mechanics live in `starfish-replica/space`'s
+ * `createSpaceMirrorChannel` — this is a thin adapter wiring the
+ * `MIRROR_COLLECTIONS` registry and its tier routing into it.
+ *
+ * Callers (the node's writer, the mobile no-node writer) gate this behind the
+ * `cloudSyncEnabled` setting themselves; this function assumes it was only
+ * called because the setting is on.
+ */
+export async function syncCloudMirror(options) {
+    const { session, enabledCollectionIds, readSourceCollection } = options;
+    const channel = createSpaceMirrorChannel({
+        name: 'octobot-cloud-mirror',
+        session,
+        // One space; `tier` is what separates the audiences within it. "shared"
+        // -> "isolated" (own per-node keyring, so a grant reaches exactly that
+        // node), "private" -> the space keyring, "public" -> world-readable
+        // plaintext.
+        collections: MIRROR_COLLECTIONS.map((c) => ({
+            id: c.id,
+            spaceName: MIRROR_SPACE_NAME,
+            tier: mirrorTierFor(c.id),
+        })),
+        enabledIds: () => enabledCollectionIds,
+        readSource: (id) => readSourceCollection(id),
+        // Shared with the website-side reader so a tier is never written to one
+        // path and read from another.
+        docPath: mirrorDocPath,
+        // Opaque for public nodes: their title is republished world-readable, so
+        // it must not name the collection. See `mirrorNodeTitleFor`.
+        title: mirrorNodeTitleFor,
+    });
+    // A direct app call, not a scheduler-driven one.
+    await channel.sync({ callKind: 'classic' });
+    const { spaces, created, written, cleared } = channel.result;
+    return {
+        spaceId: spaces[MIRROR_SPACE_NAME] ?? null,
+        created: created,
+        written: written,
+        cleared: cleared,
+    };
+}
+//# sourceMappingURL=writer.js.map

package/dist/client/mirror/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../../src/client/mirror/writer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAA;AACnF,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,iBAAiB,GAElB,MAAM,kBAAkB,CAAA;AAyBzB;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAA+B;IAE/B,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,GAAG,OAAO,CAAA;IAEvE,MAAM,OAAO,GAAG,wBAAwB,CAAC;QACvC,IAAI,EAAE,sBAAsB;QAC5B,OAAO;QACP,wEAAwE;QACxE,uEAAuE;QACvE,oEAAoE;QACpE,aAAa;QACb,WAAW,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC1C,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,SAAS,EAAE,iBAAiB;YAC5B,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1B,CAAC,CAAC;QACH,UAAU,EAAE,GAAG,EAAE,CAAC,oBAAoB;QACtC,UAAU,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,oBAAoB,CAAC,EAAE,CAAC;QAC5C,wEAAwE;QACxE,8BAA8B;QAC9B,OAAO,EAAE,aAAa;QACtB,yEAAyE;QACzE,6DAA6D;QAC7D,KAAK,EAAE,kBAAkB;KAC1B,CAAC,CAAA;IACF,iDAAiD;IACjD,MAAM,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAA;IAE3C,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAA;IAC5D,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,iBAAiB,CAAC,IAAI,IAAI;QAC1C,OAAO,EAAE,OAA+B;QACxC,OAAO,EAAE,OAA+B;QACxC,OAAO,EAAE,OAA+B;KACzC,CAAA;AACH,CAAC"}

package/dist/client/pairing/mirrorGrant.d.ts

@@ -0,0 +1,91 @@
+import { type Session } from '@drakkar.software/starfish-spaces';
+import type { CapCert } from '@drakkar.software/starfish-protocol';
+import type { PairingRequestPayload } from '../../identity/pairingRequest.js';
+import { type MirrorCollectionId } from '../mirror/index.js';
+/**
+ * Rebuild the `{edPub, kemPub, userId, kemSig}` "join request" JSON
+ * `starfish-spaces`' `inviteToNode`/`parseJoinRequest` expect, from a
+ * `PairingRequestPayload`'s already-public `devEdPub`/`devKemPub` plus the
+ * `joinRequestKemSig` it carries. The website computes `joinRequestKemSig`
+ * once (via `signKemSig`) when it generates its ephemeral device keys in
+ * `startPairingRequest` — this just reassembles the same shape
+ * `makeJoinRequest(session)` would have produced, without the website ever
+ * needing a full `starfish-spaces` `Session` for an identity it has no
+ * wallet to derive (it's a website, not a wallet holder).
+ */
+export declare function buildJoinRequestJson(request: PairingRequestPayload): Promise<string>;
+export declare class NothingToShareError extends Error {
+    constructor();
+}
+/** One granted collection, as the website needs it to read that node: the two
+ *  caps `inviteToNode(..., {isolated: true})` mints — `contentCap` (`objinv`)
+ *  to fetch the document, `keyringCap` (`nodekeyring`) to open it. */
+export interface MirrorGrantNode {
+    collectionId: MirrorCollectionId;
+    nodeId: string;
+    contentCap: CapCert;
+    keyringCap: CapCert;
+}
+/** The grant document, published sealed through the pairing rendezvous. `v`
+ *  is a wire version: a website built against the old space-member grant sees
+ *  a shape it cannot parse and must say so, rather than silently reading
+ *  nothing. */
+export interface MirrorGrantDoc {
+    v: 1;
+    spaceId: string;
+    nodes: MirrorGrantNode[];
+}
+export interface MintedPairingGrant {
+    /** JSON-stringified `MirrorGrantDoc`. One grant per collection, each
+     *  reaching exactly one node — never the whole space. */
+    bundle: string;
+    spaceId: string;
+    /** `defaultUserIdFromEdPub(request.devEdPub)`. The website is NOT added to
+     *  the space roster (that is the point of the isolated tier), so this is an
+     *  identifier for bookkeeping, not a membership record. */
+    memberUserId: string;
+    /** The website's ephemeral KEM pubkey — the recipient entry
+     *  `revokePairingGrant` removes from each node's keyring. */
+    memberKemPub: string;
+    /** Exactly what this grant covers. Unlike the old space-wide grant this is
+     *  not a snapshot that can silently widen: a collection enabled later gets
+     *  no grant until the user pairs again. */
+    coveredCollections: MirrorCollectionId[];
+    /** The granted node ids, in the same order — what `revokePairingGrant`
+     *  takes, so a caller never has to re-parse `bundle`. */
+    grantedNodeIds: string[];
+}
+/**
+ * Phone side: mint a read-only grant for a paired website — one per-node
+ * invite for each currently-mirrored, third-party-eligible collection.
+ *
+ * The website joins no space roster. Each invite carries a cap for that one
+ * node's content plus a recipient slot in that one node's keyring, so the
+ * grant reaches exactly the collections shown in the pairing UI and nothing
+ * else — `user-settings` (`visibility: "private"`, space keyring) and
+ * `user-accounts-auth` (never mirrored at all) are unreachable by
+ * construction rather than by policy.
+ *
+ * Throws `NothingToShareError` when no eligible collection has a mirror node
+ * yet (i.e. `syncCloudMirror` has not run with one enabled).
+ */
+export declare function mintPairingGrant(session: Session, request: PairingRequestPayload): Promise<MintedPairingGrant>;
+/**
+ * Phone side: revoke a previously-minted grant by removing the website's
+ * ephemeral KEM key from each granted node's keyring, which also rotates that
+ * keyring to a new epoch. Everything written afterwards is sealed to an epoch
+ * the site is not a recipient of.
+ *
+ * Two honest caveats, both inherent to the model rather than to this code.
+ * The site keeps a valid `objinv` cap, so it can still FETCH those nodes'
+ * bytes — it simply cannot decrypt anything written after this call; making
+ * the fetch itself fail needs the cap-revocation-list plumbing, which is not
+ * reachable on the deployed server (same finding the space-member design
+ * recorded). And this cannot erase what the site already fetched and
+ * decrypted — the caveat every revocation design in this package documents.
+ *
+ * Per-node, unlike the space-member grant it replaces: revoking one
+ * collection leaves the others working.
+ */
+export declare function revokePairingGrant(session: Session, spaceId: string, nodeIds: readonly string[], memberKemPub: string): Promise<void>;
+//# sourceMappingURL=mirrorGrant.d.ts.map

package/dist/client/pairing/mirrorGrant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirrorGrant.d.ts","sourceRoot":"","sources":["../../../src/client/pairing/mirrorGrant.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,OAAO,EACb,MAAM,mCAAmC,CAAA;AAE1C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qCAAqC,CAAA;AAClE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAA;AAC7E,OAAO,EAKL,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAA;AAE3B;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ1F;AAED,qBAAa,mBAAoB,SAAQ,KAAK;;CAK7C;AAED;;sEAEsE;AACtE,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,kBAAkB,CAAA;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,OAAO,CAAA;IACnB,UAAU,EAAE,OAAO,CAAA;CACpB;AAED;;;eAGe;AACf,MAAM,WAAW,cAAc;IAC7B,CAAC,EAAE,CAAC,CAAA;IACJ,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,eAAe,EAAE,CAAA;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC;6DACyD;IACzD,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf;;+DAE2D;IAC3D,YAAY,EAAE,MAAM,CAAA;IACpB;iEAC6D;IAC7D,YAAY,EAAE,MAAM,CAAA;IACpB;;+CAE2C;IAC3C,kBAAkB,EAAE,kBAAkB,EAAE,CAAA;IACxC;6DACyD;IACzD,cAAc,EAAE,MAAM,EAAE,CAAA;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CA2C7B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAIf"}

package/dist/client/pairing/mirrorGrant.js

@@ -0,0 +1,99 @@
+import { inviteToNode, readObjectTree, removeNodeKeyringRecipient, } from '@drakkar.software/starfish-spaces';
+import { defaultUserIdFromEdPub } from '@drakkar.software/starfish-spaces';
+import { findOrCreateMirrorSpace, isIsolatedMirrorCollection, isKnownMirrorCollection, MIRROR_SPACE_NAME, } from '../mirror/index.js';
+/**
+ * Rebuild the `{edPub, kemPub, userId, kemSig}` "join request" JSON
+ * `starfish-spaces`' `inviteToNode`/`parseJoinRequest` expect, from a
+ * `PairingRequestPayload`'s already-public `devEdPub`/`devKemPub` plus the
+ * `joinRequestKemSig` it carries. The website computes `joinRequestKemSig`
+ * once (via `signKemSig`) when it generates its ephemeral device keys in
+ * `startPairingRequest` — this just reassembles the same shape
+ * `makeJoinRequest(session)` would have produced, without the website ever
+ * needing a full `starfish-spaces` `Session` for an identity it has no
+ * wallet to derive (it's a website, not a wallet holder).
+ */
+export async function buildJoinRequestJson(request) {
+    const userId = await defaultUserIdFromEdPub(request.devEdPub);
+    return JSON.stringify({
+        edPub: request.devEdPub,
+        kemPub: request.devKemPub,
+        userId,
+        kemSig: request.joinRequestKemSig,
+    });
+}
+export class NothingToShareError extends Error {
+    constructor() {
+        super('cloud sync: nothing enabled to share yet — enable at least one collection before pairing');
+        this.name = 'NothingToShareError';
+    }
+}
+/**
+ * Phone side: mint a read-only grant for a paired website — one per-node
+ * invite for each currently-mirrored, third-party-eligible collection.
+ *
+ * The website joins no space roster. Each invite carries a cap for that one
+ * node's content plus a recipient slot in that one node's keyring, so the
+ * grant reaches exactly the collections shown in the pairing UI and nothing
+ * else — `user-settings` (`visibility: "private"`, space keyring) and
+ * `user-accounts-auth` (never mirrored at all) are unreachable by
+ * construction rather than by policy.
+ *
+ * Throws `NothingToShareError` when no eligible collection has a mirror node
+ * yet (i.e. `syncCloudMirror` has not run with one enabled).
+ */
+export async function mintPairingGrant(session, request) {
+    const joinRequestJson = await buildJoinRequestJson(request);
+    const space = await findOrCreateMirrorSpace(session, MIRROR_SPACE_NAME);
+    const tree = await readObjectTree(session, space.id);
+    const grantable = tree.filter((node) => isKnownMirrorCollection(node.type) && isIsolatedMirrorCollection(node.type));
+    if (grantable.length === 0)
+        throw new NothingToShareError();
+    const nodes = [];
+    for (const node of grantable) {
+        // `isolated: true` is what keeps this off the space roster and off the
+        // space keyring; `write: false` is what makes it read-only.
+        const bundleJson = await inviteToNode(session, space.id, node.id, joinRequestJson, { enc: true }, node.type, { isolated: true, write: false });
+        const bundle = JSON.parse(bundleJson);
+        if (!bundle.nodeCap || !bundle.keyringCap) {
+            throw new Error(`pairing grant: incomplete invite bundle for ${node.type}`);
+        }
+        nodes.push({
+            collectionId: node.type,
+            nodeId: node.id,
+            contentCap: bundle.nodeCap,
+            keyringCap: bundle.keyringCap,
+        });
+    }
+    const doc = { v: 1, spaceId: space.id, nodes };
+    return {
+        bundle: JSON.stringify(doc),
+        spaceId: space.id,
+        memberUserId: await defaultUserIdFromEdPub(request.devEdPub),
+        memberKemPub: request.devKemPub,
+        coveredCollections: nodes.map((n) => n.collectionId),
+        grantedNodeIds: nodes.map((n) => n.nodeId),
+    };
+}
+/**
+ * Phone side: revoke a previously-minted grant by removing the website's
+ * ephemeral KEM key from each granted node's keyring, which also rotates that
+ * keyring to a new epoch. Everything written afterwards is sealed to an epoch
+ * the site is not a recipient of.
+ *
+ * Two honest caveats, both inherent to the model rather than to this code.
+ * The site keeps a valid `objinv` cap, so it can still FETCH those nodes'
+ * bytes — it simply cannot decrypt anything written after this call; making
+ * the fetch itself fail needs the cap-revocation-list plumbing, which is not
+ * reachable on the deployed server (same finding the space-member design
+ * recorded). And this cannot erase what the site already fetched and
+ * decrypted — the caveat every revocation design in this package documents.
+ *
+ * Per-node, unlike the space-member grant it replaces: revoking one
+ * collection leaves the others working.
+ */
+export async function revokePairingGrant(session, spaceId, nodeIds, memberKemPub) {
+    for (const nodeId of nodeIds) {
+        await removeNodeKeyringRecipient(session, spaceId, nodeId, [memberKemPub]);
+    }
+}
+//# sourceMappingURL=mirrorGrant.js.map

package/dist/client/pairing/mirrorGrant.js.map

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

package/dist/client/pairing/mirrorReader.d.ts

@@ -0,0 +1,99 @@
+import type { CapCert, PushSuccess } from '@drakkar.software/starfish-protocol';
+import { type MirrorCollectionId } from '../mirror/index.js';
+/** The grant document `mintPairingGrant` publishes (sealed) and this module
+ *  unpacks: one entry per granted collection, each naming the node and the
+ *  two caps that reach it. The node list is carried IN the grant because a
+ *  per-node grant holder cannot read `objindex` to discover it. */
+export interface MirrorGrantBundle {
+    spaceId: string;
+    nodes: MirrorGrantNodeRef[];
+}
+export interface MirrorGrantNodeRef {
+    collectionId: MirrorCollectionId;
+    nodeId: string;
+    contentCap: CapCert;
+    keyringCap: CapCert;
+}
+export declare function parseMirrorGrantBundle(bundleJson: string): MirrorGrantBundle;
+export interface ReadMirrorCollectionsOptions {
+    rendezvous: {
+        baseUrl: string;
+        namespace: string;
+    };
+    spaceId: string;
+    /** From `parseMirrorGrantBundle` — exactly the nodes this grant covers. */
+    nodes: readonly MirrorGrantNodeRef[];
+    /** The website's own ephemeral Ed25519 private key (hex) — from the same
+     *  `device` the site generated in `startPairingRequest`; every cap was
+     *  minted for exactly this device's pubkey. */
+    devEdPrivHex: string;
+    /** The website's own ephemeral X25519 KEM private key (hex) — same `device`
+     *  as `devEdPrivHex`. Each `inviteToNode` added this device's KEM pubkey as
+     *  a recipient of THAT node's own keyring; content is sealed under those,
+     *  not under the caps. */
+    devKemPrivHex: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * Website side, session-less: pull every collection the grant covers. A REAL
+ * live read, not a point-in-time export — call it again any time to see the
+ * latest write, bounded only by how often the wallet's writer refreshes.
+ *
+ * A collection whose node was cleared (the user disabled it) or whose keyring
+ * recipient was removed (the user revoked it) simply won't appear, so this
+ * reflects CURRENT state rather than a snapshot of grant time.
+ *
+ * A thin adapter over `starfish-replica/space`'s `readIsolatedSpaceMirror`;
+ * this module owns only the `mirrorDocPath` template and the timeout-wrapped
+ * fetch.
+ */
+export declare function readMirrorCollections(opts: ReadMirrorCollectionsOptions): Promise<Partial<Record<MirrorCollectionId, unknown>>>;
+export interface AttemptDirectMirrorWriteOptions {
+    rendezvous: {
+        baseUrl: string;
+        namespace: string;
+    };
+    spaceId: string;
+    cap: CapCert;
+    /** The website's own ephemeral Ed25519 private key (hex) — same device the
+     *  cap was minted for. */
+    devEdPrivHex: string;
+    /** Which mirror collection to target, e.g. `'user-data'` (automations) or
+     *  `'user-accounts'`. */
+    collectionId: MirrorCollectionId;
+    /** A fresh node id — this always targets a node that does not exist yet,
+     *  matching "write a new automation/account", not an edit of one that's
+     *  already there. */
+    nodeId: string;
+    /** Plain (unsealed) JSON body to push. Since the grant is expected to be
+     *  read-only, the request is rejected before content ever matters — this
+     *  never needs to be a validly-sealed document. */
+    doc: Record<string, unknown>;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * Website side, session-less: try to write a brand-new node directly into
+ * the paired mirror space, using nothing but the grant `mintPairingGrant`
+ * already handed this site (`opts.cap` + `opts.devEdPrivHex` — the exact
+ * credentials `readMirrorCollections` reads with). No session, no
+ * `addObject`/index update — just one raw `push` at the collection's own
+ * path, the smallest possible probe of what the cap actually authorizes.
+ *
+ * **This call is expected to fail.** `mintPairingGrant` always mints with
+ * `canWrite: false` (see `mirrorGrant.ts`), so the cap's `ops` is
+ * `['read', 'list']` — no `'write'` — and the server rejects the push before
+ * looking at the body. That is the point of exposing this: a paired website
+ * holding only a read grant cannot unilaterally create or change anything in
+ * the user's node. Making a change requires asking the user (the phone,
+ * which holds the actual writable session) to approve it and publish the
+ * write itself — this function is not, and is never meant to become, a
+ * second write path around that approval.
+ *
+ * Returns the server's raw response on the (unexpected) chance it succeeds,
+ * or rethrows the `StarfishHttpError` (or plain fetch failure) so a caller
+ * can show the real rejection rather than a synthesized one.
+ */
+export declare function attemptDirectMirrorWrite(opts: AttemptDirectMirrorWriteOptions): Promise<PushSuccess>;
+//# sourceMappingURL=mirrorReader.d.ts.map

package/dist/client/pairing/mirrorReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirrorReader.d.ts","sourceRoot":"","sources":["../../../src/client/pairing/mirrorReader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAA;AAK/E,OAAO,EAA6D,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAEvH;;;mEAGmE;AACnE,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,kBAAkB,EAAE,CAAA;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,kBAAkB,CAAA;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,OAAO,CAAA;IACnB,UAAU,EAAE,OAAO,CAAA;CACpB;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,CAkC5E;AAED,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAClD,OAAO,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACpC;;mDAE+C;IAC/C,YAAY,EAAE,MAAM,CAAA;IACpB;;;8BAG0B;IAC1B,aAAa,EAAE,MAAM,CAAA;IACrB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,4BAA4B,GACjC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC,CAAC,CAUvD;AAkBD,MAAM,WAAW,+BAA+B;IAC9C,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAClD,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,OAAO,CAAA;IACZ;8BAC0B;IAC1B,YAAY,EAAE,MAAM,CAAA;IACpB;6BACyB;IACzB,YAAY,EAAE,kBAAkB,CAAA;IAChC;;yBAEqB;IACrB,MAAM,EAAE,MAAM,CAAA;IACd;;uDAEmD;IACnD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC5B,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,+BAA+B,GACpC,OAAO,CAAC,WAAW,CAAC,CAStB"}

package/dist/client/pairing/mirrorReader.js

@@ -0,0 +1,117 @@
+import { readIsolatedSpaceMirror } from '@drakkar.software/starfish-replica/space';
+import { StarfishClient } from '@drakkar.software/starfish-client';
+import { createTimeoutFetch } from '../../transport/syncClient.js';
+import { SYNC_FETCH_TIMEOUT_MS } from '../../crypto/wireConstants.js';
+import { isKnownMirrorCollection, mirrorDocPushPath, mirrorDocPath } from '../mirror/index.js';
+export function parseMirrorGrantBundle(bundleJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(bundleJson);
+    }
+    catch {
+        throw new Error('pairing grant: bundle is not valid JSON');
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        throw new Error('pairing grant: malformed bundle');
+    const b = parsed;
+    if (typeof b.spaceId !== 'string' || !b.spaceId)
+        throw new Error('pairing grant: missing spaceId');
+    // A pre-per-node grant (one space-wide `cap`, no `nodes`) is not something
+    // this reader can silently treat as "nothing shared" — say so instead.
+    if (!Array.isArray(b.nodes)) {
+        throw new Error('pairing grant: missing nodes — this grant was issued by an older, incompatible version');
+    }
+    const nodes = b.nodes.map((raw, i) => {
+        const n = raw;
+        if (typeof n?.collectionId !== 'string' || typeof n?.nodeId !== 'string') {
+            throw new Error(`pairing grant: malformed node at index ${i}`);
+        }
+        if (typeof n.contentCap !== 'object' || n.contentCap === null) {
+            throw new Error(`pairing grant: node ${n.collectionId} is missing its content cap`);
+        }
+        if (typeof n.keyringCap !== 'object' || n.keyringCap === null) {
+            throw new Error(`pairing grant: node ${n.collectionId} is missing its keyring cap`);
+        }
+        return {
+            collectionId: n.collectionId,
+            nodeId: n.nodeId,
+            contentCap: n.contentCap,
+            keyringCap: n.keyringCap,
+        };
+    });
+    return { spaceId: b.spaceId, nodes };
+}
+/**
+ * Website side, session-less: pull every collection the grant covers. A REAL
+ * live read, not a point-in-time export — call it again any time to see the
+ * latest write, bounded only by how often the wallet's writer refreshes.
+ *
+ * A collection whose node was cleared (the user disabled it) or whose keyring
+ * recipient was removed (the user revoked it) simply won't appear, so this
+ * reflects CURRENT state rather than a snapshot of grant time.
+ *
+ * A thin adapter over `starfish-replica/space`'s `readIsolatedSpaceMirror`;
+ * this module owns only the `mirrorDocPath` template and the timeout-wrapped
+ * fetch.
+ */
+export async function readMirrorCollections(opts) {
+    return readIsolatedSpaceMirror({
+        rendezvous: opts.rendezvous,
+        spaceId: opts.spaceId,
+        nodes: opts.nodes.filter((n) => isKnownMirrorCollection(n.collectionId)),
+        devEdPrivHex: opts.devEdPrivHex,
+        devKemPrivHex: opts.devKemPrivHex,
+        docPath: mirrorDocPath,
+        fetch: createTimeoutFetch(opts.timeoutMs ?? SYNC_FETCH_TIMEOUT_MS, opts.fetch ?? globalThis.fetch),
+    });
+}
+/** Returns the SAME `{cap, devEdPrivHex}` on every call — a paired website
+ *  holds one grant for one ephemeral device, never rotates it, so there is
+ *  nothing to refresh. Shared shape between the write attempt below and
+ *  `readIsolatedSpaceMirror`'s own private cap provider (that one lives inside
+ *  `starfish-replica` and isn't exported, so this is a narrow duplicate, not
+ *  a reused import). */
+class StaticMirrorCapProvider {
+    cap;
+    devEdPrivHex;
+    constructor(cap, devEdPrivHex) {
+        this.cap = cap;
+        this.devEdPrivHex = devEdPrivHex;
+    }
+    async getCap() {
+        return { cap: this.cap, devEdPrivHex: this.devEdPrivHex };
+    }
+}
+/**
+ * Website side, session-less: try to write a brand-new node directly into
+ * the paired mirror space, using nothing but the grant `mintPairingGrant`
+ * already handed this site (`opts.cap` + `opts.devEdPrivHex` — the exact
+ * credentials `readMirrorCollections` reads with). No session, no
+ * `addObject`/index update — just one raw `push` at the collection's own
+ * path, the smallest possible probe of what the cap actually authorizes.
+ *
+ * **This call is expected to fail.** `mintPairingGrant` always mints with
+ * `canWrite: false` (see `mirrorGrant.ts`), so the cap's `ops` is
+ * `['read', 'list']` — no `'write'` — and the server rejects the push before
+ * looking at the body. That is the point of exposing this: a paired website
+ * holding only a read grant cannot unilaterally create or change anything in
+ * the user's node. Making a change requires asking the user (the phone,
+ * which holds the actual writable session) to approve it and publish the
+ * write itself — this function is not, and is never meant to become, a
+ * second write path around that approval.
+ *
+ * Returns the server's raw response on the (unexpected) chance it succeeds,
+ * or rethrows the `StarfishHttpError` (or plain fetch failure) so a caller
+ * can show the real rejection rather than a synthesized one.
+ */
+export async function attemptDirectMirrorWrite(opts) {
+    const client = new StarfishClient({
+        baseUrl: opts.rendezvous.baseUrl,
+        namespace: opts.rendezvous.namespace,
+        fetch: createTimeoutFetch(opts.timeoutMs ?? SYNC_FETCH_TIMEOUT_MS, opts.fetch ?? globalThis.fetch),
+        capProvider: new StaticMirrorCapProvider(opts.cap, opts.devEdPrivHex),
+    });
+    const path = mirrorDocPushPath(opts.collectionId, opts.spaceId, opts.nodeId);
+    return client.push(path, opts.doc, null);
+}
+//# sourceMappingURL=mirrorReader.js.map

package/dist/client/pairing/mirrorReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirrorReader.js","sourceRoot":"","sources":["../../../src/client/pairing/mirrorReader.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAA;AAClF,OAAO,EAAE,cAAc,EAA4B,MAAM,mCAAmC,CAAA;AAC5F,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAA;AACrE,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,aAAa,EAA2B,MAAM,oBAAoB,CAAA;AAkBvH,MAAM,UAAU,sBAAsB,CAAC,UAAkB;IACvD,IAAI,MAAe,CAAA;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAA;IAC5D,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAA;IACrG,MAAM,CAAC,GAAG,MAAiC,CAAA;IAC3C,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAA;IAClG,2EAA2E;IAC3E,uEAAuE;IACvE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,wFAAwF,CAAC,CAAA;IAC3G,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;QACnC,MAAM,CAAC,GAAG,GAA8B,CAAA;QACxC,IAAI,OAAO,CAAC,EAAE,YAAY,KAAK,QAAQ,IAAI,OAAO,CAAC,EAAE,MAAM,KAAK,QAAQ,EAAE,CAAC;YACzE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,EAAE,CAAC,CAAA;QAChE,CAAC;QACD,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,IAAI,CAAC,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC,YAAY,6BAA6B,CAAC,CAAA;QACrF,CAAC;QACD,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,IAAI,CAAC,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC,YAAY,6BAA6B,CAAC,CAAA;QACrF,CAAC;QACD,OAAO;YACL,YAAY,EAAE,CAAC,CAAC,YAAkC;YAClD,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,UAAU,EAAE,CAAC,CAAC,UAAqB;YACnC,UAAU,EAAE,CAAC,CAAC,UAAqB;SACpC,CAAA;IACH,CAAC,CAAC,CAAA;IACF,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAA;AACtC,CAAC;AAoBD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,IAAkC;IAElC,OAAO,uBAAuB,CAAC;QAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,uBAAuB,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;QACxE,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,OAAO,EAAE,aAAa;QACtB,KAAK,EAAE,kBAAkB,CAAC,IAAI,CAAC,SAAS,IAAI,qBAAqB,EAAE,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;KACnG,CAAC,CAAA;AACJ,CAAC;AAED;;;;;wBAKwB;AACxB,MAAM,uBAAuB;IAER;IACA;IAFnB,YACmB,GAAY,EACZ,YAAoB;QADpB,QAAG,GAAH,GAAG,CAAS;QACZ,iBAAY,GAAZ,YAAY,CAAQ;IACpC,CAAC;IACJ,KAAK,CAAC,MAAM;QACV,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAA;IAC3D,CAAC;CACF;AAwBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,IAAqC;IAErC,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC;QAChC,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO;QAChC,SAAS,EAAE,IAAI,CAAC,UAAU,CAAC,SAAS;QACpC,KAAK,EAAE,kBAAkB,CAAC,IAAI,CAAC,SAAS,IAAI,qBAAqB,EAAE,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;QAClG,WAAW,EAAE,IAAI,uBAAuB,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC;KACtE,CAAC,CAAA;IACF,MAAM,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IAC5E,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;AAC1C,CAAC"}

package/dist/client/pairing/pairingGrantExchange.d.ts

@@ -0,0 +1,135 @@
+import { type SealerKeys } from '@drakkar.software/starfish-keyring';
+import type { GeneratedDeviceKeys } from '@drakkar.software/starfish-identities';
+import type { PairingRequestPayload } from '../../identity/pairingRequest.js';
+import { type MirrorGrantNodeRef } from './mirrorReader.js';
+import type { MintedPairingGrant } from './mirrorGrant.js';
+import type { MirrorCollectionId } from '../mirror/index.js';
+/** Phone side, step 2: seal and publish the minted grant to the request's
+ *  `code` slot — this OVERWRITES the request doc still published there,
+ *  since request and grant now share one address.
+ *
+ *  `rendezvous` is the caller's OWN trusted server config — the same one it
+ *  used to look up `request` via `fetchPairingRequestByCode` — never
+ *  `request.rendezvous`. That field rides inside a document anyone can
+ *  publish to the public `joinsessions` collection, so trusting it here
+ *  would let a malicious "website" party point this phone's outbound POST at
+ *  an arbitrary host of its choosing.
+ *
+ *  `baseHash` MUST be the `hash` `fetchPairingRequestByCode` returned
+ *  alongside `request` — this is what makes "claim this specific, exact
+ *  request" atomic: the push only succeeds if the slot still holds exactly
+ *  the request doc this caller read, so a request that was swapped or
+ *  already claimed by someone else between the read and this write is
+ *  detected as a conflict rather than silently overwritten. There is no
+ *  longer a meaningful "first publish, baseHash: null" case the way the
+ *  retired sessionId-keyed design had one — the slot is never empty by the
+ *  time a caller reaches this function, it already holds the request. A
+ *  caller legitimately RE-publishing later (a refresh) must pass back the
+ *  hash THIS function returned from its own previous call. Returns the
+ *  resulting hash for exactly that purpose. */
+export declare function publishPairingGrant(opts: {
+    request: PairingRequestPayload;
+    sealer: SealerKeys;
+    grant: MintedPairingGrant;
+    rendezvous: {
+        baseUrl: string;
+        namespace: string;
+    };
+    baseHash: string | null;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<{
+    hash: string;
+}>;
+/** Phone side: stop publishing and clear the current slot — since request
+ *  and grant share one address, this clears BOTH together (there is no way
+ *  to clear one but keep the other). It stops future reads but cannot
+ *  recall a grant a website already fetched — with this design, "cannot
+ *  recall" is narrow: the grant itself only proves space membership, and
+ *  `removeSpaceMember`-based revocation (real, immediate, checked live on
+ *  every request) is the actual unpair mechanism a caller should use
+ *  ALONGSIDE this, not instead of it — this only stops the CODE from
+ *  resolving to a usable grant again, it does not by itself revoke a grant
+ *  already handed out. */
+export declare function clearPairingGrant(opts: {
+    request: PairingRequestPayload;
+    rendezvous: {
+        baseUrl: string;
+        namespace: string;
+    };
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<{
+    hash: string;
+}>;
+export interface UnsealedPairingGrant {
+    spaceId: string;
+    /** Live read of every mirror collection the grant currently covers — a
+     *  real pull, not a cached/point-in-time value; call `readMirrorCollections`
+     *  again directly for a later refresh rather than re-fetching the grant. */
+    collections: Partial<Record<MirrorCollectionId, unknown>>;
+    /** The Ed25519 pubkey that actually sealed this grant, verified via the
+     *  wrap entry's signature (never merely claimed — `unseal` always checks
+     *  it). A trust-on-first-use pin: record it after the FIRST successful
+     *  call and pass it back as `expectedSealer` on every later poll for this
+     *  session, so a later writer to the same slot cannot silently replace an
+     *  established pairing's grant with their own. Nothing pins WHO this key
+     *  belongs to on the very first read — that trust comes from the grant
+     *  write itself being a compare-and-swap against the exact request hash
+     *  `fetchPairingRequestByCode` returned (see `publishPairingGrant`), which
+     *  only the party that actually read the live, unclaimed request could
+     *  have supplied. */
+    sealedBy: string;
+    /** The per-node grants this bundle unwrapped to — the SAME ones
+     *  `readMirrorCollections` above just used to pull `collections`. Exposed
+     *  so a caller can make its own authenticated calls (e.g.
+     *  `attemptDirectMirrorWrite`) without re-fetching and re-unsealing the
+     *  grant. Always read-only in practice: `mintPairingGrant` mints with
+     *  `write: false`, so no cap here carries `'write'`. */
+    nodes: MirrorGrantNodeRef[];
+}
+/** Website side: read whatever is currently published at this session's
+ *  slot. Three outcomes:
+ *  - nothing published (wrong/expired code) → `null`, "keep waiting".
+ *  - still `kind: 'octobot-pairing-request'` (the phone hasn't approved
+ *    yet) → also `null`, "keep waiting" — this is the normal, expected
+ *    state for most of the polling loop's life, NOT an error.
+ *  - `kind: 'octobot-pairing-grant'` → unseal it and immediately do a live
+ *    read of every mirror collection it covers.
+ *  Anything else (an unrecognized `kind`, or a `kind: 'octobot-pairing-grant'`
+ *  doc whose `sealed` field isn't actually a sealed blob) throws — that's a
+ *  genuine malformed-document case, not a wait state. */
+export declare function fetchPairingGrant(session: {
+    code: string;
+    device: GeneratedDeviceKeys;
+    rendezvous: {
+        baseUrl: string;
+        namespace: string;
+    };
+}, opts?: {
+    expectedSealer?: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<UnsealedPairingGrant | null>;
+/** Website side: poll until the phone's FIRST approval publishes a grant,
+ *  or `timeoutMs` elapses. This is the initial-approval wait, not an ongoing
+ *  refresh loop — for later refreshes call `readMirrorCollections` directly.
+ *
+ *  A `fetchPairingGrant` failure (a network blip, a transient server error)
+ *  does NOT end the wait — it's swallowed and retried on the next tick, same
+ *  as `fetchPairingGrant` returning `null` for "nothing published yet". Only
+ *  reaching `deadline` ends it: with the last error if there was one (more
+ *  informative than a bare timeout), else the generic timeout. */
+export declare function awaitPairingGrant(session: {
+    code: string;
+    device: GeneratedDeviceKeys;
+    rendezvous: {
+        baseUrl: string;
+        namespace: string;
+    };
+}, opts?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    fetch?: typeof fetch;
+}): Promise<UnsealedPairingGrant>;
+//# sourceMappingURL=pairingGrantExchange.d.ts.map

package/dist/client/pairing/pairingGrantExchange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairingGrantExchange.d.ts","sourceRoot":"","sources":["../../../src/client/pairing/pairingGrantExchange.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,UAAU,EAAmB,MAAM,oCAAoC,CAAA;AAGnG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAA;AAChF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAA;AAW7E,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AA+C5D;;;;;;;;;;;;;;;;;;;;;;+CAsB+C;AAC/C,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,OAAO,EAAE,qBAAqB,CAAA;IAC9B,MAAM,EAAE,UAAU,CAAA;IAClB,KAAK,EAAE,kBAAkB,CAAA;IACzB,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAClD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA4B5B;AAED;;;;;;;;;0BAS0B;AAC1B,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,qBAAqB,CAAA;IAC9B,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAClD,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAY5B;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAA;IACf;;gFAE4E;IAC5E,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC,CAAA;IACzD;;;;;;;;;;yBAUqB;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;4DAKwD;IACxD,KAAK,EAAE,kBAAkB,EAAE,CAAA;CAC5B;AAED;;;;;;;;;;yDAUyD;AACzD,wBAAsB,iBAAiB,CACrC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EAC1G,IAAI,GAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/E,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CA2CtC;AAED;;;;;;;;kEAQkE;AAClE,wBAAsB,iBAAiB,CACrC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EAC1G,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CAAO,GAC5E,OAAO,CAAC,oBAAoB,CAAC,CAiB/B"}