@drakkar.software/octobot-client 0.4.0

package/dist/identity/pairing.js

@@ -0,0 +1,91 @@
+import { generateDeviceKeys, mintDeviceCap } from '@drakkar.software/starfish-identities';
+import { deriveRoot } from './capProvider.js';
+import { createKeyCache } from './keys.js';
+import { deriveCollectionKeys } from '../crypto/collectionKeys.js';
+import { NODE_COLLECTIONS } from '../collections/nodeCollections.js';
+/** The two node collections a read-only pairing grants by default: enough to
+ *  reconstruct `accounts.list()`, `automations.list()`, AND `strategies.list()`
+ *  (the latter is implemented via a `userData` pull, not the legacy
+ *  `strategies` collection) — with no access to `settings`, `accountTrading`,
+ *  or the `strategies` collection itself. */
+const DEFAULT_READ_ONLY_COLLECTIONS = ['userData', 'accounts'];
+function assertKnownCollections(collections) {
+    const unknown = collections.filter((c) => !(c in NODE_COLLECTIONS));
+    if (unknown.length) {
+        throw new Error(`createReadOnlyPairing: unknown collection(s): ${unknown.join(', ')}`);
+    }
+}
+/** Mint a read-only pairing payload from the wallet's seed. The caller (e.g.
+ *  mobile2) renders the returned string as a QR code for another device to
+ *  scan — this package never renders QR images itself. The payload is fully
+ *  self-contained (it carries the node's endpoint), so
+ *  `connectReadOnlyDevice()` needs nothing else to connect. */
+export async function createReadOnlyPairing(seed, derivation, node, opts) {
+    const root = await deriveRoot(seed, derivation);
+    const device = generateDeviceKeys();
+    const collections = opts?.collections ?? DEFAULT_READ_ONLY_COLLECTIONS;
+    assertKnownCollections(collections);
+    const scope = {
+        ops: ['read', 'list'],
+        collections,
+    };
+    const cap = await mintDeviceCap(root.keys.edPriv, root.keys.edPub, { edPubHex: device.edPub, kemPubHex: device.kemPub }, scope, opts?.ttlSec != null ? { ttlSec: opts.ttlSec } : undefined);
+    const secret = await createKeyCache().getEncryptionKey(seed, derivation);
+    const collectionKeys = deriveCollectionKeys(secret, collections);
+    const payload = {
+        v: 2,
+        kind: 'octobot-read-only-pairing',
+        node,
+        rootEdPub: root.keys.edPub,
+        userId: root.userId,
+        device,
+        cap,
+        scope,
+        collectionKeys,
+    };
+    return { payload: JSON.stringify(payload) };
+}
+/** Parse and structurally validate a scanned/pasted read-only pairing
+ *  payload. Throws on anything that isn't shaped like one — callers doing QR
+ *  classification (e.g. `classifyScannedCode`) should catch and fall through
+ *  to the next candidate parser rather than propagate. */
+export function parseReadOnlyPairing(payload) {
+    let parsed;
+    try {
+        parsed = JSON.parse(payload);
+    }
+    catch {
+        throw new Error('not valid JSON');
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        throw new Error('not an object');
+    const p = parsed;
+    // A v1 payload (this package's earlier, retired pairing format) is a
+    // RECOGNIZED-but-stale payload, not an unrecognized one — a user holding
+    // an old QR should be told to re-pair, not that the code is unreadable.
+    if (p.v === 1 && p.kind === 'octobot-read-only-pairing') {
+        throw new Error('read-only pairing payload is out of date (v1) — re-pair this device to get a current one');
+    }
+    if (p.v !== 2 || p.kind !== 'octobot-read-only-pairing')
+        throw new Error('not a read-only pairing payload');
+    if (typeof p.rootEdPub !== 'string' || typeof p.userId !== 'string') {
+        throw new Error('malformed read-only pairing payload');
+    }
+    const node = p.node;
+    if (!node || typeof node.host !== 'string' || typeof node.port !== 'number') {
+        throw new Error('malformed read-only pairing payload: node');
+    }
+    const device = p.device;
+    if (!device || typeof device.edPriv !== 'string' || typeof device.kemPriv !== 'string') {
+        throw new Error('malformed read-only pairing payload: device');
+    }
+    const cap = p.cap;
+    if (!cap || cap.v !== 1 || typeof cap.sig !== 'string') {
+        throw new Error('malformed read-only pairing payload: cap');
+    }
+    if (typeof p.collectionKeys !== 'object' || p.collectionKeys === null) {
+        throw new Error('malformed read-only pairing payload: collectionKeys');
+    }
+    return p;
+}
+//# sourceMappingURL=pairing.js.map

package/dist/identity/pairing.js.map

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

package/dist/identity/pairingRequest.d.ts

@@ -0,0 +1,99 @@
+import { type GeneratedDeviceKeys } from '@drakkar.software/starfish-identities';
+import type { NodeCollectionKey } from '../collections/nodeCollections.js';
+/** A website's device-code pairing request, published to the `joinsessions`
+ *  rendezvous collection (`Infra/sync/server/drakkar_sync/apps/dk_spaces/collections.py`,
+ *  `_pairing/session/{code}`) so the phone app can look it up by the short
+ *  code the user types in. ONE address serves both phases of the exchange:
+ *  this "request" doc is later overwritten in place by the phone's sealed
+ *  "grant" doc (see `client/pairing/pairingGrantExchange.ts`) — the two
+ *  phases are told apart on the wire by the top-level `kind` field, which
+ *  the grant phase carries on an UNSEALED outer envelope specifically so a
+ *  poller can tell "not yet approved" from "approved" without needing to
+ *  unseal anything. `code` is carried on this payload (not just used as the
+ *  address) so `popSig` can bind to it — see `popSigningInput` above — and
+ *  so `parsePairingRequest` can reject a request record that doesn't match
+ *  the code it was fetched under. */
+export interface PairingRequestPayload {
+    v: 1;
+    kind: 'octobot-pairing-request';
+    code: string;
+    /** Who's asking: `'website'` — the original case, a third-party site
+     *  running this package in a browser — or `'device'` — another OctoBot
+     *  client (e.g. a second phone) pairing as a read-only viewer of this
+     *  wallet's cloud mirror. Always present on the wire; there is no
+     *  absent-means-website fallback (this package predates any published
+     *  consumer, so there was never a shape to stay compatible with). The
+     *  approving side (`website-pairing-approve.tsx` in mobile2) branches its
+     *  copy on this — a `'device'` request has no real "origin" to verify,
+     *  trust instead comes from the human typing the code themselves. */
+    requesterKind: 'website' | 'device';
+    devEdPub: string;
+    devKemPub: string;
+    /** `ed25519Suite.sign(popSigningInput(...), devEdPriv)`, hex. Proves the
+     *  requester holds `devEdPriv` — not proof of the requester's identity or
+     *  intent, which is exactly why `origin`/`code` are still what the
+     *  approving human relies on. */
+    popSig: string;
+    /** `signKemSig({kemPub: devKemPub, edPriv: devEdPriv})` (`@drakkar.software
+     *  /starfish-spaces`), hex — a SEPARATE proof-of-possession signature,
+     *  over just `devKemPub`, matching the exact `{edPub, kemPub, userId,
+     *  kemSig}` "join request" shape `starfish-spaces`' own
+     *  `parseJoinRequest`/`inviteToNode` expect. The approving side
+     *  reconstructs that join request from `devEdPub`/`devKemPub` (already
+     *  present above) plus this field — see `client/pairing/mirrorGrant.ts` —
+     *  rather than the website needing to hold a full `starfish-spaces`
+     *  `Session` just to call `makeJoinRequest()` for an identity it has no
+     *  wallet to derive. */
+    joinRequestKemSig: string;
+    /** Attacker-controlled in the sense that anyone can put any string here —
+     *  the approving side must verify it (e.g. a `.well-known` fetch), not
+     *  trust it at face value. */
+    origin: string;
+    label?: string;
+    requestedCollections?: NodeCollectionKey[];
+    createdAt: string;
+    expiresAt: string;
+    rendezvous: {
+        baseUrl: string;
+        namespace: string;
+    };
+}
+/** Create a pairing request: fresh ephemeral device keys (never the site's
+ *  own identity), a proof-of-possession signature, and a short human code.
+ *  Returns the code separately from `request` too (in addition to it being
+ *  on the payload) since the caller needs it to display immediately, before
+ *  `request` is even published. */
+export declare function createPairingRequest(opts: {
+    origin: string;
+    rendezvous: {
+        baseUrl: string;
+        namespace: string;
+    };
+    label?: string;
+    requestedCollections?: NodeCollectionKey[];
+    ttlSec?: number;
+    /** Defaults to `'website'` — the original, still-overwhelmingly-common
+     *  caller. Only a device-pairing consumer needs to pass `'device'`
+     *  explicitly. The built payload always carries the field either way. */
+    requesterKind?: 'website' | 'device';
+}): Promise<{
+    request: PairingRequestPayload;
+    device: GeneratedDeviceKeys;
+    code: string;
+}>;
+/** Parse and validate a pairing request record fetched by code. `expectedCode`
+ *  MUST be the code the caller fetched this record under (from the address,
+ *  not the payload) — rejecting a mismatch stops a request record signed
+ *  for one code from being accepted after being copied/replayed to a
+ *  different code's slot. Verifies the proof-of-possession signature and
+ *  rejects an expired request — both before the approving side does
+ *  anything else with it. Does NOT verify `origin` resolves to anything
+ *  real; that needs an actual network check the approving side performs
+ *  itself (this package stays I/O-free here). It DOES bound and
+ *  sanity-check `origin`/`label` as strings — a length cap, a URL parse for
+ *  `origin`, and rejecting control/bidi-override characters in both — since
+ *  they're the two fields an approving human actually reads and relies on.
+ *  Full homoglyph/IDNA-confusable host detection is out of scope, the same
+ *  judgment call already made for origin verification itself. */
+export declare function parsePairingRequest(payload: string, expectedCode: string): PairingRequestPayload;
+//# sourceMappingURL=pairingRequest.d.ts.map

package/dist/identity/pairingRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairingRequest.d.ts","sourceRoot":"","sources":["../../src/identity/pairingRequest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,uCAAuC,CAAA;AAIpG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAA;AAiE1E;;;;;;;;;;;;qCAYqC;AACrC,MAAM,WAAW,qBAAqB;IACpC,CAAC,EAAE,CAAC,CAAA;IACJ,IAAI,EAAE,yBAAyB,CAAA;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;yEAQqE;IACrE,aAAa,EAAE,SAAS,GAAG,QAAQ,CAAA;IACnC,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB;;;qCAGiC;IACjC,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;;;;4BASwB;IACxB,iBAAiB,EAAE,MAAM,CAAA;IACzB;;kCAE8B;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oBAAoB,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC1C,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CACnD;AAED;;;;mCAImC;AACnC,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAClD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oBAAoB,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;6EAEyE;IACzE,aAAa,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;CACrC,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,qBAAqB,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA+BzF;AAgCD;;;;;;;;;;;;;iEAaiE;AACjE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,qBAAqB,CA2EhG"}

package/dist/identity/pairingRequest.js

@@ -0,0 +1,217 @@
+import { generateDeviceKeys } from '@drakkar.software/starfish-identities';
+import { ed25519Suite } from '@drakkar.software/starfish-protocol';
+import { signKemSig } from '@drakkar.software/starfish-spaces';
+import { toHex, hexToBytes } from '../internal/bytes.js';
+/** Excludes visually-ambiguous characters (0/O, 1/I/L) — Crockford-style,
+ *  meant to be read off one screen and typed on another. 31 symbols
+ *  (23 letters + 8 digits), 8 characters ⇒ 8·log2(31) ≈ 39.63 bits of
+ *  entropy, well above RFC 8628's device-flow `user_code` minimum, and
+ *  bounded further by the rendezvous collection's short TTL and per-IP
+ *  rate limit (not something this package controls). `randomCode()` uses
+ *  rejection sampling (see `CODE_REJECT_THRESHOLD`) so this figure is the
+ *  real, uniform entropy — not a biased approximation of it. */
+const CODE_ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789';
+const CODE_LENGTH = 8;
+// 256 is not a multiple of CODE_ALPHABET.length (31) — a plain `byte %
+// length` would over-represent the first `256 % 31 = 8` symbols (A-H) by
+// 12.5% in every character position. Reject any byte at or above the
+// largest multiple of the alphabet length that still fits in a byte
+// (Math.floor(256 / 31) * 31 = 248) and draw a replacement — the remaining
+// range [0, 248) maps onto the 31 symbols with exactly uniform probability.
+const CODE_REJECT_THRESHOLD = Math.floor(256 / CODE_ALPHABET.length) * CODE_ALPHABET.length;
+const DEFAULT_REQUEST_TTL_SEC = 5 * 60;
+// `expiresAt`/`createdAt` are NOT covered by popSig — anyone with the code
+// can rewrite them, and the ONLY thing that kept the code's live window
+// actually short was the 5-minute default nobody was forced to respect.
+// This is the real enforcement: a request whose declared window exceeds it
+// is rejected outright by parsePairingRequest, and createPairingRequest
+// clamps its own ttlSec to it too so a well-meaning caller can't
+// accidentally request something this package would reject anyway.
+const MAX_REQUEST_TTL_SEC = 60 * 60;
+function randomBytes(n) {
+    const b = new Uint8Array(n);
+    globalThis.crypto.getRandomValues(b);
+    return b;
+}
+function randomCode() {
+    const chars = [];
+    // Pull a batch at a time (rather than one byte per iteration) so a run of
+    // rejected bytes doesn't turn into a syscall-per-byte loop — rejection
+    // hits ~3% of bytes, so a fresh CODE_LENGTH-sized batch almost always
+    // finishes the code outright, with a further batch only on the rare tail.
+    while (chars.length < CODE_LENGTH) {
+        const batch = randomBytes(CODE_LENGTH);
+        for (const b of batch) {
+            if (b >= CODE_REJECT_THRESHOLD)
+                continue;
+            chars.push(CODE_ALPHABET[b % CODE_ALPHABET.length]);
+            if (chars.length === CODE_LENGTH)
+                break;
+        }
+    }
+    return chars.join('');
+}
+/** What binds `code`/`devEdPub`/`devKemPub` together and proves the
+ *  requester holds `devEdPriv` — without this, a request record's public
+ *  keys could be swapped in transit with no way to detect it, and binding
+ *  `code` specifically prevents a validly-signed request minted for one
+ *  code from being replayed/republished under a DIFFERENT code (the
+ *  rendezvous collection is public-write, so anyone who captures a signed
+ *  request record could otherwise re-publish it verbatim elsewhere). Signed
+ *  over a canonical JSON of the three fields so a signature can't be
+ *  replayed across a different (key-pair, code) combination. */
+function popSigningInput(code, devEdPub, devKemPub) {
+    return new TextEncoder().encode(JSON.stringify({ code, devEdPub, devKemPub }));
+}
+/** Create a pairing request: fresh ephemeral device keys (never the site's
+ *  own identity), a proof-of-possession signature, and a short human code.
+ *  Returns the code separately from `request` too (in addition to it being
+ *  on the payload) since the caller needs it to display immediately, before
+ *  `request` is even published. */
+export async function createPairingRequest(opts) {
+    const device = generateDeviceKeys();
+    const code = randomCode();
+    // Clamped, not just defaulted — a caller passing an oversized ttlSec
+    // would otherwise create a request parsePairingRequest rejects outright
+    // (see MAX_REQUEST_TTL_SEC), silently breaking their own integration
+    // instead of getting the shortest safe window this package will accept.
+    // Does not clamp a NEGATIVE ttlSec (e.g. for testing an already-expired
+    // request) — only the upper bound is enforced here.
+    const ttlSec = Math.min(opts.ttlSec ?? DEFAULT_REQUEST_TTL_SEC, MAX_REQUEST_TTL_SEC);
+    const now = new Date();
+    const popSig = toHex(ed25519Suite.sign(popSigningInput(code, device.edPub, device.kemPub), device.edPriv));
+    const joinRequestKemSig = signKemSig({ kemPub: device.kemPub, edPriv: device.edPriv });
+    const request = {
+        v: 1,
+        kind: 'octobot-pairing-request',
+        code,
+        requesterKind: opts.requesterKind ?? 'website',
+        devEdPub: device.edPub,
+        devKemPub: device.kemPub,
+        popSig,
+        joinRequestKemSig,
+        origin: opts.origin,
+        ...(opts.label ? { label: opts.label } : {}),
+        ...(opts.requestedCollections ? { requestedCollections: opts.requestedCollections } : {}),
+        createdAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + ttlSec * 1000).toISOString(),
+        rendezvous: opts.rendezvous,
+    };
+    return { request, device, code };
+}
+// Ed25519/X25519 public keys are 32 raw bytes; an Ed25519 signature is 64 —
+// hex-encoded, that's exactly these lengths. Checked BEFORE hexToBytes is
+// called on any of them: hexToBytes allocates proportionally to input
+// length with no ceiling of its own, so an unbounded hex string here would
+// allocate before ever reaching signature verification.
+const HEX_KEY_LENGTH = 64;
+const HEX_SIG_LENGTH = 128;
+const MAX_ORIGIN_LENGTH = 2048;
+const MAX_LABEL_LENGTH = 200;
+// C0/C1 control characters (including \n, \r — RN <Text> renders an
+// embedded newline as a real line break, letting attacker text masquerade
+// as extra app chrome) plus the Unicode bidi override/isolate controls
+// (U+202A-E, U+2066-9) that can visually reverse or reorder a rendered
+// string — e.g. making a hostile host read as a different one. Written as
+// explicit \u escapes, never literal control/bidi characters in source.
+const UNSAFE_TEXT_PATTERN = /[\u0000-\u001F\u007F-\u009F\u202A-\u202E\u2066-\u2069]/;
+function assertBoundedSafeText(value, field, maxLength) {
+    if (value.length > maxLength)
+        throw new Error(`pairing request: ${field} exceeds max length`);
+    if (UNSAFE_TEXT_PATTERN.test(value)) {
+        throw new Error(`pairing request: ${field} contains a disallowed control or bidi-override character`);
+    }
+}
+function assertHexLength(value, field, expectedLength) {
+    if (value.length !== expectedLength || !/^[0-9a-fA-F]+$/.test(value)) {
+        throw new Error(`pairing request: ${field} is not a valid ${expectedLength}-character hex string`);
+    }
+}
+/** Parse and validate a pairing request record fetched by code. `expectedCode`
+ *  MUST be the code the caller fetched this record under (from the address,
+ *  not the payload) — rejecting a mismatch stops a request record signed
+ *  for one code from being accepted after being copied/replayed to a
+ *  different code's slot. Verifies the proof-of-possession signature and
+ *  rejects an expired request — both before the approving side does
+ *  anything else with it. Does NOT verify `origin` resolves to anything
+ *  real; that needs an actual network check the approving side performs
+ *  itself (this package stays I/O-free here). It DOES bound and
+ *  sanity-check `origin`/`label` as strings — a length cap, a URL parse for
+ *  `origin`, and rejecting control/bidi-override characters in both — since
+ *  they're the two fields an approving human actually reads and relies on.
+ *  Full homoglyph/IDNA-confusable host detection is out of scope, the same
+ *  judgment call already made for origin verification itself. */
+export function parsePairingRequest(payload, expectedCode) {
+    let parsed;
+    try {
+        parsed = JSON.parse(payload);
+    }
+    catch {
+        throw new Error('not valid JSON');
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        throw new Error('not an object');
+    const p = parsed;
+    if (p.v !== 1 || p.kind !== 'octobot-pairing-request')
+        throw new Error('not a pairing request payload');
+    if (typeof p.code !== 'string' || typeof p.devEdPub !== 'string' || typeof p.devKemPub !== 'string'
+        || typeof p.popSig !== 'string' || typeof p.joinRequestKemSig !== 'string' || typeof p.origin !== 'string'
+        || typeof p.createdAt !== 'string' || typeof p.expiresAt !== 'string') {
+        throw new Error('malformed pairing request payload');
+    }
+    if (p.requesterKind !== 'website' && p.requesterKind !== 'device') {
+        throw new Error('malformed pairing request payload: requesterKind');
+    }
+    if (p.code !== expectedCode) {
+        throw new Error('pairing request: code does not match the address it was fetched from');
+    }
+    const rendezvous = p.rendezvous;
+    if (!rendezvous || typeof rendezvous.baseUrl !== 'string' || typeof rendezvous.namespace !== 'string') {
+        throw new Error('malformed pairing request payload: rendezvous');
+    }
+    if (p.label !== undefined && typeof p.label !== 'string') {
+        throw new Error('malformed pairing request payload: label');
+    }
+    assertHexLength(p.devEdPub, 'devEdPub', HEX_KEY_LENGTH);
+    assertHexLength(p.devKemPub, 'devKemPub', HEX_KEY_LENGTH);
+    assertHexLength(p.popSig, 'popSig', HEX_SIG_LENGTH);
+    assertHexLength(p.joinRequestKemSig, 'joinRequestKemSig', HEX_SIG_LENGTH);
+    assertBoundedSafeText(p.origin, 'origin', MAX_ORIGIN_LENGTH);
+    if (p.label !== undefined)
+        assertBoundedSafeText(p.label, 'label', MAX_LABEL_LENGTH);
+    try {
+        new URL(p.origin);
+    }
+    catch {
+        throw new Error('pairing request: origin is not a valid URL');
+    }
+    const request = p;
+    const verified = ed25519Suite.verify(hexToBytes(request.popSig), popSigningInput(request.code, request.devEdPub, request.devKemPub), request.devEdPub);
+    if (!verified)
+        throw new Error('pairing request: invalid proof-of-possession signature');
+    // Date.parse of a malformed string returns NaN, and every comparison
+    // against NaN is false — so a garbage expiresAt would otherwise be
+    // silently treated as "not expired" instead of rejected. Fail closed.
+    const expiresAtMs = Date.parse(request.expiresAt);
+    if (!Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now())
+        throw new Error('pairing request: expired');
+    // The actual enforcement of "short-lived code" — expiresAt/createdAt are
+    // NOT covered by popSig, so a party with the code can rewrite either to
+    // anything. An earlier version of this check compared expiresAt against
+    // the request's OWN createdAt — trivially bypassable, since an attacker
+    // controlling both fields can place them arbitrarily far in the future
+    // while keeping their difference inside the cap, making the code "look"
+    // freshly issued no matter when it's actually redeemed (e.g.
+    // createdAt = now+364d, expiresAt = now+364d+1h — passes a
+    // createdAt-relative check, but the code stays "valid" for the next
+    // year). Anchoring to THIS CALL's real wall clock instead closes that:
+    // a request cannot claim to remain valid more than MAX_REQUEST_TTL_SEC
+    // from right now, independent of what it claims createdAt to be.
+    // createdAt itself is otherwise purely informational — never used for
+    // any security decision here.
+    if (expiresAtMs - Date.now() > MAX_REQUEST_TTL_SEC * 1000) {
+        throw new Error('pairing request: expiry window exceeds the maximum this package allows');
+    }
+    return request;
+}
+//# sourceMappingURL=pairingRequest.js.map

package/dist/identity/pairingRequest.js.map

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

package/dist/identity/secret.d.ts

@@ -0,0 +1,32 @@
+/** What a string of key material turned out to be. */
+export type ClassifiedSecret = {
+    kind: 'privateKey';
+    value: string;
+} | {
+    kind: 'seed';
+    value: string;
+} | {
+    kind: 'unknown';
+};
+/** Classify key material that arrived somewhere already known to hold it — a
+ *  pairing payload's `password`, a standalone `{"password": "…"}` code, or a
+ *  phrase typed by hand.
+ *
+ *  The `0x` prefix picks the branch, and the branch still validates: a value
+ *  that is neither a real key nor a real phrase has to be rejected rather than
+ *  quietly produce a wallet nobody owns.
+ *
+ *  Note what this deliberately does **not** decide: which derivation SCHEME
+ *  a `seed` needs, if a caller has registered more than the built-in
+ *  `'bip44'` (see `derivationSchemes.ts`) — that depends on where the phrase
+ *  came from, not on its shape. */
+export declare function classifySecret(raw: string): Promise<ClassifiedSecret>;
+/** Classify a bare scanned/typed value, where no field name says which shape to
+ *  expect, so both are tried. Unlike `classifySecret` an unprefixed 64-hex still
+ *  reads as a key here — there is no envelope to say otherwise. */
+export declare function classifyBareSecret(raw: string): Promise<ClassifiedSecret>;
+/** The wallet inside a standalone `{"password": "…"}` code — JSON carrying key
+ *  material directly, with no node attached to fetch it from. Null when the
+ *  value is not that shape. */
+export declare function readSecretEnvelope(data: string): string | null;
+//# sourceMappingURL=secret.d.ts.map

package/dist/identity/secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret.d.ts","sourceRoot":"","sources":["../../src/identity/secret.ts"],"names":[],"mappings":"AAGA,sDAAsD;AACtD,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAA;AAEvB;;;;;;;;;;;mCAWmC;AACnC,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAW3E;AAED;;mEAEmE;AACnE,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAS/E;AAED;;+BAE+B;AAC/B,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU9D"}

package/dist/identity/secret.js

@@ -0,0 +1,54 @@
+import { isEvmPrivateKey, normalizeEvmPrivateKey } from './evm.js';
+import { validateSeedPhrase } from './mnemonic.js';
+/** Classify key material that arrived somewhere already known to hold it — a
+ *  pairing payload's `password`, a standalone `{"password": "…"}` code, or a
+ *  phrase typed by hand.
+ *
+ *  The `0x` prefix picks the branch, and the branch still validates: a value
+ *  that is neither a real key nor a real phrase has to be rejected rather than
+ *  quietly produce a wallet nobody owns.
+ *
+ *  Note what this deliberately does **not** decide: which derivation SCHEME
+ *  a `seed` needs, if a caller has registered more than the built-in
+ *  `'bip44'` (see `derivationSchemes.ts`) — that depends on where the phrase
+ *  came from, not on its shape. */
+export async function classifySecret(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.toLowerCase().startsWith('0x')) {
+        const key = normalizeEvmPrivateKey(trimmed);
+        return isEvmPrivateKey(key) ? { kind: 'privateKey', value: key } : { kind: 'unknown' };
+    }
+    const phrase = trimmed.split(/\s+/).map((w) => w.toLowerCase()).filter(Boolean).join(' ');
+    if (phrase && (await validateSeedPhrase(phrase)))
+        return { kind: 'seed', value: phrase };
+    return { kind: 'unknown' };
+}
+/** Classify a bare scanned/typed value, where no field name says which shape to
+ *  expect, so both are tried. Unlike `classifySecret` an unprefixed 64-hex still
+ *  reads as a key here — there is no envelope to say otherwise. */
+export async function classifyBareSecret(raw) {
+    const trimmed = raw.trim();
+    const key = normalizeEvmPrivateKey(trimmed);
+    if (isEvmPrivateKey(key))
+        return { kind: 'privateKey', value: key };
+    const phrase = trimmed.split(/\s+/).map((w) => w.toLowerCase()).filter(Boolean).join(' ');
+    if (phrase && (await validateSeedPhrase(phrase)))
+        return { kind: 'seed', value: phrase };
+    return { kind: 'unknown' };
+}
+/** The wallet inside a standalone `{"password": "…"}` code — JSON carrying key
+ *  material directly, with no node attached to fetch it from. Null when the
+ *  value is not that shape. */
+export function readSecretEnvelope(data) {
+    try {
+        const parsed = JSON.parse(data.trim());
+        if (parsed && typeof parsed === 'object' && typeof parsed.password === 'string') {
+            return parsed.password;
+        }
+    }
+    catch {
+        // not JSON — not an envelope
+    }
+    return null;
+}
+//# sourceMappingURL=secret.js.map

