@molecule/api-jwt 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,19 @@
+/**
+ * Browser guard — `@molecule/api-jwt` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-jwt is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};
+//# sourceMappingURL=browser-guard.js.map

package/dist/browser-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.js","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,GAAG,UAIT,CAAA;AACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACrF,MAAM,IAAI,KAAK,CACb,4FAA4F;QAC1F,sFAAsF;QACtF,iFAAiF;QACjF,0CAA0C,CAC7C,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * JWT interface for molecule.dev.
+ *
+ * Provides an abstract JWT interface that can be backed by any JWT library.
+ * Use `setProvider` to provide a concrete implementation
+ * such as `@molecule/api-jwt-jsonwebtoken`.
+ *
+ * @remarks
+ * **{@link verify} is the ONLY way to trust a token — {@link decode} does NOT check the
+ * signature.** Never make an auth decision from `decode()`: an attacker can forge any
+ * payload that `decode()` will happily return. Use `verify()` (it throws — catch it) for
+ * anything security-relevant; `decode()` is only for reading a token you do NOT trust.
+ *
+ * - The signing key (private key / secret) is SERVER-SIDE only — never ship it to the
+ *   browser. Only an asymmetric PUBLIC key may be published.
+ * - A JWT payload is READABLE by anyone (base64, not encrypted) — never put a password,
+ *   secret, or sensitive PII in it.
+ * - Always set + honor expiry ({@link JWT_EXPIRES_TIME}); a non-expiring token can't be
+ *   revoked.
+ * - In a molecule app auth is ALREADY wired: the global `verifyMiddleware` verifies the JWT
+ *   and populates `res.locals.session`, so a handler calls `getUserId(res)` — do NOT call
+ *   `verify()`/`sign()` by hand for the session (see the `auth` skill). Use these directly
+ *   only for a CUSTOM token, e.g. a signed email/reset link.
+ * - **Re-signing decoded claims (refresh flows): strip `exp`/`iat` first.** `sign()`
+ *   always sets `expiresIn` (default {@link JWT_EXPIRES_TIME}), and the underlying library
+ *   throws (`Bad "options.expiresIn" option the payload already has an "exp" property`)
+ *   when the payload still carries the old `exp` — so `const { exp, iat, ...claims } =
+ *   verify(oldToken) as JwtPayload; sign(claims)` is the correct refresh shape.
+ * - Set `JWT_PRIVATE_KEY` and `JWT_PUBLIC_KEY` together (or neither). If only the private
+ *   key is set, the matching public key is DERIVED from it automatically; setting only the
+ *   public key is for verify-only deployments.
+ * - When neither key env var is set, a key pair is auto-generated on disk at
+ *   `{JWT_KEYS_DIR}/{NODE_ENV}/` — default `JWT_KEYS_DIR`: `process.cwd() + '/.keys'`, a
+ *   stable app-level directory (NOT inside `node_modules`, so `npm ci`/reinstall never
+ *   wipes it). Set `JWT_KEYS_DIR` to relocate it (e.g. a persistent volume in production).
+ *   A pre-existing pair at the legacy `node_modules`-relative location is migrated forward
+ *   automatically (with a logged warning) instead of being silently regenerated.
+ * - `JWT_ALGORITHM` (default `RS256`) is validated at module load against the
+ *   {@link JwtAlgorithm} union; an unrecognized value (e.g. a typo like `rs256`) logs an
+ *   actionable warning and falls back to `RS256` instead of failing every `sign()`/`verify()`
+ *   call later with an opaque "invalid algorithm" error.
+ *
+ * @example
+ * ```ts
+ * import { sign, verify, decode } from '@molecule/api-jwt'
+ *
+ * const token = sign({ userId }, { expiresIn: '15m' }) // server-side; expiry set
+ *
+ * try {
+ *   const claims = verify(token) as JwtPayload // signature CHECKED — safe to trust
+ *   grantAccess(claims.userId)
+ * } catch {
+ *   res.status(401).json({ error: 'Invalid or expired token.' })
+ * }
+ *
+ * decode(token) // NOT verified — never use its output for an auth decision
+ * ```
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './keys.js';
+export * from './provider.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,65 @@
+/**
+ * JWT interface for molecule.dev.
+ *
+ * Provides an abstract JWT interface that can be backed by any JWT library.
+ * Use `setProvider` to provide a concrete implementation
+ * such as `@molecule/api-jwt-jsonwebtoken`.
+ *
+ * @remarks
+ * **{@link verify} is the ONLY way to trust a token — {@link decode} does NOT check the
+ * signature.** Never make an auth decision from `decode()`: an attacker can forge any
+ * payload that `decode()` will happily return. Use `verify()` (it throws — catch it) for
+ * anything security-relevant; `decode()` is only for reading a token you do NOT trust.
+ *
+ * - The signing key (private key / secret) is SERVER-SIDE only — never ship it to the
+ *   browser. Only an asymmetric PUBLIC key may be published.
+ * - A JWT payload is READABLE by anyone (base64, not encrypted) — never put a password,
+ *   secret, or sensitive PII in it.
+ * - Always set + honor expiry ({@link JWT_EXPIRES_TIME}); a non-expiring token can't be
+ *   revoked.
+ * - In a molecule app auth is ALREADY wired: the global `verifyMiddleware` verifies the JWT
+ *   and populates `res.locals.session`, so a handler calls `getUserId(res)` — do NOT call
+ *   `verify()`/`sign()` by hand for the session (see the `auth` skill). Use these directly
+ *   only for a CUSTOM token, e.g. a signed email/reset link.
+ * - **Re-signing decoded claims (refresh flows): strip `exp`/`iat` first.** `sign()`
+ *   always sets `expiresIn` (default {@link JWT_EXPIRES_TIME}), and the underlying library
+ *   throws (`Bad "options.expiresIn" option the payload already has an "exp" property`)
+ *   when the payload still carries the old `exp` — so `const { exp, iat, ...claims } =
+ *   verify(oldToken) as JwtPayload; sign(claims)` is the correct refresh shape.
+ * - Set `JWT_PRIVATE_KEY` and `JWT_PUBLIC_KEY` together (or neither). If only the private
+ *   key is set, the matching public key is DERIVED from it automatically; setting only the
+ *   public key is for verify-only deployments.
+ * - When neither key env var is set, a key pair is auto-generated on disk at
+ *   `{JWT_KEYS_DIR}/{NODE_ENV}/` — default `JWT_KEYS_DIR`: `process.cwd() + '/.keys'`, a
+ *   stable app-level directory (NOT inside `node_modules`, so `npm ci`/reinstall never
+ *   wipes it). Set `JWT_KEYS_DIR` to relocate it (e.g. a persistent volume in production).
+ *   A pre-existing pair at the legacy `node_modules`-relative location is migrated forward
+ *   automatically (with a logged warning) instead of being silently regenerated.
+ * - `JWT_ALGORITHM` (default `RS256`) is validated at module load against the
+ *   {@link JwtAlgorithm} union; an unrecognized value (e.g. a typo like `rs256`) logs an
+ *   actionable warning and falls back to `RS256` instead of failing every `sign()`/`verify()`
+ *   call later with an opaque "invalid algorithm" error.
+ *
+ * @example
+ * ```ts
+ * import { sign, verify, decode } from '@molecule/api-jwt'
+ *
+ * const token = sign({ userId }, { expiresIn: '15m' }) // server-side; expiry set
+ *
+ * try {
+ *   const claims = verify(token) as JwtPayload // signature CHECKED — safe to trust
+ *   grantAccess(claims.userId)
+ * } catch {
+ *   res.status(401).json({ error: 'Invalid or expired token.' })
+ * }
+ *
+ * decode(token) // NOT verified — never use its output for an auth decision
+ * ```
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './keys.js';
+export * from './provider.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/keys.d.ts

@@ -0,0 +1,46 @@
+/**
+ * RSA key pair generation and loading for JWT signing/verification.
+ *
+ * Keys are loaded from environment variables (`JWT_PRIVATE_KEY`, `JWT_PUBLIC_KEY`)
+ * or from PEM files on disk at `{JWT_KEYS_DIR}/{NODE_ENV}/` (default
+ * `JWT_KEYS_DIR`: `process.cwd() + '/.keys'` — a stable, app-level directory,
+ * NOT inside `node_modules`). If no keys exist, a new RSA-2048 key pair is
+ * generated automatically on first import.
+ *
+ * @module
+ */
+/**
+ * Generates an RSA-2048 key pair in PEM format for JWT signing and verification.
+ *
+ * @returns An object containing `publicKey` and `privateKey` as PEM strings.
+ */
+export declare const generateKeyPairSync: () => {
+    publicKey: string;
+    privateKey: string;
+};
+/**
+ * Writes a freshly generated RSA key pair to disk as PEM files. Creates
+ * the output directory if it does not exist.
+ *
+ * @param outputPath - Directory to write the PEM files into; defaults to `{JWT_KEYS_DIR}/{NODE_ENV}/`.
+ */
+export declare const writeKeys: (outputPath?: string) => void;
+/**
+ * The RSA private key for signing JWTs. Read from the `JWT_PRIVATE_KEY`
+ * environment variable, or loaded from the PEM file on disk.
+ *
+ * Throws at startup if neither source provides a key — running with an
+ * empty secret would allow anyone to forge valid JWTs.
+ */
+export declare const JWT_PRIVATE_KEY: string | Buffer<ArrayBufferLike>;
+/**
+ * The RSA public key for verifying JWTs. Read from the `JWT_PUBLIC_KEY`
+ * environment variable; when only `JWT_PRIVATE_KEY` is set, the matching
+ * public key is DERIVED from it (a disk fallback could not match an
+ * env-provided private key and would make every signed token fail
+ * verification); otherwise loaded from the PEM file on disk.
+ *
+ * Throws at startup if no source provides a key.
+ */
+export declare const JWT_PUBLIC_KEY: string | Buffer<ArrayBufferLike>;
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAoCH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAAO;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAW1E,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,mBAAqB,KAAG,IAejD,CAAA;AA4GD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,kCAOtB,CAAA;AAEN;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,kCAQrB,CAAA"}

