effect 4.0.7 → 4.1.0

package/dist/crypto/KeyAgreement.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Key agreement: X25519, and ECDH on P-256, P-384 and P-521.
+ *
+ * The {@link KeyAgreement} service generates key pairs, derives a shared
+ * secret from a private key and a peer's public key, and computes a private
+ * key's public key. The top-level {@link privateKey}, {@link publicKey},
+ * {@link privateKeyFromCryptoKey}, {@link publicKeyFromCryptoKey}, and
+ * {@link toBytes} functions build and export keys without a service.
+ *
+ * Keys carry their algorithm in their type, so deriving a secret from keys on
+ * different curves is a type error. The shared secret is plain bytes: pass it
+ * through `Kdf` before using it as a key.
+ *
+ * Keys are opaque. They hold either bytes or a `CryptoKey`, display only their
+ * algorithm, and compare by reference. The bytes are:
+ *
+ * - X25519: the 32-byte private key and the 32-byte public key;
+ * - ECDH: PKCS#8 for private keys, and the uncompressed SEC1 point for public
+ *   keys.
+ *
+ * Only X25519 private keys and X25519 and ECDH public keys have a raw
+ * constructor. ECDH private keys come from
+ * `KeyAgreement.generateKeyPair`, `CryptoKey`s, or key formats.
+ *
+ * **Gotchas**
+ *
+ * - X25519 needs Chrome 133, Firefox 130, or Safari 17. There is no fallback
+ *   for older browsers.
+ * - X25519 private keys are generated from `SecureRandom` bytes, so a seeded
+ *   `SecureRandom` reproduces them. ECDH key generation uses WebCrypto's own
+ *   randomness and cannot be seeded.
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+import * as Context from "../Context.ts";
+import * as Effect from "../Effect.ts";
+import type { Inspectable } from "../Inspectable.ts";
+import * as Layer from "../Layer.ts";
+import * as CryptoError from "./CryptoError.ts";
+import * as SecureRandom from "./SecureRandom.ts";
+declare const PrivateKeyTypeId: "~effect/crypto/KeyAgreement/PrivateKey";
+declare const PublicKeyTypeId: "~effect/crypto/KeyAgreement/PublicKey";
+/**
+ * An elliptic curve for ECDH.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type Curve = "P-256" | "P-384" | "P-521";
+/**
+ * X25519 (RFC 7748), with 32-byte shared secrets.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface X25519 {
+    readonly _tag: "X25519";
+    readonly name: "x25519";
+}
+/**
+ * ECDH on a NIST curve, with shared secrets of the curve's coordinate size.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Ecdh<C extends Curve = Curve> {
+    readonly _tag: "Ecdh";
+    readonly name: {
+        readonly "P-256": "ecdhP256";
+        readonly "P-384": "ecdhP384";
+        readonly "P-521": "ecdhP521";
+    }[C];
+    readonly namedCurve: C;
+}
+/**
+ * A key agreement algorithm, such as {@link x25519} or {@link ecdhP256}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type Algorithm = X25519 | Ecdh;
+/**
+ * X25519 (RFC 7748).
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export declare const x25519: X25519;
+/**
+ * ECDH on P-256, with 32-byte shared secrets.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export declare const ecdhP256: Ecdh<"P-256">;
+/**
+ * ECDH on P-384, with 48-byte shared secrets.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export declare const ecdhP384: Ecdh<"P-384">;
+/**
+ * ECDH on P-521, with 66-byte shared secrets.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export declare const ecdhP521: Ecdh<"P-521">;
+/**
+ * An opaque key agreement private key for the algorithm `A`.
+ *
+ * **Details**
+ *
+ * The key holds either bytes or a `CryptoKey` from
+ * {@link privateKeyFromCryptoKey}. `toString`, `toJSON`, and `inspect` show
+ * only the algorithm. Keys compare by reference and do not implement `Equal`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface PrivateKey<out A extends Algorithm = Algorithm> extends Inspectable {
+    readonly [PrivateKeyTypeId]: typeof PrivateKeyTypeId;
+    readonly algorithm: A;
+}
+/**
+ * An opaque key agreement public key for the algorithm `A`.
+ *
+ * **Details**
+ *
+ * The key holds either bytes or a `CryptoKey` from
+ * {@link publicKeyFromCryptoKey}. Keys compare by reference and do not
+ * implement `Equal`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface PublicKey<out A extends Algorithm = Algorithm> extends Inspectable {
+    readonly [PublicKeyTypeId]: typeof PublicKeyTypeId;
+    readonly algorithm: A;
+}
+/**
+ * A private key and its public key.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface KeyPair<out A extends Algorithm = Algorithm> {
+    readonly privateKey: PrivateKey<A>;
+    readonly publicKey: PublicKey<A>;
+}
+/**
+ * Checks whether a value is a {@link PrivateKey}.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isPrivateKey: (u: unknown) => u is PrivateKey;
+/**
+ * Checks whether a value is a {@link PublicKey}.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.0.0
+ */
+export declare const isPublicKey: (u: unknown) => u is PublicKey;
+declare const KeyAgreement_base: Context.ServiceClass<KeyAgreement, "effect/crypto/KeyAgreement", {
+    /**
+     * Generates a key pair. X25519 private keys are 32 bytes from
+     * `SecureRandom`. ECDH keys are generated by WebCrypto and exported to
+     * PKCS#8 and an uncompressed point.
+     */
+    readonly generateKeyPair: <A extends Algorithm>(algorithm: A) => Effect.Effect<KeyPair<A>, CryptoError.CryptoError>;
+    /**
+     * Computes the secret shared by a private key and a peer's public key on
+     * the same curve. A peer key that is not on the curve, or a low-order
+     * X25519 key that gives an all-zero secret, fails with an `InvalidKey`
+     * reason.
+     */
+    readonly deriveSharedSecret: <A extends Algorithm>(privateKey: PrivateKey<A>, publicKey: PublicKey<A>) => Effect.Effect<Uint8Array, CryptoError.CryptoError>;
+    /**
+     * Computes the public key of a private key. A non-extractable `CryptoKey`
+     * fails with a `NotExtractable` reason, since its public members cannot be
+     * read.
+     */
+    readonly publicKeyOf: <A extends Algorithm>(privateKey: PrivateKey<A>) => Effect.Effect<PublicKey<A>, CryptoError.CryptoError>;
+}>;
+/**
+ * Service that generates key pairs, derives shared secrets, and computes
+ * public keys.
+ *
+ * **Example** (Agreeing on a secret with X25519)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Layer } from "effect"
+ * import { KeyAgreement, SecureRandom } from "effect/crypto"
+ *
+ * const program = Effect.gen(function*() {
+ *   const keyAgreement = yield* KeyAgreement.KeyAgreement
+ *   const alice = yield* keyAgreement.generateKeyPair(KeyAgreement.x25519)
+ *   const bob = yield* keyAgreement.generateKeyPair(KeyAgreement.x25519)
+ *   const aliceSecret = yield* keyAgreement.deriveSharedSecret(alice.privateKey, bob.publicKey)
+ *   const bobSecret = yield* keyAgreement.deriveSharedSecret(bob.privateKey, alice.publicKey)
+ *   return aliceSecret.every((byte, i) => byte === bobSecret[i])
+ * })
+ *
+ * const layer = KeyAgreement.layerWebCrypto.pipe(Layer.provide(SecureRandom.layerWebCrypto))
+ * await Effect.runPromise(program.pipe(Effect.provide(layer))) // => true
+ * ```
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export declare class KeyAgreement extends KeyAgreement_base {
+}
+/**
+ * Layer that provides `KeyAgreement` on the `WebCrypto` reference.
+ *
+ * **Details**
+ *
+ * Every algorithm runs on `crypto.subtle`. The layer imports a byte-backed
+ * key on first use and caches the `CryptoKey`. X25519 private keys come from
+ * `SecureRandom`, so a seeded `SecureRandom` reproduces them.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export declare const layerWebCrypto: Layer.Layer<KeyAgreement, never, SecureRandom.SecureRandom>;
+/**
+ * Builds an X25519 private key from its 32 bytes.
+ *
+ * **Details**
+ *
+ * The bytes are copied. Another length fails with an `InvalidKey` reason,
+ * including the 64-byte `private key‖public key` form libsodium uses: pass
+ * its first 32 bytes. ECDH private keys have no raw form, so passing them is
+ * a type error.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const privateKey: <A extends X25519>(algorithm: A, bytes: Uint8Array) => Effect.Effect<PrivateKey<A>, CryptoError.CryptoError>;
+/**
+ * Builds a public key from its raw form: 32 bytes for X25519, or an
+ * uncompressed SEC1 point for ECDH.
+ *
+ * **Details**
+ *
+ * The bytes are copied. A wrong length, or a compressed point, fails with an
+ * `InvalidKey` reason. Only uncompressed points are taken because Safari and
+ * Firefox before 146 reject compressed ones in raw import, though they accept
+ * them inside SPKI: decode a compressed point with `KeyFormat.spki`. Whether a
+ * point is on the curve is checked when the key is first used.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const publicKey: <A extends Algorithm>(algorithm: A, bytes: Uint8Array) => Effect.Effect<PublicKey<A>, CryptoError.CryptoError>;
+/**
+ * Builds a private key from an existing `CryptoKey`, such as a
+ * non-extractable one.
+ *
+ * **Details**
+ *
+ * The `CryptoKey` must be a private key of the algorithm's WebCrypto name and
+ * curve, with the `deriveBits` usage. Otherwise the constructor fails with an
+ * `InvalidKey` reason. The key must come from the `Crypto` object of the
+ * `WebCrypto` reference.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const privateKeyFromCryptoKey: <A extends Algorithm>(algorithm: A, cryptoKey: CryptoKey) => Effect.Effect<PrivateKey<A>, CryptoError.CryptoError>;
+/**
+ * Builds a public key from an existing `CryptoKey`.
+ *
+ * **Details**
+ *
+ * The `CryptoKey` must be a public key of the algorithm's WebCrypto name and
+ * curve. Public keys need no usages. Otherwise the constructor fails with an
+ * `InvalidKey` reason. The key must come from the `Crypto` object of the
+ * `WebCrypto` reference.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const publicKeyFromCryptoKey: <A extends Algorithm>(algorithm: A, cryptoKey: CryptoKey) => Effect.Effect<PublicKey<A>, CryptoError.CryptoError>;
+/**
+ * Exports a key's stored bytes.
+ *
+ * **Details**
+ *
+ * Returns a fresh `Uint8Array`: the raw key for X25519, and PKCS#8 or the
+ * uncompressed point for ECDH. A `CryptoKey`-backed key is exported on the
+ * `WebCrypto` reference, and fails with a `NotExtractable` reason when the
+ * `CryptoKey` is not extractable.
+ *
+ * @stability unstable
+ * @category converting
+ * @since 4.0.0
+ */
+export declare const toBytes: (key: PrivateKey | PublicKey) => Effect.Effect<Uint8Array, CryptoError.CryptoError>;
+export {};
+//# sourceMappingURL=KeyAgreement.d.ts.map

