@molecule/api-jwt 1.0.4 → 1.0.5

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-16T00:31:01.424Z
+Generated: 2026-10-16T09:59:40.216Z
 -->
 
 # @molecule/api-jwt
@@ -237,6 +237,12 @@ function hasProvider(): boolean
 Signs a payload into a JWT string using the bonded provider. Uses the
 configured algorithm, expiry, and private key as defaults.
 
+This is the LOW-LEVEL signer: it signs whatever payload it is given, and a
+token it mints is not by itself a session. For a session, use
+`authorization.set()` from `@molecule/api-resource-user` — the app's global
+`verifyMiddleware` accepts a JWT only when its payload also carries a
+`deviceId` naming an active row in `devices` (see the module `@remarks`).
+
 ```typescript
 function sign(
   object: JSONObject,
@@ -379,6 +385,14 @@ anything security-relevant; `decode()` is only for reading a token you do NOT tr
   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.
+- **{@link sign} is the low-level signer; a token it mints is NOT a session.**
+  `verifyMiddleware` (`@molecule/api-resource-user`) accepts a JWT only when its payload
+  also carries a `deviceId` naming an ACTIVE row in the app's `devices` table, so a
+  payload without one is treated as no session: `sign({ userId })` answers 401 on every
+  route although the token itself verifies. Mint a session with `authorization.set()`
+  from `@molecule/api-resource-user`, which signs and writes the session cookies — call
+  `get('device').createOrUpdate(userId, deviceName)` first and pass `{ userId, deviceId }`
+  to `set()`, as that package's own log-in handler does.
 - **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`)

package/dist/index.d.ts

@@ -21,6 +21,14 @@
  *   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.
+ * - **{@link sign} is the low-level signer; a token it mints is NOT a session.**
+ *   `verifyMiddleware` (`@molecule/api-resource-user`) accepts a JWT only when its payload
+ *   also carries a `deviceId` naming an ACTIVE row in the app's `devices` table, so a
+ *   payload without one is treated as no session: `sign({ userId })` answers 401 on every
+ *   route although the token itself verifies. Mint a session with `authorization.set()`
+ *   from `@molecule/api-resource-user`, which signs and writes the session cookies — call
+ *   `get('device').createOrUpdate(userId, deviceName)` first and pass `{ userId, deviceId }`
+ *   to `set()`, as that package's own log-in handler does.
  * - **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`)

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -21,6 +21,14 @@
  *   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.
+ * - **{@link sign} is the low-level signer; a token it mints is NOT a session.**
+ *   `verifyMiddleware` (`@molecule/api-resource-user`) accepts a JWT only when its payload
+ *   also carries a `deviceId` naming an ACTIVE row in the app's `devices` table, so a
+ *   payload without one is treated as no session: `sign({ userId })` answers 401 on every
+ *   route although the token itself verifies. Mint a session with `authorization.set()`
+ *   from `@molecule/api-resource-user`, which signs and writes the session cookies — call
+ *   `get('device').createOrUpdate(userId, deviceName)` first and pass `{ userId, deviceId }`
+ *   to `set()`, as that package's own log-in handler does.
  * - **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`)

package/dist/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/provider.d.ts

@@ -50,6 +50,12 @@ 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.
  *
+ * This is the LOW-LEVEL signer: it signs whatever payload it is given, and a
+ * token it mints is not by itself a session. For a session, use
+ * `authorization.set()` from `@molecule/api-resource-user` — the app's global
+ * `verifyMiddleware` accepts a JWT only when its payload also carries a
+ * `deviceId` naming an active row in `devices` (see the module `@remarks`).
+ *
  * @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`).

package/dist/provider.d.ts.map

@@ -1 +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"}
+{"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;;;;;;;;;;;;;;;;GAgBG;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

@@ -99,6 +99,12 @@ export const hasProvider = () => {
  * Signs a payload into a JWT string using the bonded provider. Uses the
  * configured algorithm, expiry, and private key as defaults.
  *
+ * This is the LOW-LEVEL signer: it signs whatever payload it is given, and a
+ * token it mints is not by itself a session. For a session, use
+ * `authorization.set()` from `@molecule/api-resource-user` — the app's global
+ * `verifyMiddleware` accepts a JWT only when its payload also carries a
+ * `deviceId` naming an active row in `devices` (see the module `@remarks`).
+ *
  * @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`).

package/dist/provider.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-jwt",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "JWT interface and key management for molecule.dev",
   "type": "module",
   "main": "dist/index.js",