package/dist/keys.js

@@ -0,0 +1,198 @@
+/**
+ * RSA key pair generation and loading for JWT signing/verification.
+ *
+ * Keys are loaded from environment variables (`JWT_PRIVATE_KEY`, `JWT_PUBLIC_KEY`)
+ * or from PEM files on disk at `{JWT_KEYS_DIR}/{NODE_ENV}/` (default
+ * `JWT_KEYS_DIR`: `process.cwd() + '/.keys'` — a stable, app-level directory,
+ * NOT inside `node_modules`). If no keys exist, a new RSA-2048 key pair is
+ * generated automatically on first import.
+ *
+ * @module
+ */
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import process from 'process';
+import { fileURLToPath } from 'url';
+import { getLogger } from '@molecule/api-bond';
+const logger = getLogger();
+const __dirname = fileURLToPath(path.dirname(import.meta.url));
+const nodeEnv = process.env.NODE_ENV || 'development';
+// Stable, app-level default: `<app root>/.keys/{NODE_ENV}`. Explicitly
+// overridable via `JWT_KEYS_DIR` (absolute, or relative to `process.cwd()`)
+// for deployments that want keys on a persistent volume outside the app
+// checkout.
+const keysDir = process.env.JWT_KEYS_DIR
+    ? path.resolve(process.cwd(), process.env.JWT_KEYS_DIR)
+    : path.join(process.cwd(), `.keys`);
+const keysPath = path.join(keysDir, nodeEnv);
+const privateKeyPath = `${keysPath}/jwt_private_key.pem`;
+const publicKeyPath = `${keysPath}/jwt_public_key.pem`;
+// Legacy default location (one level ABOVE this package root — inside
+// `node_modules` for an installed app). Reinstalling/`npm ci` wipes
+// `node_modules`, so any key pair generated there is silently lost,
+// invalidating every session and signed link (email verification/reset)
+// on the next boot. Kept ONLY to migrate a pre-existing pair forward to the
+// new stable location below — never written to again.
+const legacyKeysPath = path.join(__dirname, `../../.keys/${nodeEnv}`);
+const legacyPrivateKeyPath = `${legacyKeysPath}/jwt_private_key.pem`;
+const legacyPublicKeyPath = `${legacyKeysPath}/jwt_public_key.pem`;
+/**
+ * Generates an RSA-2048 key pair in PEM format for JWT signing and verification.
+ *
+ * @returns An object containing `publicKey` and `privateKey` as PEM strings.
+ */
+export const generateKeyPairSync = () => crypto.generateKeyPairSync(`rsa`, {
+    modulusLength: 2048,
+    publicKeyEncoding: {
+        type: `spki`,
+        format: `pem`,
+    },
+    privateKeyEncoding: {
+        type: `pkcs8`,
+        format: `pem`,
+    },
+});
+/**
+ * Writes a freshly generated RSA key pair to disk as PEM files. Creates
+ * the output directory if it does not exist.
+ *
+ * @param outputPath - Directory to write the PEM files into; defaults to `{JWT_KEYS_DIR}/{NODE_ENV}/`.
+ */
+export const writeKeys = (outputPath = keysPath) => {
+    try {
+        const { publicKey, privateKey } = generateKeyPairSync();
+        if (!fs.existsSync(outputPath)) {
+            fs.mkdirSync(outputPath, { recursive: true });
+        }
+        fs.writeFileSync(path.join(outputPath, 'jwt_private_key.pem'), privateKey, `utf8`);
+        fs.writeFileSync(path.join(outputPath, 'jwt_public_key.pem'), publicKey, `utf8`);
+        logger.info(`JWT key pair successfully written to disk.`);
+    }
+    catch (error) {
+        logger.error(`Error writing JWT key pair:`, error);
+    }
+};
+// Ensure key files exist ONLY when the private key must come from disk.
+// When `JWT_PRIVATE_KEY` is provided via env, generating a fresh on-disk pair
+// here would be worse than useless: with `JWT_PUBLIC_KEY` unset, the public
+// key would then be read from the freshly generated file — a key that does
+// NOT match the env private key — and every token this process signs would
+// fail verification with an unexplained "invalid signature". (The public key
+// for an env-provided private key is DERIVED from it below instead.)
+if (!process.env.JWT_PRIVATE_KEY) {
+    if (!fs.existsSync(privateKeyPath) || !fs.existsSync(publicKeyPath)) {
+        // One-release migration: a pair generated by a PRE-fix version of this
+        // package lives at the legacy `node_modules`-relative path. Copy it
+        // forward to the new stable location instead of silently generating a
+        // brand-new pair — regenerating here would invalidate every existing
+        // session and signed link (email verification/reset) for a deployment
+        // that already has working keys. Once copied, this branch never runs
+        // again (the new location is populated).
+        if (fs.existsSync(legacyPrivateKeyPath) && fs.existsSync(legacyPublicKeyPath)) {
+            try {
+                fs.mkdirSync(keysPath, { recursive: true });
+                fs.copyFileSync(legacyPrivateKeyPath, privateKeyPath);
+                fs.copyFileSync(legacyPublicKeyPath, publicKeyPath);
+                logger.warn(`Migrated JWT keys from the legacy node_modules-relative location (${legacyKeysPath}) ` +
+                    `to the stable location ${keysPath}. The legacy location is wiped by every ` +
+                    `reinstall/npm ci — set JWT_PRIVATE_KEY/JWT_PUBLIC_KEY (recommended) or JWT_KEYS_DIR ` +
+                    `explicitly to control where keys live going forward.`);
+            }
+            catch (error) {
+                logger.error(`Failed to migrate JWT keys from the legacy location (${legacyKeysPath}) to ` +
+                    `${keysPath} — generating a fresh pair instead. This INVALIDATES every existing ` +
+                    `session and signed link.`, error);
+                writeKeys();
+            }
+        }
+        else {
+            writeKeys();
+        }
+    }
+}
+/**
+ * Convert PEM read from a process.env value back into a real PEM string.
+ *
+ * Node's `--env-file` (and many other dotenv readers) deliberately do NOT
+ * interpret backslash-escapes inside quoted values, so a `.env` line like
+ *   JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END..."
+ * arrives in `process.env` as a string containing literal `\n` characters
+ * (backslash + n) instead of newlines. Crypto libraries like `jsonwebtoken`
+ * then reject the value with "secretOrPrivateKey must be an asymmetric key
+ * when using RS256" because the OpenSSL parser can't find PEM headers
+ * separated by real newlines.
+ *
+ * Normalize here so any consumer of this module gets a usable PEM
+ * regardless of how the key was stored in the env source.
+ */
+const normalizePem = (value) => {
+    if (typeof value !== 'string')
+        return value;
+    // Only rewrite if the literal escape is present and there are no real
+    // newlines yet — preserves keys that arrived correctly (multi-line .env
+    // values, files on disk, etc.).
+    if (value.includes('\\n') && !value.includes('\n')) {
+        return value.replace(/\\n/g, '\n');
+    }
+    return value;
+};
+const envPrivateKey = normalizePem(process.env.JWT_PRIVATE_KEY || false);
+const envPublicKey = normalizePem(process.env.JWT_PUBLIC_KEY || false);
+/**
+ * Derive the SPKI public key from a private key PEM. Works for any
+ * asymmetric key type (RSA, EC, Ed25519) — the public half is embedded
+ * in the private key material.
+ *
+ * Used when `JWT_PRIVATE_KEY` is set but `JWT_PUBLIC_KEY` is not: deriving
+ * guarantees the pair MATCHES. Reading a public key from disk (or generating
+ * a fresh one) in that half-configured state would silently produce a
+ * mismatched pair — every token signed by this process would then fail
+ * verification with an unexplained "invalid signature".
+ *
+ * @param privateKey - The private key PEM (string or Buffer).
+ * @returns The matching public key PEM, or `false` when derivation fails
+ * (e.g. the private key PEM is malformed — signing would fail anyway).
+ */
+const derivePublicKey = (privateKey) => {
+    try {
+        return crypto.createPublicKey(privateKey).export({ type: 'spki', format: 'pem' }).toString();
+    }
+    catch (error) {
+        logger.error('JWT_PRIVATE_KEY is set but a public key could not be derived from it — the PEM is likely malformed:', error);
+        return false;
+    }
+};
+if (envPublicKey && !envPrivateKey) {
+    logger.warn('JWT_PUBLIC_KEY is set but JWT_PRIVATE_KEY is not. The private key will be loaded/generated ' +
+        'from disk, so tokens signed by THIS process will NOT verify against JWT_PUBLIC_KEY. ' +
+        'Set both env vars (or neither) unless this deployment only verifies tokens.');
+}
+/**
+ * The RSA private key for signing JWTs. Read from the `JWT_PRIVATE_KEY`
+ * environment variable, or loaded from the PEM file on disk.
+ *
+ * Throws at startup if neither source provides a key — running with an
+ * empty secret would allow anyone to forge valid JWTs.
+ */
+export const JWT_PRIVATE_KEY = envPrivateKey ||
+    (fs.existsSync(privateKeyPath) && fs.readFileSync(privateKeyPath)) ||
+    (() => {
+        throw new Error('JWT private key not found. Set JWT_PRIVATE_KEY env var or ensure key files exist.');
+    })();
+/**
+ * The RSA public key for verifying JWTs. Read from the `JWT_PUBLIC_KEY`
+ * environment variable; when only `JWT_PRIVATE_KEY` is set, the matching
+ * public key is DERIVED from it (a disk fallback could not match an
+ * env-provided private key and would make every signed token fail
+ * verification); otherwise loaded from the PEM file on disk.
+ *
+ * Throws at startup if no source provides a key.
+ */
+export const JWT_PUBLIC_KEY = envPublicKey ||
+    (envPrivateKey && derivePublicKey(envPrivateKey)) ||
+    (fs.existsSync(publicKeyPath) && fs.readFileSync(publicKeyPath)) ||
+    (() => {
+        throw new Error('JWT public key not found. Set JWT_PUBLIC_KEY env var or ensure key files exist.');
+    })();
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,MAAM,MAAM,QAAQ,CAAA;AAC3B,OAAO,EAAE,MAAM,IAAI,CAAA;AACnB,OAAO,IAAI,MAAM,MAAM,CAAA;AACvB,OAAO,OAAO,MAAM,SAAS,CAAA;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAA;AAEnC,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC9C,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;AAE1B,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;AAE9D,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,aAAa,CAAA;AAErD,uEAAuE;AACvE,4EAA4E;AAC5E,wEAAwE;AACxE,YAAY;AACZ,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY;IACtC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IACvD,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAA;AACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;AAC5C,MAAM,cAAc,GAAG,GAAG,QAAQ,sBAAsB,CAAA;AACxD,MAAM,aAAa,GAAG,GAAG,QAAQ,qBAAqB,CAAA;AAEtD,sEAAsE;AACtE,oEAAoE;AACpE,oEAAoE;AACpE,wEAAwE;AACxE,4EAA4E;AAC5E,sDAAsD;AACtD,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,eAAe,OAAO,EAAE,CAAC,CAAA;AACrE,MAAM,oBAAoB,GAAG,GAAG,cAAc,sBAAsB,CAAA;AACpE,MAAM,mBAAmB,GAAG,GAAG,cAAc,qBAAqB,CAAA;AAElE;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAA8C,EAAE,CACjF,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE;IAChC,aAAa,EAAE,IAAI;IACnB,iBAAiB,EAAE;QACjB,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE,KAAK;KACd;IACD,kBAAkB,EAAE;QAClB,IAAI,EAAE,OAAO;QACb,MAAM,EAAE,KAAK;KACd;CACF,CAAC,CAAA;AAEJ;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,UAAU,GAAG,QAAQ,EAAQ,EAAE;IACvD,IAAI,CAAC;QACH,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,mBAAmB,EAAE,CAAA;QAEvD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC/B,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QAC/C,CAAC;QAED,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,qBAAqB,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,CAAA;QAClF,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,oBAAoB,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,CAAA;QAEhF,MAAM,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAA;IAC3D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,6BAA6B,EAAE,KAAK,CAAC,CAAA;IACpD,CAAC;AACH,CAAC,CAAA;AAED,wEAAwE;AACxE,8EAA8E;AAC9E,4EAA4E;AAC5E,2EAA2E;AAC3E,2EAA2E;AAC3E,6EAA6E;AAC7E,qEAAqE;AACrE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;IACjC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QACpE,uEAAuE;QACvE,oEAAoE;QACpE,sEAAsE;QACtE,qEAAqE;QACrE,sEAAsE;QACtE,qEAAqE;QACrE,yCAAyC;QACzC,IAAI,EAAE,CAAC,UAAU,CAAC,oBAAoB,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAAC;YAC9E,IAAI,CAAC;gBACH,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;gBAC3C,EAAE,CAAC,YAAY,CAAC,oBAAoB,EAAE,cAAc,CAAC,CAAA;gBACrD,EAAE,CAAC,YAAY,CAAC,mBAAmB,EAAE,aAAa,CAAC,CAAA;gBACnD,MAAM,CAAC,IAAI,CACT,qEAAqE,cAAc,IAAI;oBACrF,0BAA0B,QAAQ,0CAA0C;oBAC5E,sFAAsF;oBACtF,sDAAsD,CACzD,CAAA;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,KAAK,CACV,wDAAwD,cAAc,OAAO;oBAC3E,GAAG,QAAQ,sEAAsE;oBACjF,0BAA0B,EAC5B,KAAK,CACN,CAAA;gBACD,SAAS,EAAE,CAAA;YACb,CAAC;QACH,CAAC;aAAM,CAAC;YACN,SAAS,EAAE,CAAA;QACb,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,YAAY,GAAG,CAAC,KAA8B,EAA2B,EAAE;IAC/E,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAC3C,sEAAsE;IACtE,wEAAwE;IACxE,gCAAgC;IAChC,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IACpC,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAED,MAAM,aAAa,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,KAAK,CAAC,CAAA;AACxE,MAAM,YAAY,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,KAAK,CAAC,CAAA;AAEtE;;;;;;;;;;;;;;GAcG;AACH,MAAM,eAAe,GAAG,CAAC,UAA2B,EAAkB,EAAE;IACtE,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAA;IAC9F,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CACV,qGAAqG,EACrG,KAAK,CACN,CAAA;QACD,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC,CAAA;AAED,IAAI,YAAY,IAAI,CAAC,aAAa,EAAE,CAAC;IACnC,MAAM,CAAC,IAAI,CACT,6FAA6F;QAC3F,sFAAsF;QACtF,6EAA6E,CAChF,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAC1B,aAAa;IACb,CAAC,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;IAClE,CAAC,GAAG,EAAE;QACJ,MAAM,IAAI,KAAK,CACb,mFAAmF,CACpF,CAAA;IACH,CAAC,CAAC,EAAE,CAAA;AAEN;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GACzB,YAAY;IACZ,CAAC,aAAa,IAAI,eAAe,CAAC,aAAa,CAAC,CAAC;IACjD,CAAC,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC;IAChE,CAAC,GAAG,EAAE;QACJ,MAAM,IAAI,KAAK,CACb,iFAAiF,CAClF,CAAA;IACH,CAAC,CAAC,EAAE,CAAA"}