package/dist/crypto/KeyAgreement.d.ts.map

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

package/dist/crypto/KeyAgreement.js

@@ -0,0 +1,303 @@
+/**
+ * Key agreement: X25519, and ECDH on P-256, P-384 and P-521.
+ *
+ * The {@link KeyAgreement} service generates key pairs, derives a shared
+ * secret from a private key and a peer's public key, and computes a private
+ * key's public key. The top-level {@link privateKey}, {@link publicKey},
+ * {@link privateKeyFromCryptoKey}, {@link publicKeyFromCryptoKey}, and
+ * {@link toBytes} functions build and export keys without a service.
+ *
+ * Keys carry their algorithm in their type, so deriving a secret from keys on
+ * different curves is a type error. The shared secret is plain bytes: pass it
+ * through `Kdf` before using it as a key.
+ *
+ * Keys are opaque. They hold either bytes or a `CryptoKey`, display only their
+ * algorithm, and compare by reference. The bytes are:
+ *
+ * - X25519: the 32-byte private key and the 32-byte public key;
+ * - ECDH: PKCS#8 for private keys, and the uncompressed SEC1 point for public
+ *   keys.
+ *
+ * Only X25519 private keys and X25519 and ECDH public keys have a raw
+ * constructor. ECDH private keys come from
+ * `KeyAgreement.generateKeyPair`, `CryptoKey`s, or key formats.
+ *
+ * **Gotchas**
+ *
+ * - X25519 needs Chrome 133, Firefox 130, or Safari 17. There is no fallback
+ *   for older browsers.
+ * - X25519 private keys are generated from `SecureRandom` bytes, so a seeded
+ *   `SecureRandom` reproduces them. ECDH key generation uses WebCrypto's own
+ *   randomness and cannot be seeded.
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+import * as Context from "../Context.js";
+import * as Effect from "../Effect.js";
+import * as Layer from "../Layer.js";
+import * as Predicate from "../Predicate.js";
+import * as CryptoError from "./CryptoError.js";
+import * as Asymmetric from "./internal/asymmetric.js";
+import * as KeyModel from "./internal/key.js";
+import * as internal from "./internal/webCrypto.js";
+import * as SecureRandom from "./SecureRandom.js";
+import { WebCrypto } from "./WebCrypto.js";
+const PrivateKeyTypeId = "~effect/crypto/KeyAgreement/PrivateKey";
+const PublicKeyTypeId = "~effect/crypto/KeyAgreement/PublicKey";
+/**
+ * X25519 (RFC 7748).
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const x25519 = {
+  _tag: "X25519",
+  name: "x25519"
+};
+/**
+ * ECDH on P-256, with 32-byte shared secrets.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const ecdhP256 = {
+  _tag: "Ecdh",
+  name: "ecdhP256",
+  namedCurve: "P-256"
+};
+/**
+ * ECDH on P-384, with 48-byte shared secrets.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const ecdhP384 = {
+  _tag: "Ecdh",
+  name: "ecdhP384",
+  namedCurve: "P-384"
+};
+/**
+ * ECDH on P-521, with 66-byte shared secrets.
+ *
+ * @stability unstable
+ * @category algorithms
+ * @since 4.0.0
+ */
+export const ecdhP521 = {
+  _tag: "Ecdh",
+  name: "ecdhP521",
+  namedCurve: "P-521"
+};
+const PrivateKeyProto = /*#__PURE__*/KeyModel.redactedProto(PrivateKeyTypeId, "KeyAgreement.PrivateKey");
+const PublicKeyProto = /*#__PURE__*/KeyModel.redactedProto(PublicKeyTypeId, "KeyAgreement.PublicKey");
+/**
+ * Checks whether a value is a {@link PrivateKey}.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.0.0
+ */
+export const isPrivateKey = u => Predicate.hasProperty(u, PrivateKeyTypeId);
+/**
+ * Checks whether a value is a {@link PublicKey}.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.0.0
+ */
+export const isPublicKey = u => Predicate.hasProperty(u, PublicKeyTypeId);
+const specOf = algorithm => algorithm._tag === "X25519" ? {
+  name: "X25519",
+  importParams: {
+    name: "X25519"
+  },
+  privateUsages: ["deriveBits"],
+  publicUsages: [],
+  seedPrefix: Asymmetric.x25519Prefix,
+  publicFormat: "raw"
+} : {
+  name: "ECDH",
+  importParams: {
+    name: "ECDH",
+    namedCurve: algorithm.namedCurve
+  },
+  privateUsages: ["deriveBits"],
+  publicUsages: [],
+  seedPrefix: undefined,
+  publicFormat: "raw",
+  check: Asymmetric.checkNamedCurve(algorithm.namedCurve)
+};
+/** @internal */
+export const family = {
+  module: "KeyAgreement",
+  specOf,
+  privateKeyProto: PrivateKeyProto,
+  publicKeyProto: PublicKeyProto,
+  isPrivateKey
+};
+// P-521 coordinates are 521 bits, padded to 66 bytes.
+const sharedSecretBits = algorithm => algorithm._tag === "X25519" ? 256 : 8 * Asymmetric.coordinateSizes[algorithm.namedCurve];
+const invalidPeer = (description, cause) => new CryptoError.CryptoError({
+  module: "KeyAgreement",
+  method: "deriveSharedSecret",
+  reason: new CryptoError.InvalidKey(cause === undefined ? {
+    description
+  } : {
+    description,
+    cause
+  })
+});
+/**
+ * Service that generates key pairs, derives shared secrets, and computes
+ * public keys.
+ *
+ * **Example** (Agreeing on a secret with X25519)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Layer } from "effect"
+ * import { KeyAgreement, SecureRandom } from "effect/crypto"
+ *
+ * const program = Effect.gen(function*() {
+ *   const keyAgreement = yield* KeyAgreement.KeyAgreement
+ *   const alice = yield* keyAgreement.generateKeyPair(KeyAgreement.x25519)
+ *   const bob = yield* keyAgreement.generateKeyPair(KeyAgreement.x25519)
+ *   const aliceSecret = yield* keyAgreement.deriveSharedSecret(alice.privateKey, bob.publicKey)
+ *   const bobSecret = yield* keyAgreement.deriveSharedSecret(bob.privateKey, alice.publicKey)
+ *   return aliceSecret.every((byte, i) => byte === bobSecret[i])
+ * })
+ *
+ * const layer = KeyAgreement.layerWebCrypto.pipe(Layer.provide(SecureRandom.layerWebCrypto))
+ * await Effect.runPromise(program.pipe(Effect.provide(layer))) // => true
+ * ```
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export class KeyAgreement extends /*#__PURE__*/Context.Service()("effect/crypto/KeyAgreement") {}
+/**
+ * Layer that provides `KeyAgreement` on the `WebCrypto` reference.
+ *
+ * **Details**
+ *
+ * Every algorithm runs on `crypto.subtle`. The layer imports a byte-backed
+ * key on first use and caches the `CryptoKey`. X25519 private keys come from
+ * `SecureRandom`, so a seeded `SecureRandom` reproduces them.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerWebCrypto = /*#__PURE__*/Layer.effect(KeyAgreement, /*#__PURE__*/Effect.gen(function* () {
+  const random = yield* SecureRandom.SecureRandom;
+  const crypto = yield* WebCrypto;
+  const caches = Asymmetric.makeCaches(family);
+  return KeyAgreement.of({
+    generateKeyPair: algorithm => Asymmetric.generateKeyPair(family, crypto, random, algorithm, specOf(algorithm).importParams),
+    deriveSharedSecret: (privateKey, publicKey) => Effect.suspend(() => {
+      const algorithm = privateKey.algorithm;
+      // The types keep curves apart, but keys typed with the default
+      // `Algorithm` can still differ at run time.
+      if (algorithm.name !== publicKey.algorithm.name) {
+        return Effect.fail(invalidPeer(`Expected a ${algorithm.name} public key, not ${publicKey.algorithm.name}`));
+      }
+      const onError = cause => Asymmetric.publicKeyError("KeyAgreement", "deriveSharedSecret", publicKey, cause);
+      // The keys are imported before deriving, so an `OperationError` from
+      // `deriveBits` can only come from the peer key.
+      return internal.run("KeyAgreement", "deriveSharedSecret", algorithm.name, crypto, async subtle => ({
+        privateKey: await caches.privateKey(subtle, privateKey),
+        publicKey: await caches.publicKey(subtle, publicKey)
+      }), onError).pipe(Effect.flatMap(keys => internal.run("KeyAgreement", "deriveSharedSecret", algorithm.name, crypto, async subtle => new Uint8Array(await subtle.deriveBits({
+        name: specOf(algorithm).name,
+        public: keys.publicKey
+      }, keys.privateKey, sharedSecretBits(algorithm))), cause => internal.isOperationError(cause) ? invalidPeer("Invalid peer public key", cause) : onError(cause))), Effect.flatMap(secret =>
+      // RFC 7748, section 6.1: an all-zero X25519 output means the peer
+      // sent a low-order point, and protocols such as SSH must abort.
+      algorithm._tag === "X25519" && secret.every(byte => byte === 0) ? Effect.fail(invalidPeer("X25519 shared secret must not be all zeros")) : Effect.succeed(secret)));
+    }),
+    publicKeyOf: privateKey => Asymmetric.publicKeyOf(family, crypto, privateKey)
+  });
+}));
+/**
+ * Builds an X25519 private key from its 32 bytes.
+ *
+ * **Details**
+ *
+ * The bytes are copied. Another length fails with an `InvalidKey` reason,
+ * including the 64-byte `private key‖public key` form libsodium uses: pass
+ * its first 32 bytes. ECDH private keys have no raw form, so passing them is
+ * a type error.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const privateKey = (algorithm, bytes) => KeyModel.fromBytes("KeyAgreement", "privateKey", PrivateKeyProto, algorithm, bytes, Asymmetric.checkSeedLength("X25519", "private"));
+/**
+ * Builds a public key from its raw form: 32 bytes for X25519, or an
+ * uncompressed SEC1 point for ECDH.
+ *
+ * **Details**
+ *
+ * The bytes are copied. A wrong length, or a compressed point, fails with an
+ * `InvalidKey` reason. Only uncompressed points are taken because Safari and
+ * Firefox before 146 reject compressed ones in raw import, though they accept
+ * them inside SPKI: decode a compressed point with `KeyFormat.spki`. Whether a
+ * point is on the curve is checked when the key is first used.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const publicKey = (algorithm, bytes) => KeyModel.fromBytes("KeyAgreement", "publicKey", PublicKeyProto, algorithm, bytes, algorithm._tag === "Ecdh" ? Asymmetric.checkPoint(algorithm.namedCurve) : Asymmetric.checkSeedLength("X25519", "public"));
+/**
+ * Builds a private key from an existing `CryptoKey`, such as a
+ * non-extractable one.
+ *
+ * **Details**
+ *
+ * The `CryptoKey` must be a private key of the algorithm's WebCrypto name and
+ * curve, with the `deriveBits` usage. Otherwise the constructor fails with an
+ * `InvalidKey` reason. The key must come from the `Crypto` object of the
+ * `WebCrypto` reference.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const privateKeyFromCryptoKey = (algorithm, cryptoKey) => Asymmetric.fromCryptoKey(family, "privateKeyFromCryptoKey", algorithm, "private", cryptoKey);
+/**
+ * Builds a public key from an existing `CryptoKey`.
+ *
+ * **Details**
+ *
+ * The `CryptoKey` must be a public key of the algorithm's WebCrypto name and
+ * curve. Public keys need no usages. Otherwise the constructor fails with an
+ * `InvalidKey` reason. The key must come from the `Crypto` object of the
+ * `WebCrypto` reference.
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const publicKeyFromCryptoKey = (algorithm, cryptoKey) => Asymmetric.fromCryptoKey(family, "publicKeyFromCryptoKey", algorithm, "public", cryptoKey);
+/**
+ * Exports a key's stored bytes.
+ *
+ * **Details**
+ *
+ * Returns a fresh `Uint8Array`: the raw key for X25519, and PKCS#8 or the
+ * uncompressed point for ECDH. A `CryptoKey`-backed key is exported on the
+ * `WebCrypto` reference, and fails with a `NotExtractable` reason when the
+ * `CryptoKey` is not extractable.
+ *
+ * @stability unstable
+ * @category converting
+ * @since 4.0.0
+ */
+export const toBytes = key => Asymmetric.toBytes(family, key);
+//# sourceMappingURL=KeyAgreement.js.map

package/dist/crypto/KeyAgreement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeyAgreement.js","names":[],"sources":["../../src/crypto/KeyAgreement.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}