@oari/jose 0.0.0

package/dist/types/key/generate_key_pair.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Asymmetric key generation
+ *
+ * @module
+ */
+import type * as types from '../types.d.ts';
+/** Asymmetric key pair generation function result. */
+export interface GenerateKeyPairResult {
+    /** The generated Private Key. */
+    privateKey: types.CryptoKey;
+    /** Public Key corresponding to the generated Private Key. */
+    publicKey: types.CryptoKey;
+}
+/** Asymmetric key pair generation function options. */
+export interface GenerateKeyPairOptions {
+    /**
+     * The EC "crv" (Curve) or OKP "crv" (Subtype of Key Pair) value to generate. The curve must be
+     * both supported on the runtime as well as applicable for the given JWA algorithm identifier.
+     */
+    crv?: string;
+    /**
+     * A hint for RSA algorithms to generate an RSA key of a given `modulusLength` (Key size in bits).
+     * JOSE requires 2048 bits or larger. Default is 2048.
+     */
+    modulusLength?: number;
+    /**
+     * The value to use as {@link !SubtleCrypto.generateKey} `extractable` argument. Default is false.
+     *
+     * @example
+     *
+     * ```js
+     * const { publicKey, privateKey } = await jose.generateKeyPair('PS256', {
+     *   extractable: true,
+     * })
+     * console.log(await jose.exportJWK(privateKey))
+     * console.log(await jose.exportPKCS8(privateKey))
+     * ```
+     */
+    extractable?: boolean;
+}
+/**
+ * Generates a private and a public key for a given JWA algorithm identifier. This can only generate
+ * asymmetric key pairs. For symmetric secrets use the `generateSecret` function.
+ *
+ * > [!NOTE]\
+ * > The `privateKey` is generated with `extractable` set to `false` by default. See
+ * > {@link GenerateKeyPairOptions.extractable} to generate an extractable `privateKey`.
+ *
+ * This function is exported (as a named export) from the main `'jose'` module entry point as well
+ * as from its subpath export `'jose/generate/keypair'`.
+ *
+ * @example
+ *
+ * ```js
+ * const { publicKey, privateKey } = await jose.generateKeyPair('PS256')
+ * console.log(publicKey)
+ * console.log(privateKey)
+ * ```
+ *
+ * @param alg JWA Algorithm Identifier to be used with the generated key pair. See
+ *   {@link https://github.com/panva/jose/issues/210 Algorithm Key Requirements}.
+ * @param options Additional options passed down to the key pair generation.
+ */
+export declare function generateKeyPair(alg: string, options?: GenerateKeyPairOptions): Promise<GenerateKeyPairResult>;

package/dist/types/key/generate_secret.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Symmetric key generation
+ *
+ * @module
+ */
+import type * as types from '../types.d.ts';
+/** Secret generation function options. */
+export interface GenerateSecretOptions {
+    /**
+     * The value to use as {@link !SubtleCrypto.generateKey} `extractable` argument. Default is false.
+     *
+     * > [!NOTE]\
+     * > Because A128CBC-HS256, A192CBC-HS384, and A256CBC-HS512 secrets cannot be represented as
+     * > {@link !CryptoKey} this option has no effect for them.
+     */
+    extractable?: boolean;
+}
+/**
+ * Generates a symmetric secret key for a given JWA algorithm identifier.
+ *
+ * > [!NOTE]\
+ * > The secret key is generated with `extractable` set to `false` by default.
+ *
+ * > [!NOTE]\
+ * > Because A128CBC-HS256, A192CBC-HS384, and A256CBC-HS512 secrets cannot be represented as
+ * > {@link !CryptoKey} this method yields a {@link !Uint8Array} for them instead.
+ *
+ * This function is exported (as a named export) from the main `'jose'` module entry point as well
+ * as from its subpath export `'jose/generate/secret'`.
+ *
+ * @example
+ *
+ * ```js
+ * const secret = await jose.generateSecret('HS256')
+ * console.log(secret)
+ * ```
+ *
+ * @param alg JWA Algorithm Identifier to be used with the generated secret. See
+ *   {@link https://github.com/panva/jose/issues/210 Algorithm Key Requirements}.
+ * @param options Additional options passed down to the secret generation.
+ */
+export declare function generateSecret(alg: string, options?: GenerateSecretOptions): Promise<types.CryptoKey | Uint8Array>;

