@actana/sdk 0.3.3 → 0.4.1

package/dist/core-pairing-csr.js

@@ -0,0 +1,159 @@
+// The client half of pairing that never leaves the machine: a key pair, and the
+// certificate signing request that proves possession of it (#280, #284).
+//
+// A pairing exchange hands a Core a *public* key and gets a certificate back.
+// This module is where the other half stays. Everything here runs before a
+// socket is opened, and the only value that ever crosses one is
+// {@link ClientCsr.csrPem} — the private key is returned to the caller, put
+// into the resulting `CoreRegistrationBlob`, and never given to
+// `core-pairing.ts` in a form it could serialise.
+//
+// **Why a hand-written PKCS#10 encoder rather than a library.** `node:crypto`
+// generates key pairs and signs, and it exports a public key as a DER
+// `SubjectPublicKeyInfo` — which is the only structure in a CSR that is hard to
+// produce. What is left is four fields in a fixed order (RFC 2986 §4), so the
+// choice was a ~90-line encoder against a new dependency on the one package in
+// this repository whose dependency list is a reviewed artifact
+// (`__tests__/package-boundaries.test.ts`, and ADR 0025's "a private one is a
+// broken install"). The encoder is checked where it counts: the suite posts
+// what it produces at the real Core, whose `assertSignableCsr` parses it with
+// `@peculiar/x509` and verifies the signature before signing. A CSR this file
+// got wrong fails that test rather than shipping.
+//
+// **RSA-2048, matching the Core.** `@actana/shared/core-cert-material` refuses
+// anything under 2048 bits (`MIN_RSA_MODULUS_BITS`), and its own
+// `generateClientCsr` mints exactly this. A client that asked for something
+// more exotic would be betting on the CA's parser rather than on the algorithm
+// the CA is known to sign.
+import { generateKeyPair, sign } from "node:crypto";
+/** Modulus size. See the header: what the Core's CA is known to sign. */
+const RSA_MODULUS_BITS = 2048;
+/** Longest common name written into the request. The Core caps its own at 48. */
+const MAX_COMMON_NAME = 48;
+/** The common name used when a caller offers nothing usable. */
+const FALLBACK_COMMON_NAME = "actana-client";
+/**
+ * Mint a key pair and a CSR naming `commonName`.
+ *
+ * The subject here is a *request*, and the Core does not honour it: the
+ * certificate is issued for the label the operator typed when they opened the
+ * pairing session (`core-pairing-routes.ts`, "the subject is the Core's to
+ * write"). It is filled in anyway because a CSR with an empty subject is a
+ * worse artifact to debug than one that says which machine asked.
+ */
+export async function generateClientCsr(commonName) {
+    const { publicKey, privateKey } = await new Promise((resolve, reject) => {
+        generateKeyPair("rsa", { modulusLength: RSA_MODULUS_BITS }, (err, publicKey, privateKey) => {
+            if (err)
+                reject(err);
+            else
+                resolve({ publicKey, privateKey });
+        });
+    });
+    const spki = new Uint8Array(publicKey.export({ type: "spki", format: "der" }));
+    const info = derSequence(DER_VERSION_V1, derName(certificationRequestName(commonName)), spki, 
+    // `attributes [0] IMPLICIT SET OF Attribute`, empty. Not optional in RFC
+    // 2986 — a request with the field left out is one some parsers reject —
+    // and nothing this client asks for belongs in it: requested extensions are
+    // exactly what the Core refuses to honour.
+    DER_EMPTY_ATTRIBUTES);
+    // RSASSA-PKCS1-v1_5 over SHA-256, which is what `sign` produces for an RSA
+    // key with no `padding` given, and what the algorithm identifier below says.
+    const signature = new Uint8Array(sign("sha256", info, privateKey));
+    const csr = derSequence(info, DER_SHA256_WITH_RSA, derBitString(signature));
+    return {
+        csrPem: derToPem("CERTIFICATE REQUEST", csr),
+        privateKeyPem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+    };
+}
+/**
+ * A common name as it can appear in a distinguished name.
+ *
+ * Same conservative set the Core applies to the label it issues for, for the
+ * same reason: an X.509 name is structure, `,` and `=` and `+` are part of it,
+ * and a CSR is not the place to find out whose escaping is right.
+ */
+function certificationRequestName(label) {
+    const cleaned = label.replace(/[^A-Za-z0-9 ._-]/g, "-").trim().slice(0, MAX_COMMON_NAME);
+    return cleaned.length > 0 ? cleaned : FALLBACK_COMMON_NAME;
+}
+// ─── A DER writer, as much of one as a CSR needs ───
+//
+// Tags are written as constants rather than an enum: there are five of them,
+// each is used once, and a reader checking this file against RFC 2986 wants the
+// byte.
+/** `INTEGER 0` — `version` is v1, and v1 is zero. */
+const DER_VERSION_V1 = Uint8Array.from([0x02, 0x01, 0x00]);
+/** `[0]` constructed, zero-length: the empty attribute set. */
+const DER_EMPTY_ATTRIBUTES = Uint8Array.from([0xa0, 0x00]);
+/**
+ * `AlgorithmIdentifier` for `sha256WithRSAEncryption` — OID
+ * 1.2.840.113549.1.1.11, with the explicit `NULL` parameters RFC 4055 §5
+ * requires for it. Written out because it is a constant in every request this
+ * file produces; an OID encoder would be more code and one more thing to get
+ * wrong.
+ */
+const DER_SHA256_WITH_RSA = Uint8Array.from([
+    0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x0b, 0x05, 0x00,
+]);
+/** OID 2.5.4.3, `id-at-commonName`. */
+const DER_OID_COMMON_NAME = Uint8Array.from([0x06, 0x03, 0x55, 0x04, 0x03]);
+/** `SEQUENCE` of the given already-encoded members. */
+function derSequence(...members) {
+    return derTagged(0x30, concat(members));
+}
+/** `RDNSequence` with the one relative distinguished name `CN=<value>`. */
+function derName(commonName) {
+    const attribute = derSequence(DER_OID_COMMON_NAME, derUtf8String(commonName));
+    const rdn = derTagged(0x31, attribute); // SET
+    return derSequence(rdn);
+}
+function derUtf8String(value) {
+    return derTagged(0x0c, new TextEncoder().encode(value));
+}
+/**
+ * `BIT STRING` holding whole bytes.
+ *
+ * The leading zero is the count of unused bits in the final byte. A signature
+ * is a whole number of bytes, so it is always zero — and it is always present,
+ * because a `BIT STRING` without it is a malformed one.
+ */
+function derBitString(bytes) {
+    return derTagged(0x03, concat([Uint8Array.from([0x00]), bytes]));
+}
+/** `tag | length | content`, with the length in DER's short or long form. */
+function derTagged(tag, content) {
+    return concat([Uint8Array.from([tag]), derLength(content.length), content]);
+}
+/**
+ * DER's definite length.
+ *
+ * Under 128 the length is the byte. At or above it, the first byte is `0x80`
+ * plus the number of bytes that follow, big-endian and with no leading zero —
+ * the "minimal number of octets" DER insists on, which is why this counts the
+ * bytes rather than always writing four.
+ */
+function derLength(length) {
+    if (length < 0x80)
+        return Uint8Array.from([length]);
+    const bytes = [];
+    for (let rest = length; rest > 0; rest = Math.floor(rest / 256))
+        bytes.unshift(rest % 256);
+    return Uint8Array.from([0x80 | bytes.length, ...bytes]);
+}
+function concat(parts) {
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+/** DER to PEM: base64 in 64-column lines between the two armour lines. */
+function derToPem(label, der) {
+    const body = Buffer.from(der).toString("base64").replace(/(.{64})/g, "$1\n").trimEnd();
+    return `-----BEGIN ${label}-----\n${body}\n-----END ${label}-----\n`;
+}
+//# sourceMappingURL=core-pairing-csr.js.map

package/dist/core-pairing-csr.js.map

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

package/dist/core-pairing-wire.d.ts

@@ -0,0 +1,63 @@
+/** The one route a client with no certificate may reach on a Core. */
+export declare const CORE_PAIRING_REDEEM_PATH = "/v1/pair/redeem";
+/**
+ * What the client says about itself.
+ *
+ * The Core keeps the label and ignores the rest. "Ignores" is the honest word
+ * and is checked by `parseRedeemRequest`: an optional field a server drops is a
+ * client courtesy, not a promise the server has broken.
+ */
+export type CorePairingClientInfo = {
+    /** The machine's own name for itself, e.g. a hostname. */
+    label?: string;
+    /**
+     * `process.platform`, sent by the CLI and the Panel.
+     *
+     * The Core reads it off the wire and stores nothing: it is not on
+     * {@link https://github.com/actana/control/issues/280 #280}'s paired-client
+     * record and `actana pair ls` does not show it. Surfacing it means adding a
+     * persisted field, which is a ticket rather than a parser change — #306's
+     * review raised it and it is tracked there.
+     */
+    platform?: string;
+};
+/**
+ * The redemption request body.
+ *
+ * `sessionId` names the pairing session the code belongs to and is not
+ * optional: the Core hashes a candidate code together with the session id and
+ * refuses to search for a session a code might fit, which is what stops a code
+ * lifted from one session being replayed against another.
+ */
+export type CorePairingRedeemRequest = {
+    sessionId: string;
+    code: string;
+    client: CorePairingClientInfo;
+    /** PEM `CERTIFICATE REQUEST`. The private half is not in this object. */
+    csr: string;
+};
+/**
+ * The 200 body.
+ *
+ * Four fields, and the absence of a fifth is the point: there is no key here,
+ * because the Core never had one. `pairWithCore` supplies the fifth from the
+ * key it generated locally.
+ */
+export type CorePairingRedeemResponse = {
+    /** The `wss://host:port` core link to dial from now on. */
+    endpoint: string;
+    /** PEM CA certificate — the trust anchor for every later dial. */
+    caCert: string;
+    /** PEM client certificate, signed from the CSR just posted. */
+    clientCert: string;
+    /** The signed bearer for the `auth` frame. */
+    bearer: string;
+};
+/** A refusal body, as every non-200 answer from the pairing route is shaped. */
+export type CorePairingRefusalBody = {
+    /** The Core's machine-readable reason, e.g. `pairing-refused`. */
+    code?: string;
+    /** The human-readable one. */
+    error?: string;
+};
+//# sourceMappingURL=core-pairing-wire.d.ts.map

package/dist/core-pairing-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-pairing-wire.d.ts","sourceRoot":"","sources":["../src/core-pairing-wire.ts"],"names":[],"mappings":"AAoBA,sEAAsE;AACtE,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,qBAAqB,CAAC;IAC9B,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,gFAAgF;AAChF,MAAM,MAAM,sBAAsB,GAAG;IACnC,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC"}

package/dist/core-pairing-wire.js

@@ -0,0 +1,22 @@
+// The pairing route's wire contract, and nothing else.
+//
+// This file exists so that the redeem request and response have **one**
+// definition rather than two structurally identical ones — [ADR 0025][adr] D3:
+// *"There is exactly one definition of every frame type, and a mirror is never
+// the answer."* Until #306's review it was a mirror: `core-pairing.ts` declared
+// the shapes for the client and `packages/core/src/core-pairing-routes.ts`
+// hand-built the same shapes for the server, and nothing compiled the two
+// against each other. A mirror does not fail; it disagrees, at runtime, on a
+// wire, between two processes that each believe they are correct.
+//
+// It is a separate module from `core-pairing.ts` because of what D2 requires of
+// anything the Core imports: **no I/O, no transport and no imports of its
+// own.** `core-pairing.ts` dials, hashes and reads certificates, so a Core
+// importing it would be a Core dialling itself. This file has no imports, and
+// that is a property to preserve rather than a coincidence — it is the reason
+// D2's list is allowed to grow to include it.
+//
+// [adr]: ../../docs/adr/0025-the-protocol-ships-with-the-client.md
+/** The one route a client with no certificate may reach on a Core. */
+export const CORE_PAIRING_REDEEM_PATH = "/v1/pair/redeem";
+//# sourceMappingURL=core-pairing-wire.js.map

package/dist/core-pairing-wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-pairing-wire.js","sourceRoot":"","sources":["../src/core-pairing-wire.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,wEAAwE;AACxE,+EAA+E;AAC/E,+EAA+E;AAC/E,gFAAgF;AAChF,2EAA2E;AAC3E,0EAA0E;AAC1E,6EAA6E;AAC7E,kEAAkE;AAClE,EAAE;AACF,gFAAgF;AAChF,0EAA0E;AAC1E,2EAA2E;AAC3E,8EAA8E;AAC9E,8EAA8E;AAC9E,8CAA8C;AAC9C,EAAE;AACF,mEAAmE;AAEnE,sEAAsE;AACtE,MAAM,CAAC,MAAM,wBAAwB,GAAG,iBAAiB,CAAC"}

package/dist/core-pairing.d.ts

@@ -0,0 +1,211 @@
+import type { CoreRegistrationBlob } from "./core-registration-blob.ts";
+export { CORE_PAIRING_REDEEM_PATH, type CorePairingClientInfo, type CorePairingRedeemRequest, type CorePairingRedeemResponse, type CorePairingRefusalBody, } from "./core-pairing-wire.ts";
+/**
+ * Why a pairing attempt did not produce a blob.
+ *
+ * The list is what a caller can *act* on, and it stops where the Core's own
+ * answers stop. `refused` covers a wrong code, an expired session, one already
+ * redeemed and one whose attempts are spent, because the Core answers all four
+ * with one status and one body on purpose (`core-pairing-routes.ts`, "every
+ * refusal is the same refusal"): telling them apart on the wire would tell an
+ * attacker whether a session exists and whether their last guess was closer.
+ * A client that reported four different things would be inventing three of
+ * them. The distinction the operator needs is in the Core's audit log, which
+ * is where #282 put it deliberately.
+ */
+export type CorePairingFailure = 
+/** The address could not be read as a Core's HTTPS or core-link address. */
+"bad-address"
+/** The code was not eight characters, or named no pairing session. */
+ | "bad-code"
+/** The expected fingerprint was not a SHA-256 fingerprint. */
+ | "bad-fingerprint"
+/** Nothing answered at that address, or the dial timed out. */
+ | "unreachable"
+/** The Core presented a chain with no CA in it — nothing to pin. */
+ | "no-ca-presented"
+/** No fingerprint was given to check against. The code was not sent. */
+ | "fingerprint-unconfirmed"
+/** The presented CA is not the expected one. The code was not sent. */
+ | "fingerprint-mismatch"
+/**
+ * The expected CA, on an address its certificate does not cover.
+ *
+ * Its own failure rather than a mismatch, because it is not an attack and
+ * saying so sends the operator hunting for one: a Core's server certificate
+ * covers the host it was set up for plus loopback, so reaching a Core over a
+ * second interface, a tunnel or a DNS name added later fails here with the
+ * fingerprint matching perfectly.
+ */
+ | "hostname-mismatch"
+/** The expected CA, and a certificate that is expired or otherwise unusable. */
+ | "certificate-invalid"
+/** Wrong, expired, already redeemed, or out of attempts — see above. */
+ | "refused"
+/** Too many attempts from this client, too fast. Try again later. */
+ | "rate-limited"
+/** The Core would not accept the request itself — a bug on this side. */
+ | "rejected"
+/** There is no pairing endpoint on that Core. */
+ | "not-pairable"
+/** The Core failed while handling the redemption. */
+ | "core-error"
+/** A 200 that was not a redemption response. */
+ | "malformed-response";
+/** Everything a failure knows beyond its {@link CorePairingFailure}. */
+export type CorePairingErrorDetail = {
+    /** The HTTP status, when the failure came from one. */
+    status?: number;
+    /** `retry-after`, in seconds, on a `rate-limited` failure. */
+    retryAfterSeconds?: number;
+    /** The Core's own refusal code, when it sent one. */
+    coreCode?: string;
+    /** The fingerprint the caller was told to expect. */
+    expectedFingerprint?: string;
+    /** The fingerprint the Core actually presented. */
+    presentedFingerprint?: string;
+    /** The CA the Core presented, PEM — for a UI that wants to show it. */
+    presentedCaCert?: string;
+    /** The TLS or OpenSSL code behind a dial failure, e.g. `CERT_HAS_EXPIRED`. */
+    tlsCode?: string;
+};
+/**
+ * A pairing attempt that did not produce a blob.
+ *
+ * One class with a {@link CorePairingFailure} rather than a class per failure:
+ * the CLI (#285) and the Panel (#286) both switch on the reason to write a
+ * sentence, and a `switch` over a union is checked by the compiler where a
+ * chain of `instanceof` is not.
+ */
+export declare class CorePairingError extends Error {
+    readonly name = "CorePairingError";
+    /** Which failure this is. Switch on it; do not read the message. */
+    readonly failure: CorePairingFailure;
+    /** Whatever the failure knows beyond its reason. */
+    readonly detail: CorePairingErrorDetail;
+    constructor(failure: CorePairingFailure, message: string, detail?: CorePairingErrorDetail, options?: {
+        cause?: unknown;
+    });
+}
+/** What a bootstrap dial learns about a Core before anything is trusted. */
+export type CorePairingIdentity = {
+    /** SHA-256 over the CA's DER, colon-separated uppercase hex. */
+    fingerprint: string;
+    /** The PEM CA certificate that fingerprint is of. */
+    caCert: string;
+    /** The host that was dialled. */
+    host: string;
+    /** The port that was dialled. */
+    port: number;
+    /** `https://host:port` — where a redemption would be posted. */
+    httpsOrigin: string;
+};
+/** How long a dial or a redemption may take before it is called unreachable. */
+export declare const DEFAULT_PAIRING_TIMEOUT_MS = 15000;
+/**
+ * Dial a Core and report the CA it presents — **without a code to send**.
+ *
+ * This is the first-contact mode, and the reason it is a separate function
+ * rather than a flag is that it takes no code: a UI that shows the operator's
+ * fingerprint beside the Core's, and asks a human whether they match, cannot
+ * leak a secret it was never given. {@link pairWithCore} calls it too, so the
+ * fingerprint a caller confirms is computed by the same code that later
+ * enforces it.
+ *
+ * The dial is unverified, because at this point in the flow there is nothing to
+ * verify against — that is what the fingerprint the operator read out is for.
+ * Nothing is sent on this connection and it is closed as soon as the chain has
+ * been read.
+ */
+export declare function fetchCorePairingIdentity(opts: {
+    /** `host:port`, `https://host:port` or `wss://host:port`. */
+    address: string;
+    /** Defaults to {@link DEFAULT_PAIRING_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}): Promise<CorePairingIdentity>;
+export type PairWithCoreOptions = {
+    /** The Core's address: `host:port`, `https://host:port` or `wss://host:port`. */
+    address: string;
+    /**
+     * The pairing code the operator read out — `XXXX-XXXX`, in any case and with
+     * or without the hyphen.
+     *
+     * A code names a session, and the Core will not go looking for which one, so
+     * the session id has to travel with it. Either pass it as `sessionId`, or
+     * pass a single `<sessionId>:<XXXX-XXXX>` string here and this reads both out
+     * of it. Which of the two an operator is given is #280's to settle across
+     * `actana pair new` (#283) and `actana core pair` (#285); both forms parse
+     * here so that neither is a change to this module.
+     */
+    code: string;
+    /** The pairing session the code belongs to, when `code` does not carry it. */
+    sessionId?: string;
+    /**
+     * The CA fingerprint the operator read out, in any of the forms a human
+     * copies it in: colon-separated or not, upper or lower case.
+     *
+     * **Absent is not "skip the check".** With no fingerprint this function
+     * refuses with `fingerprint-unconfirmed` and reports the presented one in the
+     * error, having sent no code — see {@link fetchCorePairingIdentity}.
+     */
+    expectedCaFingerprint?: string | null;
+    /** What this machine calls itself, for the operator's `actana pair ls`. */
+    label?: string;
+    /** This machine's platform, e.g. `process.platform`. */
+    platform?: string;
+    /** Defaults to {@link DEFAULT_PAIRING_TIMEOUT_MS}, per connection. */
+    timeoutMs?: number;
+};
+/**
+ * Pair with a Core and return the credential it issued.
+ *
+ * The result is a {@link CoreRegistrationBlob} and nothing downstream can tell
+ * it from a hand-carried one: `coreConnectionFromBlob` unpacks it,
+ * `httpsBaseUrlFor` derives the HTTPS origin, the PEMs go into the mTLS
+ * handshake and the bearer into the `auth` frame — exactly as they do today.
+ * `clientKey` is the key generated on this machine a few lines above; it was
+ * never sent, and the Core has never seen it.
+ *
+ * Throws {@link CorePairingError} for everything that is not a blob.
+ */
+export declare function pairWithCore(opts: PairWithCoreOptions): Promise<CoreRegistrationBlob>;
+/** A pairing code, and the session it names. */
+export type PairingTicket = {
+    sessionId: string;
+    code: string;
+};
+/**
+ * Read a ticket out of what a human typed.
+ *
+ * The code is checked for *shape* — eight alphanumerics, hyphens and spaces
+ * ignored — and not against the Core's alphabet. That is a deliberate stop:
+ * the alphabet is an internal of `packages/shared` (which this package may not
+ * import) and mirroring it here would be a copy free to drift, which ADR 0025
+ * D3 is about. What the shape check buys is worth having on its own: a code
+ * that could not be right whatever the alphabet is never spends one of the
+ * five attempts the operator's session has.
+ */
+export declare function parsePairingTicket(input: string, sessionId?: string): PairingTicket;
+/** A Core's address, in the two forms this module needs it. */
+type CoreAddress = {
+    host: string;
+    port: number;
+    httpsOrigin: string;
+};
+/**
+ * Read `host:port`, `https://host:port` or `wss://host:port`.
+ *
+ * `ws://` and `http://` are refused rather than upgraded: there is no
+ * certificate on a plaintext dial, so there is no fingerprint to check, and
+ * pairing over one would be the silent unverified exchange this module exists
+ * to make impossible. A caller that meant the secure port should say so.
+ */
+export declare function parseCoreAddress(address: string): CoreAddress;
+/**
+ * A fingerprint as this module compares them: colon-separated uppercase hex,
+ * which is the form `actana pair new` prints and a human copies.
+ */
+export declare function parseFingerprint(input: string): string;
+/** SHA-256 over a certificate's DER, in the form {@link parseFingerprint} yields. */
+export declare function fingerprintOf(der: Uint8Array): string;
+//# sourceMappingURL=core-pairing.d.ts.map

package/dist/core-pairing.d.ts.map

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