package/dist/provider.d.ts

@@ -0,0 +1,82 @@
+/**
+ * JWT provider bond accessor and convenience functions.
+ *
+ * Bond packages (e.g. `@molecule/api-jwt-jsonwebtoken`) call `setProvider()`
+ * during setup. Application code uses `sign()`, `verify()`, and `decode()` directly.
+ *
+ * @module
+ */
+import type { JSONObject, JwtAlgorithm, JwtDecodeOptions, JwtPayload, JwtProvider, JwtSignOptions, JwtVerifyOptions } from './types.js';
+/**
+ * The signing algorithm used for JWT operations. Read from the `JWT_ALGORITHM`
+ * environment variable, defaulting to `RS256`. An unrecognized value logs an
+ * actionable warning at module load and falls back to `RS256` rather than
+ * failing every `sign()`/`verify()` call later with an unexplained
+ * "invalid algorithm" error.
+ */
+export declare const JWT_ALGORITHM: JwtAlgorithm;
+/**
+ * Token lifetime in seconds. Read from the `JWT_EXPIRES_TIME` environment
+ * variable, defaulting to 604800 (1 week).
+ */
+export declare const JWT_EXPIRES_TIME: number;
+/**
+ * Refresh window in seconds — tokens are refreshed if they will expire within
+ * this period. Read from the `JWT_REFRESH_TIME` environment variable,
+ * defaulting to 3600 (1 hour).
+ */
+export declare const JWT_REFRESH_TIME: number;
+/**
+ * Registers a JWT provider as the active singleton. Called by bond
+ * packages during application startup.
+ *
+ * @param provider - The JWT provider implementation to bond.
+ */
+export declare const setProvider: (provider: JwtProvider) => void;
+/**
+ * Retrieves the bonded JWT provider, throwing if none is configured.
+ *
+ * @returns The bonded JWT provider.
+ * @throws {Error} If no JWT provider has been bonded.
+ */
+export declare const getProvider: () => JwtProvider;
+/**
+ * Checks whether a JWT provider is currently bonded.
+ *
+ * @returns `true` if a JWT provider is bonded.
+ */
+export declare const hasProvider: () => boolean;
+/**
+ * Signs a payload into a JWT string using the bonded provider. Uses the
+ * configured algorithm, expiry, and private key as defaults.
+ *
+ * @param object - The JSON payload to sign.
+ * @param options - Signing options; `algorithm` defaults to `JWT_ALGORITHM`, `expiresIn` defaults to `JWT_EXPIRES_TIME`.
+ * @param options.algorithm - The signing algorithm (e.g. `RS256`, `HS256`).
+ * @param options.expiresIn - Token lifetime in seconds.
+ * @param privateKey - The private key for signing; defaults to `JWT_PRIVATE_KEY`.
+ * @returns The signed JWT string.
+ */
+export declare const sign: (object: JSONObject, { algorithm, expiresIn, ...rest }?: JwtSignOptions, privateKey?: string | Buffer) => string;
+/**
+ * Verifies a JWT string and returns the decoded payload. Uses the configured
+ * algorithm and public key as defaults.
+ *
+ * @param token - The JWT string to verify.
+ * @param options - Verification options; `algorithms` defaults to `[JWT_ALGORITHM]`.
+ * @param options.algorithms - The allowed signing algorithms for verification.
+ * @param publicKey - The public key for verification; defaults to `JWT_PUBLIC_KEY`.
+ * @returns The decoded payload string or object.
+ * @throws {Error} If the token is invalid, expired, or verification fails.
+ */
+export declare const verify: (token: string, { algorithms, ...rest }?: JwtVerifyOptions, publicKey?: string | Buffer) => string | JwtPayload;
+/**
+ * Decodes a JWT string without verifying its signature. Useful for inspecting
+ * token contents when verification is handled elsewhere.
+ *
+ * @param token - The JWT string to decode.
+ * @param options - Decode options such as `complete` for full header+payload output.
+ * @returns The decoded payload, or `null` if the token cannot be decoded.
+ */
+export declare const decode: (token: string, options?: JwtDecodeOptions) => string | JwtPayload | null;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,cAAc,EACd,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAkDnB;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,cAAwB,CAAA;AAElD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAA2D,CAAA;AAExF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAkD,CAAA;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,WAAW,KAAG,IAEnD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,QAAO,WAE9B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAO,OAE9B,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI,GACf,QAAQ,UAAU,EAClB,oCAAsE,cAAmB,EACzF,aAAY,MAAM,GAAG,MAAwB,KAC5C,MAAmF,CAAA;AAEtF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,GACjB,OAAO,MAAM,EACb,0BAA2C,gBAAqB,EAChE,YAAW,MAAM,GAAG,MAAuB,KAC1C,MAAM,GAAG,UAA6E,CAAA;AAEzF;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,EAAE,UAAU,gBAAgB,KAAG,MAAM,GAAG,UAAU,GAAG,IACnD,CAAA"}