package/dist/identity/secret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret.js","sourceRoot":"","sources":["../../src/identity/secret.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAQlD;;;;;;;;;;;mCAWmC;AACnC,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAW;IAC9C,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAA;IAE1B,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAA;QAC3C,OAAO,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAA;IACxF,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACzF,IAAI,MAAM,IAAI,CAAC,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;IACxF,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAA;AAC5B,CAAC;AAED;;mEAEmE;AACnE,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAW;IAClD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAA;IAE1B,MAAM,GAAG,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAA;IAC3C,IAAI,eAAe,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;IAEnE,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACzF,IAAI,MAAM,IAAI,CAAC,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;IACxF,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAA;AAC5B,CAAC;AAED;;+BAE+B;AAC/B,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;QACtC,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAChF,OAAO,MAAM,CAAC,QAAQ,CAAA;QACxB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,6BAA6B;IAC/B,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { connectOctoBot, type OctoBotClient, type ConnectOptions, type SeedDerivation, type CallOptions, type AccountsApi, type AccountInput, type AutomationsApi, type CreateAutomationInput, type CreateAutomationProgress, type StrategiesApi, type SettingsApi, type NodeApi, type DocumentsApi, type ReadOnlyDocumentsApi, type ActionHandle, type AccountView, type AccountKind, type AutomationView, type Holding, OctoBotError, OctoBotConfigError, OctoBotConnectionError, OctoBotAuthError, OctoBotHttpError, OctoBotConflictError, OctoBotActionError, OctoBotTimeoutError, OctoBotScopeError, isOctoBotError, type OctoBotErrorCode, connectReadOnlyDevice, type ConnectReadOnlyOptions, type ReadOnlyOctoBotClient, type ReadOnlyAccountsApi, type ReadOnlyAutomationsApi, type ReadOnlyStrategiesApi, type ProposedAction, accountViewOf, automationViewOf, startPairingRequest, fetchPairingRequestByCode, type StartPairingRequestOptions, type PairingRequestSession, type PairingRequestLookup, buildJoinRequestJson, mintPairingGrant, revokePairingGrant, NothingToShareError, type MintedPairingGrant, parseMirrorGrantBundle, readMirrorCollections, attemptDirectMirrorWrite, type MirrorGrantBundle, type MirrorGrantNodeRef, type ReadMirrorCollectionsOptions, type AttemptDirectMirrorWriteOptions, publishPairingGrant, clearPairingGrant, fetchPairingGrant, awaitPairingGrant, type UnsealedPairingGrant, } from './client/index.js';
+export { MIRROR_COLLECTIONS, DEFAULT_MIRROR_COLLECTIONS, THIRD_PARTY_ELIGIBLE_MIRROR_COLLECTIONS, MIRROR_SPACE_NAME, isIsolatedMirrorCollection, isKnownMirrorCollection, isPublicMirrorCollection, isThirdPartyEligible, mirrorVisibilityFor, type MirrorCollection, type MirrorCollectionId, type MirrorVisibility, syncCloudMirror, type SyncCloudMirrorOptions, type SyncCloudMirrorResult, } from './client/mirror/index.js';
+export { strategy, type StrategyBuilders } from './client/strategy.js';
+export { createReadOnlyPairing, parseReadOnlyPairing, type ReadOnlyPairingPayload } from './identity/pairing.js';
+export { createPairingRequest, parsePairingRequest, type PairingRequestPayload } from './identity/pairingRequest.js';
+export { createRendezvousClient, pullRendezvousDoc, pushRendezvousDoc, clearRendezvousDoc, joinSessionPath, type RendezvousDoc, } from './transport/rendezvous.js';
+export { encodeActionProposal, decodeActionProposal, type ActionProposal, type ProposedActionEntry } from './protocol/proposal.js';
+export type { Strategy as ProtocolStrategy, Account as ProtocolAccount, AccountState, AccountAuthentication, ExchangeConfig, AutomationState, WorkflowStatus, DetailedAsset, UserAction, UserActionConfiguration, DslKeywordsState, MarketMakingConfiguration, AccountTrading, AccountTradingWithAccountId, DetailedAssetsForTradingType, CreateAutomationConfiguration, } from '@drakkar.software/octobot-protocol';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,YAAY,EACZ,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,KAAK,gBAAgB,EACrB,qBAAqB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,4BAA4B,EACjC,KAAK,+BAA+B,EACpC,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,uCAAuC,EACvC,iBAAiB,EACjB,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,QAAQ,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACtE,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAChH,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,KAAK,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AACpH,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,KAAK,aAAa,GACnB,MAAM,2BAA2B,CAAA;AAClC,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAOlI,YAAY,EACV,QAAQ,IAAI,gBAAgB,EAC5B,OAAO,IAAI,eAAe,EAC1B,YAAY,EACZ,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,cAAc,EACd,aAAa,EACb,UAAU,EACV,uBAAuB,EACvB,gBAAgB,EAChB,yBAAyB,EACzB,cAAc,EACd,2BAA2B,EAC3B,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,oCAAoC,CAAA"}

