npm - @suveren/gateway - Versions diffs - 0.4.0 → 0.5.0 - Mend

@suveren/gateway 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (98) hide show

package/dist/ui/index.html CHANGED Viewed

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Suveren</title>
-    <script type="module" crossorigin src="/assets/index-BDQY7Z3H.js"></script>
+    <script type="module" crossorigin src="/assets/index-DedRWpBs.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-JHaCddDE.css">
   </head>
   <body>

package/lib/autostart-templates.d.mts ADDED Viewed

@@ -0,0 +1,37 @@
+/**
+ * Types for the plain-ESM autostart templates.
+ *
+ * The module is .mjs because the CLI (plain JS, no build step) imports it
+ * directly. TypeScript consumers — the tests — need declarations, and without
+ * them a typecheck fails with TS7016 rather than checking anything.
+ */
+export declare function escapeXml(value: unknown): string;
+export declare function shellQuote(value: unknown): string;
+export declare function buildLaunchAgentPlist(opts: {
+  launcherPath: string;
+  label: string;
+  logFile: string;
+  dataDir?: string;
+  path?: string;
+}): string;
+export declare function buildMacLauncher(opts: {
+  nodePath: string;
+  serverEntry: string;
+}): string;
+export declare function buildSystemdUnit(opts: {
+  nodePath: string;
+  serverEntry: string;
+  logFile: string;
+  dataDir?: string;
+  path?: string;
+}): string;
+export declare function buildWindowsTaskXml(opts: {
+  nodePath: string;
+  serverEntry: string;
+  author: string;
+  dataDir?: string;
+}): string;

package/lib/autostart-templates.mjs ADDED Viewed