package/dist/types/key/import.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Cryptographic key import functions
+ *
+ * @module
+ */
+import type * as types from '../types.d.ts';
+/** Key Import Function options. */
+export interface KeyImportOptions {
+    /**
+     * The value to use as {@link !SubtleCrypto.importKey} `extractable` argument. Default is false for
+     * private keys, true otherwise.
+     */
+    extractable?: boolean;
+}
+/**
+ * Imports a PEM-encoded SPKI string as a {@link !CryptoKey}.
+ *
+ * > [!NOTE]\
+ * > The OID id-RSASSA-PSS (1.2.840.113549.1.1.10) is not supported in
+ * > {@link https://w3c.github.io/webcrypto/ Web Cryptography API}, use the OID rsaEncryption
+ * > (1.2.840.113549.1.1.1) instead for all RSA algorithms.
+ *
+ * This function is exported (as a named export) from the main `'jose'` module entry point as well
+ * as from its subpath export `'jose/key/import'`.
+ *
+ * @example
+ *
+ * ```js
+ * const algorithm = 'ES256'
+ * const spki = `-----BEGIN PUBLIC KEY-----
+ * MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEFlHHWfLk0gLBbsLTcuCrbCqoHqmM
+ * YJepMC+Q+Dd6RBmBiA41evUsNMwLeN+PNFqib+xwi9JkJ8qhZkq8Y/IzGg==
+ * -----END PUBLIC KEY-----`
+ * const ecPublicKey = await jose.importSPKI(spki, algorithm)
+ * ```
+ *
+ * @param spki PEM-encoded SPKI string
+ * @param alg JSON Web Algorithm identifier to be used with the imported key. See
+ *   {@link https://github.com/panva/jose/issues/210 Algorithm Key Requirements}.
+ */
+export declare function importSPKI(spki: string, alg: string, options?: KeyImportOptions): Promise<types.CryptoKey>;
+/**
+ * Imports the SPKI from an X.509 string certificate as a {@link !CryptoKey}.
+ *
+ * > [!NOTE]\
+ * > The OID id-RSASSA-PSS (1.2.840.113549.1.1.10) is not supported in
+ * > {@link https://w3c.github.io/webcrypto/ Web Cryptography API}, use the OID rsaEncryption
+ * > (1.2.840.113549.1.1.1) instead for all RSA algorithms.
+ *
+ * This function is exported (as a named export) from the main `'jose'` module entry point as well
+ * as from its subpath export `'jose/key/import'`.
+ *
+ * @example
+ *
+ * ```js
+ * const algorithm = 'ES256'
+ * const x509 = `-----BEGIN CERTIFICATE-----
+ * MIIBXjCCAQSgAwIBAgIGAXvykuMKMAoGCCqGSM49BAMCMDYxNDAyBgNVBAMMK3Np
+ * QXBNOXpBdk1VaXhXVWVGaGtjZXg1NjJRRzFyQUhXaV96UlFQTVpQaG8wHhcNMjEw
+ * OTE3MDcwNTE3WhcNMjIwNzE0MDcwNTE3WjA2MTQwMgYDVQQDDCtzaUFwTTl6QXZN
+ * VWl4V1VlRmhrY2V4NTYyUUcxckFIV2lfelJRUE1aUGhvMFkwEwYHKoZIzj0CAQYI
+ * KoZIzj0DAQcDQgAE8PbPvCv5D5xBFHEZlBp/q5OEUymq7RIgWIi7tkl9aGSpYE35
+ * UH+kBKDnphJO3odpPZ5gvgKs2nwRWcrDnUjYLDAKBggqhkjOPQQDAgNIADBFAiEA
+ * 1yyMTRe66MhEXID9+uVub7woMkNYd0LhSHwKSPMUUTkCIFQGsfm1ecXOpeGOufAh
+ * v+A1QWZMuTWqYt+uh/YSRNDn
+ * -----END CERTIFICATE-----`
+ * const ecPublicKey = await jose.importX509(x509, algorithm)
+ * ```
+ *
+ * @param x509 X.509 certificate string
+ * @param alg JSON Web Algorithm identifier to be used with the imported key. See
+ *   {@link https://github.com/panva/jose/issues/210 Algorithm Key Requirements}.
+ */
+export declare function importX509(x509: string, alg: string, options?: KeyImportOptions): Promise<types.CryptoKey>;
+/**
+ * Imports a PEM-encoded PKCS#8 string as a {@link !CryptoKey}.
+ *
+ * > [!NOTE]\
+ * > The OID id-RSASSA-PSS (1.2.840.113549.1.1.10) is not supported in
+ * > {@link https://w3c.github.io/webcrypto/ Web Cryptography API}, use the OID rsaEncryption
+ * > (1.2.840.113549.1.1.1) instead for all RSA algorithms.
+ *
+ * This function is exported (as a named export) from the main `'jose'` module entry point as well
+ * as from its subpath export `'jose/key/import'`.
+ *
+ * @example
+ *
+ * ```js
+ * const algorithm = 'ES256'
+ * const pkcs8 = `-----BEGIN PRIVATE KEY-----
+ * MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgiyvo0X+VQ0yIrOaN
+ * nlrnUclopnvuuMfoc8HHly3505OhRANCAAQWUcdZ8uTSAsFuwtNy4KtsKqgeqYxg
+ * l6kwL5D4N3pEGYGIDjV69Sw0zAt43480WqJv7HCL0mQnyqFmSrxj8jMa
+ * -----END PRIVATE KEY-----`
+ * const ecPrivateKey = await jose.importPKCS8(pkcs8, algorithm)
+ * ```
+ *
+ * @param pkcs8 PEM-encoded PKCS#8 string
+ * @param alg JSON Web Algorithm identifier to be used with the imported key. See
+ *   {@link https://github.com/panva/jose/issues/210 Algorithm Key Requirements}.
+ */
+export declare function importPKCS8(pkcs8: string, alg: string, options?: KeyImportOptions): Promise<types.CryptoKey>;
+/**
+ * Imports a JWK to a {@link !CryptoKey}. Either the JWK "alg" (Algorithm) Parameter, or the optional
+ * "alg" argument, must be present for asymmetric JSON Web Key imports.
+ *
+ * > [!NOTE]\
+ * > The JSON Web Key parameters "use", "key_ops", and "ext" are also used in the {@link !CryptoKey}
+ * > import process.
+ *
+ * > [!NOTE]\
+ * > Symmetric JSON Web Keys (i.e. `kty: "oct"`) yield back an {@link !Uint8Array} instead of a
+ * > {@link !CryptoKey}.
+ *
+ * This function is exported (as a named export) from the main `'jose'` module entry point as well
+ * as from its subpath export `'jose/key/import'`.
+ *
+ * @example
+ *
+ * ```js
+ * const ecPublicKey = await jose.importJWK(
+ *   {
+ *     crv: 'P-256',
+ *     kty: 'EC',
+ *     x: 'ySK38C1jBdLwDsNWKzzBHqKYEE5Cgv-qjWvorUXk9fw',
+ *     y: '_LeQBw07cf5t57Iavn4j-BqJsAD1dpoz8gokd3sBsOo',
+ *   },
+ *   'ES256',
+ * )
+ *
+ * const rsaPublicKey = await jose.importJWK(
+ *   {
+ *     kty: 'RSA',
+ *     e: 'AQAB',
+ *     n: '12oBZRhCiZFJLcPg59LkZZ9mdhSMTKAQZYq32k_ti5SBB6jerkh-WzOMAO664r_qyLkqHUSp3u5SbXtseZEpN3XPWGKSxjsy-1JyEFTdLSYe6f9gfrmxkUF_7DTpq0gn6rntP05g2-wFW50YO7mosfdslfrTJYWHFhJALabAeYirYD7-9kqq9ebfFMF4sRRELbv9oi36As6Q9B3Qb5_C1rAzqfao_PCsf9EPsTZsVVVkA5qoIAr47lo1ipfiBPxUCCNSdvkmDTYgvvRm6ZoMjFbvOtgyts55fXKdMWv7I9HMD5HwE9uW839PWA514qhbcIsXEYSFMPMV6fnlsiZvQQ',
+ *   },
+ *   'PS256',
+ * )
+ * ```
+ *
+ * @param jwk JSON Web Key.
+ * @param alg JSON Web Algorithm identifier to be used with the imported key. Default is the "alg"
+ *   property on the JWK. See
+ *   {@link https://github.com/panva/jose/issues/210 Algorithm Key Requirements}.
+ */
+export declare function importJWK(jwk: types.JWK, alg?: string, options?: KeyImportOptions): Promise<types.CryptoKey | Uint8Array>;