package/dist/index.js

@@ -0,0 +1,18 @@
+// @drakkar.software/octobot-client — a TypeScript client for the OctoBot node
+// protocol: wallet identity, accounts, automations, strategies, and user
+// actions over the Starfish sync transport.
+//
+// This is the facade tier. It keeps no document cache and no offline
+// queue — every read is a fresh pull, every write is a fresh push/append.
+// An app that needs persistence, an offline queue, or CRDT merge across
+// devices builds that layer ON TOP of this package (see
+// https://docs.octobot.cloud/client-sdk/advanced-primitives for the subpath
+// exports this is built from).
+export { connectOctoBot, OctoBotError, OctoBotConfigError, OctoBotConnectionError, OctoBotAuthError, OctoBotHttpError, OctoBotConflictError, OctoBotActionError, OctoBotTimeoutError, OctoBotScopeError, isOctoBotError, connectReadOnlyDevice, accountViewOf, automationViewOf, startPairingRequest, fetchPairingRequestByCode, buildJoinRequestJson, mintPairingGrant, revokePairingGrant, NothingToShareError, parseMirrorGrantBundle, readMirrorCollections, attemptDirectMirrorWrite, publishPairingGrant, clearPairingGrant, fetchPairingGrant, awaitPairingGrant, } from './client/index.js';
+export { MIRROR_COLLECTIONS, DEFAULT_MIRROR_COLLECTIONS, THIRD_PARTY_ELIGIBLE_MIRROR_COLLECTIONS, MIRROR_SPACE_NAME, isIsolatedMirrorCollection, isKnownMirrorCollection, isPublicMirrorCollection, isThirdPartyEligible, mirrorVisibilityFor, syncCloudMirror, } from './client/mirror/index.js';
+export { strategy } from './client/strategy.js';
+export { createReadOnlyPairing, parseReadOnlyPairing } from './identity/pairing.js';
+export { createPairingRequest, parsePairingRequest } from './identity/pairingRequest.js';
+export { createRendezvousClient, pullRendezvousDoc, pushRendezvousDoc, clearRendezvousDoc, joinSessionPath, } from './transport/rendezvous.js';
+export { encodeActionProposal, decodeActionProposal } from './protocol/proposal.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,yEAAyE;AACzE,4CAA4C;AAC5C,EAAE;AACF,qEAAqE;AACrE,0EAA0E;AAC1E,wEAAwE;AACxE,wDAAwD;AACxD,4EAA4E;AAC5E,+BAA+B;AAE/B,OAAO,EACL,cAAc,EAoBd,YAAY,EACZ,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EAEd,qBAAqB,EAOrB,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EAIzB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EAEnB,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EAKxB,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAElB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,uCAAuC,EACvC,iBAAiB,EACjB,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,mBAAmB,EAInB,eAAe,GAGhB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,QAAQ,EAAyB,MAAM,sBAAsB,CAAA;AACtE,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAA+B,MAAM,uBAAuB,CAAA;AAChH,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAA8B,MAAM,8BAA8B,CAAA;AACpH,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,GAEhB,MAAM,2BAA2B,CAAA;AAClC,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAiD,MAAM,wBAAwB,CAAA"}

package/dist/internal/bytes.d.ts

@@ -0,0 +1,11 @@
+export declare function toHex(b: Uint8Array): string;
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function toBase64(bytes: Uint8Array): string;
+export declare function fromBase64(b64: string): Uint8Array<ArrayBuffer>;
+/** URL-safe base64 (`+/` → `-_`, no `=` padding) of raw bytes. Distinct from
+ *  `starfish-protocol`'s `toBase64Url`, which encodes a UTF-8 *string* — not
+ *  usable here since not every byte sequence (e.g. random session-id bytes)
+ *  round-trips through UTF-8. */
+export declare function toBase64Url(bytes: Uint8Array): string;
+export declare function fromBase64Url(b64url: string): Uint8Array<ArrayBuffer>;
+//# sourceMappingURL=bytes.d.ts.map

package/dist/internal/bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../../src/internal/bytes.ts"],"names":[],"mappings":"AAKA,wBAAgB,KAAK,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAE3C;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAKlD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAElD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAM/D;AAED;;;iCAGiC;AACjC,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAErD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAIrE"}