@@ -0,0 +1,208 @@
+/**
+ * Autostart file contents, per platform — pure string builders, no side effects.
+ *
+ * Separated from the CLI so they can be tested. The macOS plist builder shipped
+ * with no tests and interpolated paths straight into XML: a home directory
+ * containing `&` or `<` (both legal) produced a malformed plist and an install
+ * that failed confusingly. Escaping is applied here, once, for every format
+ * that needs it.
+ *
+ * All three mechanisms are USER-level — no admin, no root:
+ *   macOS    LaunchAgent   (~/Library/LaunchAgents)
+ *   Windows  Task Scheduler ONLOGON task, registered from XML
+ *   Linux    systemd user unit (~/.config/systemd/user)
+ */
+/** Escape the five XML predefined entities. Used by both plist and Task XML. */
+export function escapeXml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+/**
+ * macOS LaunchAgent.
+ *
+ * RunAtLoad → start at login. KeepAlive → restart on crash. The API key is
+ * NEVER placed here: no argument or environment variable carries a secret, so
+ * the gateway always boots locked.
+ */
+export function buildLaunchAgentPlist({ launcherPath, label, logFile, dataDir, path }) {
+  // launchd hands a process a MINIMAL PATH (/usr/bin:/bin:/usr/sbin:/sbin).
+  // The gateway itself still starts — its node path is absolute — but it then
+  // cannot find npx or the integration bin shims, so every integration silently
+  // fails to launch and the UI shows them all "Not running". Carry the PATH
+  // captured at install time, when it is the user's real one.
+  const entries = [];
+  if (dataDir) entries.push(['SUVEREN_DATA_DIR', dataDir]);
+  if (path) entries.push(['PATH', path]);
+  const env = entries.length
+    ? '  <key>EnvironmentVariables</key>\n  <dict>\n' +
+      entries.map(([k, v]) => `    <key>${escapeXml(k)}</key>\n    <string>${escapeXml(v)}</string>\n`).join('') +
+      '  </dict>\n'
+    : '';
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${escapeXml(launcherPath)}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(logFile)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(logFile)}</string>
+${env}</dict>
+</plist>
+`;
+}
+/**
+ * A tiny launcher whose FILENAME is what macOS shows in
+ * System Settings → Login Items & Extensions.
+ *
+ * Pointing launchd straight at the node binary made the entry read "node —
+ * Item from unidentified developer": the user cannot tell what it is, and it
+ * looks like something that wandered in. A file named `Suveren` reads as
+ * itself.
+ *
+ * ("Unidentified developer" persists regardless — it means the node binary is
+ * not signed and notarized by a registered Apple developer, which is true of
+ * every Homebrew and nvm install. Nothing is bypassed; it is your own node
+ * running your own code.)
+ */
+export function buildMacLauncher({ nodePath, serverEntry }) {
+  // exec, so the launcher does not linger as an extra process between launchd
+  // and the gateway — launchd's KeepAlive and signal delivery then apply to
+  // the gateway itself.
+  return `#!/bin/sh
+# Generated by \`suveren-gateway service install\`. Safe to delete once the
+# login item is removed.
+exec ${shellQuote(nodePath)} ${shellQuote(serverEntry)} --autostart "$@"
+`;
+}
+/** Single-quote for /bin/sh, escaping embedded quotes. */
+export function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Linux systemd USER unit.
+ *
+ * Restart=always is the KeepAlive equivalent. WantedBy=default.target starts it
+ * with the user session; `loginctl enable-linger` (offered separately) extends
+ * that to boot, before any login.
+ *
+ * Environment values are quoted because systemd splits unquoted values on
+ * whitespace — a data directory with a space would otherwise be truncated.
+ */
+export function buildSystemdUnit({ nodePath, serverEntry, logFile, dataDir, path }) {
+  // Same problem as launchd: a systemd user unit does not inherit the shell's
+  // PATH, so npx and the integration shims go missing and every integration
+  // fails to start.
+  const envLines = [];
+  if (dataDir) envLines.push(`Environment="SUVEREN_DATA_DIR=${dataDir}"`);
+  if (path) envLines.push(`Environment="PATH=${path}"`);
+  const envLine = envLines.length ? envLines.join('\n') + '\n' : '';
+  return `[Unit]
+Description=Suveren gateway (Human Agency Protocol)
+Documentation=https://www.suveren.ai
+After=network-online.target
+[Service]
+Type=simple
+ExecStart=${nodePath} ${serverEntry} --autostart
+${envLine}Restart=always
+RestartSec=5
+# The gateway boots LOCKED. Nothing in this unit can unlock the vault, so a
+# restart brings the process back but never the credentials.
+StandardOutput=append:${logFile}
+StandardError=append:${logFile}
+[Install]
+WantedBy=default.target
+`;
+}
+/**
+ * Windows Task Scheduler task, as registration XML.
+ *
+ * Registered with `schtasks /Create /XML`. XML rather than the flag form
+ * because the flags cannot express restart-on-failure, and cannot reliably
+ * carry paths containing spaces.
+ *
+ * LogonType=InteractiveToken keeps it in the user's own session with no stored
+ * password and no admin rights. Hidden + no execution time limit stop it
+ * flashing a console window or being killed after the default 72 hours.
+ */
+export function buildWindowsTaskXml({ nodePath, serverEntry, author, dataDir }) {
+  // Task Scheduler requires \Command to be the executable and \Arguments the
+  // rest; quoting the script path handles spaces (e.g. under "Program Files").
+  // Task Scheduler XML carries no environment block, so the marker that this
+  // was a service start has to ride in the arguments.
+  const args = `"${serverEntry}" --autostart`;
+  const envNote = dataDir ? `Suveren data directory: ${dataDir}` : 'Suveren gateway';
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>${escapeXml(envNote)}</Description>
+    <Author>${escapeXml(author)}</Author>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <IdleSettings>
+      <StopOnIdleEnd>false</StopOnIdleEnd>
+      <RestartOnIdle>false</RestartOnIdle>
+    </IdleSettings>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>true</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>3</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${escapeXml(nodePath)}</Command>
+      <Arguments>${escapeXml(args)}</Arguments>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}

package/node_modules/jose/README.md CHANGED Viewed

@@ -124,19 +124,19 @@ Please note that certain algorithms may not be available depending on the runtim
 <details>
 <summary>Details</summary>
-- JSON Web Signature (JWS) - [RFC7515](https://www.rfc-editor.org/rfc/rfc7515)
-- JSON Web Encryption (JWE) - [RFC7516](https://www.rfc-editor.org/rfc/rfc7516)
-- JSON Web Key (JWK) - [RFC7517](https://www.rfc-editor.org/rfc/rfc7517)
-- JSON Web Algorithms (JWA) - [RFC7518](https://www.rfc-editor.org/rfc/rfc7518)
-- JSON Web Token (JWT) - [RFC7519](https://www.rfc-editor.org/rfc/rfc7519)
-- JSON Web Key Thumbprint - [RFC7638](https://www.rfc-editor.org/rfc/rfc7638)
-- JSON Web Key Thumbprint URI - [RFC9278](https://www.rfc-editor.org/rfc/rfc9278)
-- JWS Unencoded Payload Option - [RFC7797](https://www.rfc-editor.org/rfc/rfc7797)
-- CFRG Elliptic Curve ECDH and Signatures - [RFC8037](https://www.rfc-editor.org/rfc/rfc8037)
-- Fully-Specified Algorithms for JOSE - [RFC9864](https://www.rfc-editor.org/rfc/rfc9864.html)
-- ML-DSA for JOSE - [RFC9964](https://www.rfc-editor.org/rfc/rfc9964.html)
-The algorithm implementations in `jose` have been tested using test vectors from their respective specifications as well as [RFC7520](https://www.rfc-editor.org/rfc/rfc7520).
+- JSON Web Signature (JWS) - [RFC7515](https://www.rfc-editor.org/info/rfc7515/)
+- JSON Web Encryption (JWE) - [RFC7516](https://www.rfc-editor.org/info/rfc7516/)
+- JSON Web Key (JWK) - [RFC7517](https://www.rfc-editor.org/info/rfc7517/)
+- JSON Web Algorithms (JWA) - [RFC7518](https://www.rfc-editor.org/info/rfc7518/)
+- JSON Web Token (JWT) - [RFC7519](https://www.rfc-editor.org/info/rfc7519/)
+- JSON Web Key Thumbprint - [RFC7638](https://www.rfc-editor.org/info/rfc7638/)
+- JSON Web Key Thumbprint URI - [RFC9278](https://www.rfc-editor.org/info/rfc9278/)
+- JWS Unencoded Payload Option - [RFC7797](https://www.rfc-editor.org/info/rfc7797/)
+- CFRG Elliptic Curve ECDH and Signatures - [RFC8037](https://www.rfc-editor.org/info/rfc8037/)
+- Fully-Specified Algorithms for JOSE - [RFC9864](https://www.rfc-editor.org/info/rfc9864/)
+- ML-DSA for JOSE - [RFC9964](https://www.rfc-editor.org/info/rfc9964/)
+The algorithm implementations in `jose` have been tested using test vectors from their respective specifications as well as [RFC7520](https://www.rfc-editor.org/info/rfc7520/).
 </details>

package/node_modules/jose/dist/types/index.d.ts CHANGED Viewed

@@ -27,8 +27,9 @@ export { EncryptJWT } from './jwt/encrypt.js';
 export { calculateJwkThumbprint, calculateJwkThumbprintUri } from './jwk/thumbprint.js';
 export { EmbeddedJWK } from './jwk/embedded.js';
 export { createLocalJWKSet } from './jwks/local.js';
+export type { LocalJWKSet } from './jwks/local.js';
 export { createRemoteJWKSet, jwksCache, customFetch } from './jwks/remote.js';
-export type { RemoteJWKSetOptions, JWKSCacheInput, ExportedJWKSCache, FetchImplementation, } from './jwks/remote.js';
+export type { RemoteJWKSet, RemoteJWKSetOptions, JWKSCacheInput, ExportedJWKSCache, FetchImplementation, } from './jwks/remote.js';
 export { UnsecuredJWT } from './jwt/unsecured.js';
 export type { UnsecuredResult } from './jwt/unsecured.js';
 export { exportPKCS8, exportSPKI, exportJWK } from './key/export.js';
@@ -40,16 +41,16 @@ export type { ProtectedHeaderParameters } from './util/decode_protected_header.j
 import * as errors from './util/errors.js';
 export { errors };
 export { generateKeyPair } from './key/generate_key_pair.js';
-export type { GenerateKeyPairResult, GenerateKeyPairOptions } from './key/generate_key_pair.js';
+export type { GenerateKeyPairAlgorithm, GenerateKeyPairResult, GenerateKeyPairOptions, } from './key/generate_key_pair.js';
 export { generateSecret } from './key/generate_secret.js';
-export type { GenerateSecretOptions } from './key/generate_secret.js';
+export type { GenerateSecretAlgorithm, GenerateSecretOptions } from './key/generate_secret.js';
 import * as base64url from './util/base64url.js';
 export { base64url };
-export type { CompactDecryptResult, CompactJWEHeaderParameters, CompactJWSHeaderParameters, CompactVerifyResult, CritOption, CryptoKey, DecryptOptions, EncryptOptions, FlattenedDecryptResult, FlattenedJWE, FlattenedJWS, FlattenedJWSInput, FlattenedVerifyResult, GeneralDecryptResult, GeneralJWE, GeneralJWS, GeneralJWSInput, GeneralVerifyResult, GetKeyFunction, JoseHeaderParameters, JSONWebKeySet, JWEHeaderParameters, JWEKeyManagementHeaderParameters, JWK_EC_Private, JWK_EC_Public, JWK_oct, JWK_OKP_Private, JWK_OKP_Public, JWK_RSA_Private, JWK_RSA_Public, JWK, JWKParameters, JWSHeaderParameters, JWTClaimVerificationOptions, JWTDecryptResult, JWTHeaderParameters, JWTPayload, JWTVerifyResult, KeyObject, ProduceJWT, ResolvedKey, SignOptions, VerifyOptions, } from './types.d.ts';
+export type { AnyJWK, CompactDecryptResult, CompactJWEHeaderParameters, CompactJWSHeaderParameters, CompactVerifyResult, CritOption, CryptoKey, DecryptOptions, EncryptOptions, FlattenedDecryptResult, FlattenedJWE, FlattenedJWS, FlattenedJWSInput, FlattenedVerifyResult, GeneralDecryptResult, GeneralJWE, GeneralJWS, GeneralJWSInput, GeneralVerifyResult, GetKeyFunction, JoseHeaderParameters, JSONWebKeySet, JWEContentEncryptionAlgorithm, JWEHeaderParameters, JWEKeyManagementAlgorithm, JWEKeyManagementHeaderParameters, JWK_AKP_Private, JWK_AKP_Public, JWK_EC_Private, JWK_EC_Public, JWK_oct, JWK_OKP_Private, JWK_OKP_Public, JWK_RSA_Private, JWK_RSA_Public, JWK, JWKKeyType, JWKParameters, JWSAlgorithm, JWSHeaderParameters, JWTClaimVerificationOptions, JWTDecryptResult, JWTHeaderParameters, JWTPayload, JWTVerifyResult, KeyInput, KeyObject, ProduceJWT, ResolvedKey, SignOptions, VerifyOptions, } from './types.d.ts';
 /**
  * In prior releases this indicated whether a Node.js-specific build was loaded, this is now fixed
  * to `"WebCryptoAPI"`
  *
- * @deprecated
+ * @deprecated Remove any runtime branching on this value; it is always `"WebCryptoAPI"`.
  */
 export declare const cryptoRuntime = "WebCryptoAPI";

package/node_modules/jose/dist/types/jwe/compact/decrypt.d.ts CHANGED Viewed

@@ -1,31 +1,37 @@
-/**
- * Decrypting JSON Web Encryption (JWE) in Compact Serialization
- *
- * @module
- */
 import type * as types from '../../types.d.ts';
 /**
  * Interface for Compact JWE Decryption dynamic key resolution. No token components have been
  * verified at the time of this function call.
  */
-export interface CompactDecryptGetKey extends types.GetKeyFunction<types.CompactJWEHeaderParameters, types.FlattenedJWE> {
+export interface CompactDecryptGetKey<KeyType extends types.CryptoKey | Uint8Array = types.CryptoKey | Uint8Array> extends types.GetKeyFunction<types.CompactJWEHeaderParameters, types.FlattenedJWE, KeyType | types.KeyObject | types.JWK> {
 }
 /**
  * Decrypts a Compact JWE.
  *
- * This function is exported (as a named export) from the main `'jose'` module entry point as well
- * as from its subpath export `'jose/jwe/compact/decrypt'`.
- *
  * @param jwe Compact JWE.
  * @param key Private Key or Secret to decrypt the JWE with. See
  *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWE Decryption options.
  */
-export declare function compactDecrypt(jwe: string | Uint8Array, key: types.CryptoKey | types.KeyObject | types.JWK | Uint8Array, options?: types.DecryptOptions): Promise<types.CompactDecryptResult>;
+export declare function compactDecrypt(jwe: string | Uint8Array, key: types.KeyInput, options?: types.DecryptOptions): Promise<types.CompactDecryptResult>;
 /**
+ * Decrypts a Compact JWE, resolving the key dynamically. The result additionally carries the
+ * {@link types.ResolvedKey.key resolved key}.
+ *
  * @param jwe Compact JWE.
  * @param getKey Function resolving Private Key or Secret to decrypt the JWE with. See
  *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWE Decryption options.
  */
-export declare function compactDecrypt(jwe: string | Uint8Array, getKey: CompactDecryptGetKey, options?: types.DecryptOptions): Promise<types.CompactDecryptResult & types.ResolvedKey>;
+export declare function compactDecrypt<KeyType extends types.CryptoKey | Uint8Array = types.CryptoKey | Uint8Array>(jwe: string | Uint8Array, getKey: CompactDecryptGetKey<KeyType>, options?: types.DecryptOptions): Promise<types.CompactDecryptResult & types.ResolvedKey<KeyType>>;
+/**
+ * Accepts either form of the `key` argument. Use this overload when forwarding a value that may be
+ * either a key or a key resolution function; `key` is present on the result only when a resolution
+ * function was used.
+ *
+ * @param jwe Compact JWE.
+ * @param key Private Key or Secret, or a function resolving one, to decrypt the JWE with. See
+ *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
+ * @param options JWE Decryption options.
+ */
+export declare function compactDecrypt(jwe: string | Uint8Array, key: types.KeyInput | CompactDecryptGetKey, options?: types.DecryptOptions): Promise<types.CompactDecryptResult & Partial<types.ResolvedKey>>;

package/node_modules/jose/dist/types/jwe/compact/encrypt.d.ts CHANGED Viewed

@@ -1,16 +1,5 @@
-/**
- * Encrypting JSON Web Encryption (JWE) in Compact Serialization
- *
- * @module
- */
 import type * as types from '../../types.d.ts';
-/**
- * The CompactEncrypt class is used to build and encrypt Compact JWE strings.
- *
- * This class is exported (as a named export) from the main `'jose'` module entry point as well as
- * from its subpath export `'jose/jwe/compact/encrypt'`.
- *
- */
+/** The CompactEncrypt class is used to build and encrypt Compact JWE strings. */
 export declare class CompactEncrypt {
     #private;
     /**
@@ -21,7 +10,7 @@ export declare class CompactEncrypt {
     constructor(plaintext: Uint8Array);
     /**
      * Sets a content encryption key to use, by default a random suitable one is generated for the JWE
-     * enc" (Encryption Algorithm) Header Parameter.
+     * "enc" (Encryption Algorithm) Header Parameter.
      *
      * @deprecated You should not use this method. It is only really intended for test and vector
      *   validation purposes.
@@ -31,7 +20,7 @@ export declare class CompactEncrypt {
     setContentEncryptionKey(cek: Uint8Array): this;
     /**
      * Sets the JWE Initialization Vector to use for content encryption, by default a random suitable
-     * one is generated for the JWE enc" (Encryption Algorithm) Header Parameter.
+     * one is generated for the JWE "enc" (Encryption Algorithm) Header Parameter.
      *
      * @deprecated You should not use this method. It is only really intended for test and vector
      *   validation purposes.
@@ -46,10 +35,9 @@ export declare class CompactEncrypt {
      */
     setProtectedHeader(protectedHeader: types.CompactJWEHeaderParameters): this;
     /**
-     * Sets the JWE Key Management parameters to be used when encrypting.
-     *
-     * (ECDH-ES) Use of this method is needed for ECDH based algorithms to set the "apu" (Agreement
-     * PartyUInfo) or "apv" (Agreement PartyVInfo) parameters.
+     * Sets the JWE Key Management parameters to be used when encrypting. For ECDH based algorithms,
+     * use this method to set the "apu" (Agreement PartyUInfo) or "apv" (Agreement PartyVInfo)
+     * parameters.
      *
      * @param parameters JWE Key Management parameters.
      */
@@ -61,5 +49,5 @@ export declare class CompactEncrypt {
      *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
      * @param options JWE Encryption options.
      */
-    encrypt(key: types.CryptoKey | types.KeyObject | types.JWK | Uint8Array, options?: types.EncryptOptions): Promise<string>;
+    encrypt(key: types.KeyInput, options?: types.EncryptOptions): Promise<string>;
 }

package/node_modules/jose/dist/types/jwe/flattened/decrypt.d.ts CHANGED Viewed

@@ -1,31 +1,37 @@
-/**
- * Decrypting JSON Web Encryption (JWE) in Flattened JSON Serialization
- *
- * @module
- */
 import type * as types from '../../types.d.ts';
 /**
  * Interface for Flattened JWE Decryption dynamic key resolution. No token components have been
  * verified at the time of this function call.
  */
-export interface FlattenedDecryptGetKey extends types.GetKeyFunction<types.JWEHeaderParameters | undefined, types.FlattenedJWE> {
+export interface FlattenedDecryptGetKey<KeyType extends types.CryptoKey | Uint8Array = types.CryptoKey | Uint8Array> extends types.GetKeyFunction<types.JWEHeaderParameters | undefined, types.FlattenedJWE, KeyType | types.KeyObject | types.JWK> {
 }
 /**
  * Decrypts a Flattened JWE.
  *
- * This function is exported (as a named export) from the main `'jose'` module entry point as well
- * as from its subpath export `'jose/jwe/flattened/decrypt'`.
- *
  * @param jwe Flattened JWE.
  * @param key Private Key or Secret to decrypt the JWE with. See
  *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWE Decryption options.
  */
-export declare function flattenedDecrypt(jwe: types.FlattenedJWE, key: types.CryptoKey | types.KeyObject | types.JWK | Uint8Array, options?: types.DecryptOptions): Promise<types.FlattenedDecryptResult>;
+export declare function flattenedDecrypt(jwe: types.FlattenedJWE, key: types.KeyInput, options?: types.DecryptOptions): Promise<types.FlattenedDecryptResult>;
 /**
+ * Decrypts a Flattened JWE, resolving the key dynamically. The result additionally carries the
+ * {@link types.ResolvedKey.key resolved key}.
+ *
  * @param jwe Flattened JWE.
  * @param getKey Function resolving Private Key or Secret to decrypt the JWE with. See
  *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWE Decryption options.
  */
-export declare function flattenedDecrypt(jwe: types.FlattenedJWE, getKey: FlattenedDecryptGetKey, options?: types.DecryptOptions): Promise<types.FlattenedDecryptResult & types.ResolvedKey>;
+export declare function flattenedDecrypt<KeyType extends types.CryptoKey | Uint8Array = types.CryptoKey | Uint8Array>(jwe: types.FlattenedJWE, getKey: FlattenedDecryptGetKey<KeyType>, options?: types.DecryptOptions): Promise<types.FlattenedDecryptResult & types.ResolvedKey<KeyType>>;
+/**
+ * Accepts either form of the `key` argument. Use this overload when forwarding a value that may be
+ * either a key or a key resolution function; `key` is present on the result only when a resolution
+ * function was used.
+ *
+ * @param jwe Flattened JWE.
+ * @param key Private Key or Secret, or a function resolving one, to decrypt the JWE with. See
+ *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
+ * @param options JWE Decryption options.
+ */
+export declare function flattenedDecrypt(jwe: types.FlattenedJWE, key: types.KeyInput | FlattenedDecryptGetKey, options?: types.DecryptOptions): Promise<types.FlattenedDecryptResult & Partial<types.ResolvedKey>>;

package/node_modules/jose/dist/types/jwe/flattened/encrypt.d.ts CHANGED Viewed

@@ -1,16 +1,5 @@
-/**
- * Encrypting JSON Web Encryption (JWE) in Flattened JSON Serialization
- *
- * @module
- */
 import type * as types from '../../types.d.ts';
-/**
- * The FlattenedEncrypt class is used to build and encrypt Flattened JWE objects.
- *
- * This class is exported (as a named export) from the main `'jose'` module entry point as well as
- * from its subpath export `'jose/jwe/flattened/encrypt'`.
- *
- */
+/** The FlattenedEncrypt class is used to build and encrypt Flattened JWE objects. */
 export declare class FlattenedEncrypt {
     #private;
     /**
@@ -20,10 +9,9 @@ export declare class FlattenedEncrypt {
      */
     constructor(plaintext: Uint8Array);
     /**
-     * Sets the JWE Key Management parameters to be used when encrypting.
-     *
-     * (ECDH-ES) Use of this method is needed for ECDH based algorithms to set the "apu" (Agreement
-     * PartyUInfo) or "apv" (Agreement PartyVInfo) parameters.
+     * Sets the JWE Key Management parameters to be used when encrypting. For ECDH based algorithms,
+     * use this method to set the "apu" (Agreement PartyUInfo) or "apv" (Agreement PartyVInfo)
+     * parameters.
      *
      * @param parameters JWE Key Management parameters.
      */
@@ -54,7 +42,7 @@ export declare class FlattenedEncrypt {
     setAdditionalAuthenticatedData(aad: Uint8Array): this;
     /**
      * Sets a content encryption key to use, by default a random suitable one is generated for the JWE
-     * enc" (Encryption Algorithm) Header Parameter.
+     * "enc" (Encryption Algorithm) Header Parameter.
      *
      * @deprecated You should not use this method. It is only really intended for test and vector
      *   validation purposes.
@@ -64,7 +52,7 @@ export declare class FlattenedEncrypt {
     setContentEncryptionKey(cek: Uint8Array): this;
     /**
      * Sets the JWE Initialization Vector to use for content encryption, by default a random suitable
-     * one is generated for the JWE enc" (Encryption Algorithm) Header Parameter.
+     * one is generated for the JWE "enc" (Encryption Algorithm) Header Parameter.
      *
      * @deprecated You should not use this method. It is only really intended for test and vector
      *   validation purposes.
@@ -79,5 +67,5 @@ export declare class FlattenedEncrypt {
      *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
      * @param options JWE Encryption options.
      */
-    encrypt(key: types.CryptoKey | types.KeyObject | types.JWK | Uint8Array, options?: types.EncryptOptions): Promise<types.FlattenedJWE>;
+    encrypt(key: types.KeyInput, options?: types.EncryptOptions): Promise<types.FlattenedJWE>;
 }

package/node_modules/jose/dist/types/jwe/general/decrypt.d.ts CHANGED Viewed

@@ -1,23 +1,14 @@
-/**
- * Decrypting JSON Web Encryption (JWE) in General JSON Serialization
- *
- * @module
- */
 import type * as types from '../../types.d.ts';
 /**
  * Interface for General JWE Decryption dynamic key resolution. No token components have been
  * verified at the time of this function call.
  */
-export interface GeneralDecryptGetKey extends types.GetKeyFunction<types.JWEHeaderParameters, types.FlattenedJWE> {
+export interface GeneralDecryptGetKey<KeyType extends types.CryptoKey | Uint8Array = types.CryptoKey | Uint8Array> extends types.GetKeyFunction<types.JWEHeaderParameters | undefined, types.FlattenedJWE, KeyType | types.KeyObject | types.JWK> {
 }
 /**
  * Decrypts a General JWE.
  *
- * This function is exported (as a named export) from the main `'jose'` module entry point as well
- * as from its subpath export `'jose/jwe/general/decrypt'`.
- *
- * > [!NOTE]\
- * > The function iterates over the `recipients` array in the General JWE and returns the decryption
+ * > Note: The function iterates over the `recipients` array in the General JWE and returns the decryption
  * > result of the first recipient entry that can be successfully decrypted. The result only contains
  * > the plaintext and headers of that successfully decrypted recipient entry. Other recipient entries
  * > in the General JWE are not validated, and their headers are not included in the returned result.
@@ -28,11 +19,25 @@ export interface GeneralDecryptGetKey extends types.GetKeyFunction<types.JWEHead
  *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWE Decryption options.
  */
-export declare function generalDecrypt(jwe: types.GeneralJWE, key: types.CryptoKey | types.KeyObject | types.JWK | Uint8Array, options?: types.DecryptOptions): Promise<types.GeneralDecryptResult>;
+export declare function generalDecrypt(jwe: types.GeneralJWE, key: types.KeyInput, options?: types.DecryptOptions): Promise<types.GeneralDecryptResult>;
 /**
+ * Decrypts a General JWE, resolving the key dynamically. The result additionally carries the
+ * {@link types.ResolvedKey.key resolved key}.
+ *
  * @param jwe General JWE.
  * @param getKey Function resolving Private Key or Secret to decrypt the JWE with. See
  *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWE Decryption options.
  */
-export declare function generalDecrypt(jwe: types.GeneralJWE, getKey: GeneralDecryptGetKey, options?: types.DecryptOptions): Promise<types.GeneralDecryptResult & types.ResolvedKey>;
+export declare function generalDecrypt<KeyType extends types.CryptoKey | Uint8Array = types.CryptoKey | Uint8Array>(jwe: types.GeneralJWE, getKey: GeneralDecryptGetKey<KeyType>, options?: types.DecryptOptions): Promise<types.GeneralDecryptResult & types.ResolvedKey<KeyType>>;
+/**
+ * Accepts either form of the `key` argument. Use this overload when forwarding a value that may be
+ * either a key or a key resolution function; `key` is present on the result only when a resolution
+ * function was used.
+ *
+ * @param jwe General JWE.
+ * @param key Private Key or Secret, or a function resolving one, to decrypt the JWE with. See
+ *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
+ * @param options JWE Decryption options.
+ */
+export declare function generalDecrypt(jwe: types.GeneralJWE, key: types.KeyInput | GeneralDecryptGetKey, options?: types.DecryptOptions): Promise<types.GeneralDecryptResult & Partial<types.ResolvedKey>>;