effect 4.0.7 → 4.1.0

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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"}