@actana/sdk 0.3.2 → 0.4.1

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":"AAsDA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAOxE,OAAO,EACL,wBAAwB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,GAC5B,MAAM,wBAAwB,CAAC;AAWhC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,kBAAkB;AAC5B,4EAA4E;AAC1E,aAAa;AACf,sEAAsE;GACpE,UAAU;AACZ,8DAA8D;GAC5D,iBAAiB;AACnB,+DAA+D;GAC7D,aAAa;AACf,oEAAoE;GAClE,iBAAiB;AACnB,wEAAwE;GACtE,yBAAyB;AAC3B,uEAAuE;GACrE,sBAAsB;AACxB;;;;;;;;GAQG;GACD,mBAAmB;AACrB,gFAAgF;GAC9E,qBAAqB;AACvB,wEAAwE;GACtE,SAAS;AACX,qEAAqE;GACnE,cAAc;AAChB,yEAAyE;GACvE,UAAU;AACZ,iDAAiD;GAC/C,cAAc;AAChB,qDAAqD;GACnD,YAAY;AACd,gDAAgD;GAC9C,oBAAoB,CAAC;AAEzB,wEAAwE;AACxE,MAAM,MAAM,sBAAsB,GAAG;IACnC,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mDAAmD;IACnD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,uEAAuE;IACvE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAkB,IAAI,sBAAsB;IAC5C,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;gBAOtC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,sBAA2B,EACnC,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAMpC;AAID,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAAG;IAChC,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAW/B;AAID,MAAM,MAAM,mBAAmB,GAAG;IAChC,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;OAUG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAiF3F;AAID,gDAAgD;AAChD,MAAM,MAAM,aAAa,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,CAoCnF;AAED,+DAA+D;AAC/D,KAAK,WAAW,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAwB7D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAStD;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAErD"}