effect 4.0.6 → 4.1.0

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":[]}

package/dist/crypto/KeyFormat.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Key formats: SPKI, PKCS#8, JWK, and PEM, with import-only PKCS#1 and SEC1.
+ *
+ * {@link decodePublic}, {@link decodePrivate}, and {@link decodeSecret} build
+ * typed keys from encoded data, and {@link encode} writes a key in a named
+ * format. They are plain functions, not a service: each returns an Effect that
+ * requires nothing and runs on the `WebCrypto` reference.
+ *
+ * The algorithm decides the family of the result. Decoding with
+ * `Signature.ecdsaP256` gives a `Signature` key, and with
+ * `KeyAgreement.ecdhP256` a `KeyAgreement` key. Raw bytes are not a format
+ * here: each family's own constructors read them.
+ *
+ * Format values carry their role, direction, and data type in the types:
+ *
+ * - {@link spki} (public) and {@link pkcs8} (private) read and write DER
+ *   bytes;
+ * - {@link jwk} reads and writes JWK objects for every role;
+ * - {@link pkcs1} (RSA) and {@link sec1} (EC) read private DER keys and
+ *   cannot be written;
+ * - {@link pem} turns any DER format into PEM text.
+ *
+ * Decoded keys always hold bytes, in the forms each family stores, so they
+ * work with every layer.
+ *
+ * **Gotchas**
+ *
+ * - EC private keys must include their public point. Safari and Firefox
+ *   before 132 cannot import one without it, so every runtime fails with an
+ *   `Unsupported` reason.
+ * - SPKI accepts compressed EC points. Safari and Firefox before 146 reject
+ *   them in raw import, so the families' raw constructors take only
+ *   uncompressed points.
+ * - Ed25519 and X25519 private JWKs need a correct `x`. Bun and Deno accept
+ *   `d` alone, and other runtimes reject it.
+ * - JWK members other than `kty`, `crv`, `alg`, and the key material are
+ *   ignored on import, and written JWKs contain only `kty`, `crv`, and the key
+ *   material.
+ * - Callers parse and serialize JSON themselves.
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+import * as Effect from "../Effect.ts";
+import type * as Aead from "./Aead.ts";
+import type * as Cipher from "./Cipher.ts";
+import * as CryptoError from "./CryptoError.ts";
+import * as KeyAgreement from "./KeyAgreement.ts";
+import * as KeyWrap from "./KeyWrap.ts";
+import type * as Mac from "./Mac.ts";
+import * as Signature from "./Signature.ts";
+/**
+ * The role of a key: public, private, or secret (symmetric).
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type Role = "public" | "private" | "secret";
+/**
+ * Whether a format can be read, written, or both.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type Direction = "decode" | "encode";
+/**
+ * A key format, such as {@link spki} or `pem(pkcs8)`.
+ *
+ * **Details**
+ *
+ * `~tags` exists only in the types. It records the roles the format holds,
+ * whether it can be read and written, and the type of its data: `Uint8Array`
+ * for DER, `string` for PEM, and `JsonWebKey` for JWK.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Format<R extends Role, D extends Direction, Data> {
+    readonly _tag: "spki" | "pkcs8" | "jwk" | "pkcs1" | "sec1";
+    readonly pem: boolean;
+    readonly "~tags"?: {
+        readonly role: (_: R) => void;
+        readonly direction: (_: D) => void;
+        readonly data: Data;
+    } | undefined;
+}
+/**
+ * SubjectPublicKeyInfo DER (RFC 5280), for public keys.
+ *
+ * @stability unstable
+ * @category formats
+ * @since 4.0.0
+ */
+export declare const spki: Format<"public", Direction, Uint8Array>;
+/**
+ * PKCS#8 PrivateKeyInfo DER (RFC 5208), for private keys.
+ *
+ * @stability unstable
+ * @category formats
+ * @since 4.0.0
+ */
+export declare const pkcs8: Format<"private", Direction, Uint8Array>;
+/**
+ * JSON Web Key (RFC 7517), for every role.
+ *
+ * **Details**
+ *
+ * `decodePublic` rejects a JWK with `d`, and `decodePrivate` requires it.
+ * `kty`, `crv`, and `alg` must match the algorithm when present. Written JWKs
+ * contain only `kty`, `crv`, and the key material.
+ *
+ * Ed25519 and X25519 private JWKs need a correct `x`: Bun and Deno accept `d`
+ * alone, but other runtimes reject it.
+ *
+ * @stability unstable
+ * @category formats
+ * @since 4.0.0
+ */
+export declare const jwk: Format<Role, Direction, JsonWebKey>;
+/**
+ * PKCS#1 RSAPrivateKey DER (RFC 8017), read only.
+ *
+ * @stability unstable
+ * @category formats
+ * @since 4.0.0
+ */
+export declare const pkcs1: Format<"private", "decode", Uint8Array>;
+/**
+ * SEC1 ECPrivateKey DER (RFC 5915), read only.
+ *
+ * **Details**
+ *
+ * The curve parameters, when present, must match the algorithm's curve. The
+ * public point must be present.
+ *
+ * @stability unstable
+ * @category formats
+ * @since 4.0.0
+ */
+export declare const sec1: Format<"private", "decode", Uint8Array>;
+/**
+ * PEM (RFC 7468) over a DER format.
+ *
+ * **Details**
+ *
+ * Reading accepts exactly one block whose label matches the format:
+ * `PUBLIC KEY`, `PRIVATE KEY`, `RSA PRIVATE KEY`, or `EC PRIVATE KEY`.
+ * Writing uses 64-column lines.
+ *
+ * @stability unstable
+ * @category formats
+ * @since 4.0.0
+ */
+export declare const pem: <R extends Role, D extends Direction>(format: Format<R, D, Uint8Array>) => Format<R, D, string>;
+/**
+ * The algorithms whose public and private keys `KeyFormat` reads and writes.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type AsymmetricAlgorithm = Signature.Algorithm | KeyAgreement.Algorithm | KeyWrap.RsaOaep;
+/**
+ * The algorithms whose secret keys `KeyFormat` reads and writes, and that
+ * `KeyWrap` wraps.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type SecretAlgorithm = Aead.Algorithm | Cipher.Algorithm | Mac.Algorithm | KeyWrap.AesKw;
+/**
+ * The public key type of an algorithm.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type PublicKey<A extends AsymmetricAlgorithm = AsymmetricAlgorithm> = A extends Signature.Algorithm ? Signature.PublicKey<A> : A extends KeyAgreement.Algorithm ? KeyAgreement.PublicKey<A> : A extends KeyWrap.RsaOaep ? KeyWrap.PublicKey<A> : never;
+/**
+ * The private key type of an algorithm.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type PrivateKey<A extends AsymmetricAlgorithm = AsymmetricAlgorithm> = A extends Signature.Algorithm ? Signature.PrivateKey<A> : A extends KeyAgreement.Algorithm ? KeyAgreement.PrivateKey<A> : A extends KeyWrap.RsaOaep ? KeyWrap.PrivateKey<A> : never;
+/**
+ * The secret key type of an algorithm.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type SecretKey<A extends SecretAlgorithm = SecretAlgorithm> = A extends Aead.Algorithm ? Aead.Key<A> : A extends Cipher.Algorithm ? Cipher.Key<A> : A extends Mac.Algorithm ? Mac.Key<A> : A extends KeyWrap.AesKw ? KeyWrap.Key<A> : never;
+/**
+ * Any key `KeyFormat` can write.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type Key = PublicKey | PrivateKey | SecretKey;
+/**
+ * The role of a key type.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type RoleOf<K extends Key> = K extends PublicKey ? "public" : K extends PrivateKey ? "private" : "secret";
+/**
+ * Decodes a public key.
+ *
+ * **Details**
+ *
+ * The format must hold public keys: {@link spki}, {@link jwk}, or
+ * `pem(spki)`. The key is imported on the `WebCrypto` reference and stored as
+ * bytes. Malformed data, a key of another algorithm or curve, or a JWK with
+ * `d` fails with an `InvalidKey` reason.
+ *
+ * **Example** (Reading a PEM public key)
+ *
+ * ```ts
+ * import { Effect } from "effect"
+ * import { KeyFormat, Signature } from "effect/crypto"
+ *
+ * declare const text: string
+ *
+ * const publicKey = KeyFormat.decodePublic(KeyFormat.pem(KeyFormat.spki), Signature.ecdsaP256, text)
+ * ```
+ *
+ * @stability unstable
+ * @category decoding
+ * @since 4.0.0
+ */
+export declare const decodePublic: <A extends AsymmetricAlgorithm, Data>(format: Format<"public", "decode", Data>, algorithm: A, data: NoInfer<Data>) => Effect.Effect<PublicKey<A>, CryptoError.CryptoError>;
+/**
+ * Decodes a private key.
+ *
+ * **Details**
+ *
+ * The format must hold private keys: {@link pkcs8}, {@link jwk},
+ * {@link pkcs1}, {@link sec1}, or their PEM forms. PKCS#1 and SEC1 are
+ * converted to PKCS#8 before the import. Malformed data, a key of another
+ * algorithm or curve, or a JWK without `d` fails with an `InvalidKey` reason.
+ * An EC private key without its public point fails with an `Unsupported`
+ * reason on every runtime, because Safari and Firefox before 132 cannot import
+ * it.
+ *
+ * @stability unstable
+ * @category decoding
+ * @since 4.0.0
+ */
+export declare const decodePrivate: <A extends AsymmetricAlgorithm, Data>(format: Format<"private", "decode", Data>, algorithm: A, data: NoInfer<Data>) => Effect.Effect<PrivateKey<A>, CryptoError.CryptoError>;
+/**
+ * Decodes a secret key from a JWK.
+ *
+ * **Details**
+ *
+ * The JWK must have `kty` `oct` when `kty` is present, and an `alg` matching
+ * the algorithm when `alg` is present. The key bytes go through the family's
+ * raw constructor, so a wrong length fails with an `InvalidKey` reason.
+ * Secret keys never touch `crypto.subtle` here.
+ *
+ * @stability unstable
+ * @category decoding
+ * @since 4.0.0
+ */
+export declare const decodeSecret: <A extends SecretAlgorithm, Data>(format: Format<"secret", "decode", Data>, algorithm: A, data: NoInfer<Data>) => Effect.Effect<SecretKey<A>, CryptoError.CryptoError>;
+/**
+ * Encodes a key in a format.
+ *
+ * **Details**
+ *
+ * The format must hold the key's role and be writable: {@link spki} for
+ * public keys, {@link pkcs8} for private keys, {@link jwk} for every role,
+ * and the PEM forms of SPKI and PKCS#8. PKCS#1 and SEC1 cannot be written.
+ *
+ * PEM output uses 64-column lines. JWK output contains only `kty`, `crv`, and
+ * the key material. A non-extractable `CryptoKey`-backed key fails with a
+ * `NotExtractable` reason.
+ *
+ * **Example** (Writing a public key as JWK)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Layer } from "effect"
+ * import { KeyFormat, SecureRandom, Signature } from "effect/crypto"
+ *
+ * const program = Effect.gen(function*() {
+ *   const signature = yield* Signature.Signature
+ *   const { publicKey } = yield* signature.generateKeyPair(Signature.ed25519)
+ *   const jwk = yield* KeyFormat.encode(KeyFormat.jwk, publicKey)
+ *   return [jwk.kty, jwk.crv]
+ * })
+ *
+ * const layer = Signature.layerWebCrypto.pipe(Layer.provide(SecureRandom.layerWebCrypto))
+ * await Effect.runPromise(program.pipe(Effect.provide(layer))) // => ["OKP", "Ed25519"]
+ * ```
+ *
+ * @stability unstable
+ * @category encoding
+ * @since 4.0.0
+ */
+export declare const encode: <K extends Key, Data>(format: Format<RoleOf<K>, "encode", Data>, key: K) => Effect.Effect<Data, CryptoError.CryptoError>;
+//# sourceMappingURL=KeyFormat.d.ts.map

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

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