package/dist/provider.js

@@ -0,0 +1,131 @@
+/**
+ * JWT provider bond accessor and convenience functions.
+ *
+ * Bond packages (e.g. `@molecule/api-jwt-jsonwebtoken`) call `setProvider()`
+ * during setup. Application code uses `sign()`, `verify()`, and `decode()` directly.
+ *
+ * @module
+ */
+import { bond, expectBond, getLogger, isBonded, require as bondRequire } from '@molecule/api-bond';
+import { JWT_PRIVATE_KEY, JWT_PUBLIC_KEY } from './keys.js';
+const logger = getLogger();
+const BOND_TYPE = 'jwt';
+expectBond(BOND_TYPE);
+/** Every algorithm the {@link JwtAlgorithm} union accepts. */
+const VALID_JWT_ALGORITHMS = [
+    'RS256',
+    'RS384',
+    'RS512',
+    'HS256',
+    'HS384',
+    'HS512',
+    'ES256',
+    'ES384',
+    'ES512',
+    'PS256',
+    'PS384',
+    'PS512',
+];
+/**
+ * Resolves and validates `JWT_ALGORITHM` at module load. An unset env var
+ * silently defaults to `RS256` (already-supported behavior). A SET-but-invalid
+ * value (a typo like `rs256` or `RS-256`) would otherwise produce no boot-time
+ * signal at all — every `sign()`/`verify()` call would instead fail later, at
+ * request time, with the underlying library's generic "invalid algorithm"
+ * error, which reads like a token problem rather than a config problem. Warn
+ * here, naming the bad value, and fall back to `RS256` so the process still
+ * boots and serves traffic while the misconfiguration gets fixed.
+ *
+ * @returns A valid `JwtAlgorithm`.
+ */
+const resolveJwtAlgorithm = () => {
+    const raw = process.env.JWT_ALGORITHM;
+    if (!raw) {
+        return `RS256`;
+    }
+    if (VALID_JWT_ALGORITHMS.includes(raw)) {
+        return raw;
+    }
+    logger.warn(`JWT_ALGORITHM is set to "${raw}", which is not a supported JWT algorithm. ` +
+        `Falling back to RS256. Supported values: ${VALID_JWT_ALGORITHMS.join(', ')}.`);
+    return `RS256`;
+};
+/**
+ * The signing algorithm used for JWT operations. Read from the `JWT_ALGORITHM`
+ * environment variable, defaulting to `RS256`. An unrecognized value logs an
+ * actionable warning at module load and falls back to `RS256` rather than
+ * failing every `sign()`/`verify()` call later with an unexplained
+ * "invalid algorithm" error.
+ */
+export const JWT_ALGORITHM = resolveJwtAlgorithm();
+/**
+ * Token lifetime in seconds. Read from the `JWT_EXPIRES_TIME` environment
+ * variable, defaulting to 604800 (1 week).
+ */
+export const JWT_EXPIRES_TIME = Number(process.env.JWT_EXPIRES_TIME) || 60 * 60 * 24 * 7; // 1 week
+/**
+ * Refresh window in seconds — tokens are refreshed if they will expire within
+ * this period. Read from the `JWT_REFRESH_TIME` environment variable,
+ * defaulting to 3600 (1 hour).
+ */
+export const JWT_REFRESH_TIME = Number(process.env.JWT_REFRESH_TIME) || 60 * 60; // 1 hour
+/**
+ * Registers a JWT provider as the active singleton. Called by bond
+ * packages during application startup.
+ *
+ * @param provider - The JWT provider implementation to bond.
+ */
+export const setProvider = (provider) => {
+    bond(BOND_TYPE, provider);
+};
+/**
+ * Retrieves the bonded JWT provider, throwing if none is configured.
+ *
+ * @returns The bonded JWT provider.
+ * @throws {Error} If no JWT provider has been bonded.
+ */
+export const getProvider = () => {
+    return bondRequire(BOND_TYPE);
+};
+/**
+ * Checks whether a JWT provider is currently bonded.
+ *
+ * @returns `true` if a JWT provider is bonded.
+ */
+export const hasProvider = () => {
+    return isBonded(BOND_TYPE);
+};
+/**
+ * Signs a payload into a JWT string using the bonded provider. Uses the
+ * configured algorithm, expiry, and private key as defaults.
+ *
+ * @param object - The JSON payload to sign.
+ * @param options - Signing options; `algorithm` defaults to `JWT_ALGORITHM`, `expiresIn` defaults to `JWT_EXPIRES_TIME`.
+ * @param options.algorithm - The signing algorithm (e.g. `RS256`, `HS256`).
+ * @param options.expiresIn - Token lifetime in seconds.
+ * @param privateKey - The private key for signing; defaults to `JWT_PRIVATE_KEY`.
+ * @returns The signed JWT string.
+ */
+export const sign = (object, { algorithm = JWT_ALGORITHM, expiresIn = JWT_EXPIRES_TIME, ...rest } = {}, privateKey = JWT_PRIVATE_KEY) => getProvider().sign(object, { algorithm, expiresIn, ...rest }, privateKey);
+/**
+ * Verifies a JWT string and returns the decoded payload. Uses the configured
+ * algorithm and public key as defaults.
+ *
+ * @param token - The JWT string to verify.
+ * @param options - Verification options; `algorithms` defaults to `[JWT_ALGORITHM]`.
+ * @param options.algorithms - The allowed signing algorithms for verification.
+ * @param publicKey - The public key for verification; defaults to `JWT_PUBLIC_KEY`.
+ * @returns The decoded payload string or object.
+ * @throws {Error} If the token is invalid, expired, or verification fails.
+ */
+export const verify = (token, { algorithms = [JWT_ALGORITHM], ...rest } = {}, publicKey = JWT_PUBLIC_KEY) => getProvider().verify(token, { algorithms, ...rest }, publicKey);
+/**
+ * Decodes a JWT string without verifying its signature. Useful for inspecting
+ * token contents when verification is handled elsewhere.
+ *
+ * @param token - The JWT string to decode.
+ * @param options - Decode options such as `complete` for full header+payload output.
+ * @returns The decoded payload, or `null` if the token cannot be decoded.
+ */
+export const decode = (token, options) => getProvider().decode(token, options);
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Type definitions for the JWT core interface.
+ *
+ * @module
+ */
+/**
+ * Supported JWT signing algorithms.
+ */
+export type JwtAlgorithm = 'RS256' | 'RS384' | 'RS512' | 'HS256' | 'HS384' | 'HS512' | 'ES256' | 'ES384' | 'ES512' | 'PS256' | 'PS384' | 'PS512';
+/**
+ * Options for signing a JWT.
+ */
+export interface JwtSignOptions {
+    algorithm?: JwtAlgorithm;
+    expiresIn?: number | string;
+    notBefore?: number | string;
+    audience?: string | string[];
+    issuer?: string;
+    subject?: string;
+    jwtid?: string;
+    keyid?: string;
+    header?: Record<string, unknown>;
+}
+/**
+ * Options for verifying a JWT.
+ *
+ * Note: security-hardened bonds (e.g. `@molecule/api-jwt-jsonwebtoken`)
+ * REFUSE to honor `ignoreExpiration`/`ignoreNotBefore` — an expired token
+ * always fails verification regardless of these flags. To tolerate clock
+ * skew or slow flows, use `clockTolerance` (seconds) instead.
+ */
+export interface JwtVerifyOptions {
+    algorithms?: JwtAlgorithm[];
+    audience?: string | string[];
+    issuer?: string | string[];
+    subject?: string;
+    clockTolerance?: number;
+    maxAge?: string | number;
+    complete?: boolean;
+    ignoreExpiration?: boolean;
+    ignoreNotBefore?: boolean;
+}
+/**
+ * Options for decoding a JWT (without verification).
+ */
+export interface JwtDecodeOptions {
+    complete?: boolean;
+    json?: boolean;
+}
+/**
+ * Decoded JWT payload.
+ */
+export interface JwtPayload {
+    [key: string]: unknown;
+    iss?: string;
+    sub?: string;
+    aud?: string | string[];
+    exp?: number;
+    nbf?: number;
+    iat?: number;
+    jti?: string;
+}
+/**
+ * Recursive JSON value type representing any valid JSON primitive, array, or object.
+ */
+export type JSONValue = string | number | boolean | null | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+/**
+ * A plain JSON object whose values are `JSONValue`s. Used as the payload
+ * type for JWT signing operations.
+ */
+export type JSONObject = {
+    [key: string]: JSONValue;
+};
+/**
+ * JWT provider interface that all JWT bond packages must implement.
+ *
+ * Provides `sign`, `verify`, and `decode` operations. Key management
+ * and algorithm configuration are handled by the core package.
+ */
+export interface JwtProvider {
+    sign(payload: JSONObject, options?: JwtSignOptions, privateKey?: string | Buffer): string;
+    verify(token: string, options?: JwtVerifyOptions, publicKey?: string | Buffer): string | JwtPayload;
+    decode(token: string, options?: JwtDecodeOptions): string | JwtPayload | null;
+}
+declare global {
+    namespace NodeJS {
+        /** JWT-related environment variables. */
+        interface ProcessEnv {
+            JWT_PRIVATE_KEY?: string;
+            JWT_PUBLIC_KEY?: string;
+            JWT_ALGORITHM?: string;
+            JWT_EXPIRES_TIME?: string;
+            JWT_REFRESH_TIME?: string;
+            /**
+             * Directory to store auto-generated JWT key pairs in (only used when
+             * `JWT_PRIVATE_KEY`/`JWT_PUBLIC_KEY` are unset). Absolute, or resolved
+             * relative to `process.cwd()`. Defaults to `process.cwd() + '/.keys'`.
+             */
+            JWT_KEYS_DIR?: string;
+        }
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for the JWT core interface.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@molecule/api-jwt",
+  "version": "1.0.0",
+  "description": "JWT interface and key management for molecule.dev",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "jwt",
+    "json-web-token",
+    "auth"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@molecule/api-bond": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/api-bond": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/core/jwt"
+  },
+  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/core/jwt",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}