@softistx/janus-oauth-mongo 0.0.0-stage → 0.18.5

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 (104) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +262 -2
  3. package/dist/authorization-collections.d.ts +43 -0
  4. package/dist/authorization-collections.d.ts.map +1 -0
  5. package/dist/clients-collection.d.ts +29 -0
  6. package/dist/clients-collection.d.ts.map +1 -0
  7. package/dist/collection-fields.d.ts +23 -0
  8. package/dist/collection-fields.d.ts.map +1 -0
  9. package/dist/collections.d.ts +211 -0
  10. package/dist/collections.d.ts.map +1 -0
  11. package/dist/details-field.d.ts +25 -0
  12. package/dist/details-field.d.ts.map +1 -0
  13. package/dist/device-collection.d.ts +28 -0
  14. package/dist/device-collection.d.ts.map +1 -0
  15. package/dist/dpop-replay-collection.d.ts +13 -0
  16. package/dist/dpop-replay-collection.d.ts.map +1 -0
  17. package/dist/dpop-replay.d.ts +27 -0
  18. package/dist/dpop-replay.d.ts.map +1 -0
  19. package/dist/grants-collection.d.ts +17 -0
  20. package/dist/grants-collection.d.ts.map +1 -0
  21. package/dist/index.d.ts +16 -0
  22. package/dist/index.d.ts.map +1 -0
  23. package/dist/index.js +1671 -0
  24. package/dist/index.js.map +52 -0
  25. package/dist/partitioned.d.ts +97 -0
  26. package/dist/partitioned.d.ts.map +1 -0
  27. package/dist/purge.d.ts +124 -0
  28. package/dist/purge.d.ts.map +1 -0
  29. package/dist/record-fields.d.ts +57 -0
  30. package/dist/record-fields.d.ts.map +1 -0
  31. package/dist/records/clients.d.ts +7 -0
  32. package/dist/records/clients.d.ts.map +1 -0
  33. package/dist/records/grants.d.ts +7 -0
  34. package/dist/records/grants.d.ts.map +1 -0
  35. package/dist/records/index.d.ts +5 -0
  36. package/dist/records/index.d.ts.map +1 -0
  37. package/dist/records/requests.d.ts +10 -0
  38. package/dist/records/requests.d.ts.map +1 -0
  39. package/dist/records/tokens.d.ts +10 -0
  40. package/dist/records/tokens.d.ts.map +1 -0
  41. package/dist/records-device.d.ts +7 -0
  42. package/dist/records-device.d.ts.map +1 -0
  43. package/dist/signing-keys/context.d.ts +11 -0
  44. package/dist/signing-keys/context.d.ts.map +1 -0
  45. package/dist/signing-keys/index.d.ts +22 -0
  46. package/dist/signing-keys/index.d.ts.map +1 -0
  47. package/dist/signing-keys/keyring.d.ts +9 -0
  48. package/dist/signing-keys/keyring.d.ts.map +1 -0
  49. package/dist/signing-keys/options.d.ts +15 -0
  50. package/dist/signing-keys/options.d.ts.map +1 -0
  51. package/dist/signing-keys/promote.d.ts +7 -0
  52. package/dist/signing-keys/promote.d.ts.map +1 -0
  53. package/dist/signing-keys/read.d.ts +7 -0
  54. package/dist/signing-keys/read.d.ts.map +1 -0
  55. package/dist/signing-keys/records.d.ts +13 -0
  56. package/dist/signing-keys/records.d.ts.map +1 -0
  57. package/dist/signing-keys/reseal.d.ts +25 -0
  58. package/dist/signing-keys/reseal.d.ts.map +1 -0
  59. package/dist/signing-keys/seal.d.ts +19 -0
  60. package/dist/signing-keys/seal.d.ts.map +1 -0
  61. package/dist/signing-keys/write.d.ts +7 -0
  62. package/dist/signing-keys/write.d.ts.map +1 -0
  63. package/dist/signing-keys-collection.d.ts +52 -0
  64. package/dist/signing-keys-collection.d.ts.map +1 -0
  65. package/dist/store/clients.d.ts +7 -0
  66. package/dist/store/clients.d.ts.map +1 -0
  67. package/dist/store/codes.d.ts +7 -0
  68. package/dist/store/codes.d.ts.map +1 -0
  69. package/dist/store/context.d.ts +21 -0
  70. package/dist/store/context.d.ts.map +1 -0
  71. package/dist/store/device.d.ts +7 -0
  72. package/dist/store/device.d.ts.map +1 -0
  73. package/dist/store/grant-reads.d.ts +7 -0
  74. package/dist/store/grant-reads.d.ts.map +1 -0
  75. package/dist/store/grants.d.ts +7 -0
  76. package/dist/store/grants.d.ts.map +1 -0
  77. package/dist/store/index.d.ts +58 -0
  78. package/dist/store/index.d.ts.map +1 -0
  79. package/dist/store/open.d.ts +9 -0
  80. package/dist/store/open.d.ts.map +1 -0
  81. package/dist/store/requests.d.ts +7 -0
  82. package/dist/store/requests.d.ts.map +1 -0
  83. package/dist/store/rotate.d.ts +6 -0
  84. package/dist/store/rotate.d.ts.map +1 -0
  85. package/dist/store/scope.d.ts +24 -0
  86. package/dist/store/scope.d.ts.map +1 -0
  87. package/dist/store/spend-devices.d.ts +20 -0
  88. package/dist/store/spend-devices.d.ts.map +1 -0
  89. package/dist/store/tokens.d.ts +7 -0
  90. package/dist/store/tokens.d.ts.map +1 -0
  91. package/dist/sync.d.ts +20 -0
  92. package/dist/sync.d.ts.map +1 -0
  93. package/dist/tokens-collections.d.ts +42 -0
  94. package/dist/tokens-collections.d.ts.map +1 -0
  95. package/dist/transaction.d.ts +13 -0
  96. package/dist/transaction.d.ts.map +1 -0
  97. package/dist/translate.d.ts +34 -0
  98. package/dist/translate.d.ts.map +1 -0
  99. package/docs/README.md +13 -0
  100. package/docs/guide/partitions.md +141 -0
  101. package/docs/guide/wiring.md +133 -0
  102. package/docs/roadmap.md +46 -0
  103. package/docs/troubleshooting.md +226 -0
  104. package/package.json +68 -5
@@ -0,0 +1,46 @@
1
+ # Roadmap
2
+
3
+ Where `@softistx/janus-oauth-mongo` is heading. A direction, not a commitment: there
4
+ are no dates here, and the version something shipped in is the only number.
5
+
6
+ ## Now
7
+
8
+ Nothing is under way.
9
+
10
+ ## Next
11
+
12
+ Nothing yet.
13
+
14
+ ## Later
15
+
16
+ Nothing yet.
17
+
18
+ ## Not planned
19
+
20
+ - **Standalone `mongod` without transactions.** A rotation is all or nothing,
21
+ which takes a transaction; a fallback ordering of writes would leave a
22
+ client locked out when the process died half-way.
23
+ - **Error classes of its own.** The store throws `@softistx/janus`'s `StoreFailure`.
24
+
25
+ ## Shipped
26
+
27
+ - **Authorization details** (0.17.0) — the collections keep RFC 9396 `authorizationDetails` (a canonical JSON string on requests, codes, grants, tokens and device authorizations) and the clients' `authorizationDetailsTypes`, for `@softistx/janus-oauth` 0.20.0. The validators change: run `syncMongoOAuth(db)` before deploying. No data migration. [#508](https://github.com/softistx/nxgt-janus/issues/508)
28
+ - **Token exchange** (0.16.0) — the access-token collections persist the optional `actor` of a delegated token (RFC 8693), and the client validator accepts the token-exchange grant type; the store passes the new `tokens.actor` and `grants.revokeClientForeign` cases. Run `syncMongoOAuth(db)` before deploying. [#507](https://github.com/softistx/nxgt-janus/issues/507)
29
+ - **DPoP** (0.15.0) — the collections persist the optional `jkt`, `dpopJkt` and `dpopBoundAccessTokens` fields, and `createMongoDPoPReplayCache(db)` is the `DPoPReplayCache` of `@softistx/janus-oauth`, in the new TTL collection `oauthDpopReplay` (atomic upsert on a unique `_id`). Four validators change: run `syncMongoOAuth(db)` before deploying. [#506](https://github.com/softistx/nxgt-janus/issues/506)
30
+ - **Device authorizations** (0.13.0) — the store implements the `device` capability of `@softistx/janus-oauth` for the RFC 8628 grant: the `oauthDeviceAuthorizations` collection (and its partitioned twin), `DEVICE_GRACE_SECONDS`, and a `deviceAuthorizations` count in the purge result. Run `syncMongoOAuth(db)` before deploying. [#500](https://github.com/softistx/nxgt-janus/issues/500)
31
+ - **Bound grants** (0.12.0) — the store implements `listBoundGrants` for `@softistx/janus-oauth`'s `approve(…, { bound })`: an optional `bound` on grants and a partial `bound` index (partition-prefixed in the partitioned layout). Run `syncMongoOAuth(db)` before deploying.
32
+ - **Rotating the signing-key master key** (0.11.0) — `createMongoSigningKeys` takes `encryptionKey` as a list (the first key seals, any opens), and `resealMongoSigningKeys(db, { encryptionKey, partition? })` re-encrypts the stored keys under the first one, so the old key can be dropped without losing the keys. [#654](https://github.com/softistx/nxgt-janus/issues/654)
33
+ - **Purging a partition** (0.10.0) — `purgeMongoOAuthPartition(db, { partition, signingKeys? })` deletes every client, request, code, grant, token and signing key of one partition, for the day an issuer is deleted for good, and answers the count per collection. Destructive and not undoable, but idempotent; it refuses a missing or empty `partition` and never touches the default layout or another partition. For the `default` partition, say `signingKeys: true` or `false`, since its keys are also those of an unpartitioned deployment.
34
+ - **Listing clients and grants by client** (0.9.0) — the store implements `listClients`, `listClientGrants` and `revokeClientGrants` for `@softistx/janus-oauth`'s admin methods, with a `clientId` index on grants, access tokens and refresh tokens: run `syncMongoOAuth(db)` before deploying. [#706](https://github.com/softistx/nxgt-janus/issues/706)
35
+ - **One decryption per signed token** (0.8.0) — `createMongoSigningKeys` implements `findCurrentKey`: one indexed `findOne` on the `current` key, decrypting that record only, where signing used to decrypt every published key. Needs `@softistx/janus-oauth` with the same change. [#631](https://github.com/softistx/nxgt-janus/issues/631)
36
+ - **Authentication hints on requests** — the `oauthRequests` collections persist the optional `acrValues`, `maxAge`, `prompt` and `loginHint` of a pending request. Optional: existing documents read back unchanged; run `syncMongoOAuth` to update the validators. [#892](https://github.com/softistx/nxgt-janus/issues/892)
37
+ - **OpenID Connect fields** (0.7.0) — the collections persist the optional `nonce`, `authTime`, `amr` and `acr` of requests, codes and tokens, and a client's `tokenEndpointAuthMethod` and `secretHash`, for `@softistx/janus-oauth`'s OpenID Connect hooks. Optional in every schema: existing documents read back unchanged. [#502](https://github.com/softistx/nxgt-janus/issues/502), [#556](https://github.com/softistx/nxgt-janus/issues/556)
38
+ - **Partitions for several issuers** (0.6.0) — `createMongoOAuth(db, { partition })` keeps one store per issuer in one database, with partition-scoped keys and indexes in every collection; opt-in, and the default layout is unchanged. [#503](https://github.com/softistx/nxgt-janus/issues/503), [#555](https://github.com/softistx/nxgt-janus/issues/555)
39
+ - **Encrypted signing-key store** (0.5.0) — `createMongoSigningKeys(db, { encryptionKey })`, the `SigningKeyStore` for JWT access tokens, with the private JWKs encrypted at rest (AES-256-GCM). [#504](https://github.com/softistx/nxgt-janus/issues/504)
40
+
41
+ Newest first; from the first release on, the package's CHANGELOG holds every one.
42
+
43
+ - **Moved to `@softistx` on GitHub Packages** (0.3.0) — formerly
44
+ the `@nxgt` scope on npm; same names under the new scope, published privately.
45
+
46
+ - **The first release, v0.1.0.** `createMongoOAuth` and `syncMongoOAuth`, passing the shared conformance suite against a real `mongod`, with atomic spends and a transactional refresh rotation.
@@ -0,0 +1,226 @@
1
+ # Troubleshooting `@softistx/janus-oauth-mongo`
2
+
3
+ Installing `@softistx/janus*` fails with a 401 or 404? See
4
+ [the install entry](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md#installing-softistx-packages).
5
+
6
+ Each entry is headed by the text you see. This adapter defines no error class;
7
+ it throws `@softistx/janus`'s `StoreFailure`, with `operation` the method and
8
+ `cause` the driver's error.
9
+
10
+ ## Index
11
+
12
+ - [`STORE_FAILED`: `oauthStore.<method>: the store could not answer`](#store_failed-oauthstoremethod-the-store-could-not-answer)
13
+ - [`STORE_FAILED` on `rotateRefreshToken`: `Transaction numbers are only allowed on a replica set member or mongos`](#store_failed-on-rotaterefreshtoken-transaction-numbers-are-only-allowed-on-a-replica-set-member-or-mongos)
14
+ - [`STORE_FAILED`: `a duplicate key on … which this adapter never writes on purpose`](#store_failed-a-duplicate-key-on--which-this-adapter-never-writes-on-purpose)
15
+ - [`Document failed validation` (code 121)](#document-failed-validation-code-121)
16
+ - [`the Mongo OAuth store holds authorization details that are not a JSON list of objects`](#the-mongo-oauth-store-holds-authorization-details-that-are-not-a-json-list-of-objects)
17
+ - [`createMongoOAuth: pass the Db your app opened with @softistx/mongo (got undefined)`](#createmongooauth-pass-the-db-your-app-opened-with-softistxmongo-got-undefined)
18
+ - [`createMongoOAuth: partition must be a non-empty string`](#createmongooauth-partition-must-be-a-non-empty-string) and [`a stored _id does not belong to this partition`](#store_failed-a-stored-_id-does-not-belong-to-this-partition)
19
+ - [`purgeMongoOAuthPartition: partition must be a non-empty string`](#purgemongooauthpartition-partition-must-be-a-non-empty-string) and the `default` partition's signing keys
20
+ - [`purgeMongoOAuthPartition: signingKeys is a boolean`](#purgemongooauthpartition-signingkeys-is-a-boolean)
21
+ - [`purgeMongoOAuthPartition: pass the Db your app opened with @softistx/mongo (got undefined)`](#purgemongooauthpartition-pass-the-db-your-app-opened-with-softistxmongo-got-undefined)
22
+ - [`purgeMongoOAuthPartition: pass { partition }`](#purgemongooauthpartition-pass--partition-)
23
+ - [`STORE_FAILED` after repeated `TransientTransactionError`](#store_failed-after-repeated-transienttransactionerror)
24
+ - [`not authorized on <db> to execute command` from `syncMongoOAuth`](#not-authorized-on-db-to-execute-command-from-syncmongooauth)
25
+ - [`STORE_FAILED` on `findKeys` or `findCurrentKey`: the signing keys do not decrypt](#store_failed-on-findkeys-or-findcurrentkey-the-signing-keys-do-not-decrypt)
26
+ - [`createMongoSigningKeys: encryptionKey must be …` and `resealMongoSigningKeys: encryptionKey must be …`](#createmongosigningkeys-encryptionkey-must-be--and-resealmongosigningkeys-encryptionkey-must-be-)
27
+ - [`listBoundGrants` is slow, or the `bound` index is missing](#listboundgrants-is-slow-or-the-bound-index-is-missing)
28
+ - [A lapsed code or token is still found](#a-lapsed-code-or-token-is-still-found)
29
+
30
+ ---
31
+
32
+ ### `STORE_FAILED`: `oauthStore.<method>: the store could not answer`
33
+
34
+ **When:** MongoDB is unreachable, a primary is stepping down, or a command is refused.
35
+
36
+ **Why:** the driver rejected the call. The adapter never turns that into an absence, so the server refuses the request instead of treating a client or a token as unknown.
37
+
38
+ **Fix:** read `error.cause` for the driver's message. A refused connection or a missing role is the deployment's; retrying later is safe, since every method is idempotent or atomic.
39
+
40
+ ### `STORE_FAILED` on `rotateRefreshToken`: `Transaction numbers are only allowed on a replica set member or mongos`
41
+
42
+ **When:** the first refresh on a standalone `mongod`.
43
+
44
+ **Why:** the rotation is a transaction, which MongoDB runs on a replica set or a sharded cluster only.
45
+
46
+ **Fix:** run a replica set, a single-node one included, and put `?replicaSet=rs0` in the connection string:
47
+
48
+ ```sh
49
+ mongod --replSet rs0 --bind_ip localhost --dbpath ./data &
50
+ mongosh --eval 'rs.initiate({ _id: "rs0", members: [{ _id: 0, host: "localhost:27017" }] })'
51
+ ```
52
+
53
+ ```ts
54
+ // mongodb://localhost:27017/app?replicaSet=rs0
55
+ ```
56
+
57
+ Every other method works on a standalone server; only the refresh rotation needs the transaction.
58
+
59
+ ### `STORE_FAILED`: `a duplicate key on … which this adapter never writes on purpose`
60
+
61
+ The full text is `oauthStore.<method>: a duplicate key on <index keys>, which this adapter never writes on purpose`.
62
+
63
+ **When:** an insert is refused by an index other than `_id`, or two grants collide on a different key.
64
+
65
+ **Why:** an index someone added by hand, or a database `syncMongoOAuth` did not shape, is stricter than the port.
66
+
67
+ **Fix:** list the indexes (`db.oauthGrants.getIndexes()`), drop the extra one, and run `syncMongoOAuth(db, { dropUnknownIndexes: true })` to see what else differs.
68
+
69
+ ### `Document failed validation` (code 121)
70
+
71
+ **When:** a write after upgrading this package.
72
+
73
+ **Why:** the collection's `$jsonSchema` validator is older than the code.
74
+
75
+ **Fix:** run `syncMongoOAuth(db)` before deploying the new code. With authorization details the failing write is the first one that carries `authorizationDetails` or `authorizationDetailsTypes`: seven validators changed (`oauthClients` for `authorizationDetailsTypes`, then `oauthRequests`, `oauthCodes`, `oauthGrants`, both token collections and `oauthDeviceAuthorizations` for `authorizationDetails`). With DPoP the failing write is the first one that carries `jkt`, `dpopJkt` or `dpopBoundAccessTokens`: four validators changed (`oauthClients.dpopBoundAccessTokens`, `dpopJkt` on `oauthRequests` and `oauthCodes`, `jkt` on both token collections), and `oauthDpopReplay` did not exist. The replay cache's `spend` then answers a `StoreFailure`. With token exchange the failing write is the first client with the token-exchange URN in `grantTypes`, or the first delegated access token (`actor`): the `oauthClients` and access-token validators changed.
76
+
77
+ ### `the Mongo OAuth store holds authorization details that are not a JSON list of objects`
78
+
79
+ **When:** a read of a request, code, grant, token or device authorization throws this `TypeError`.
80
+
81
+ **Why:** the stored `authorizationDetails` is one canonical JSON string the store wrote itself. A hand-edited document, or a writer other than the store, left something that is not a JSON list of objects. The store refuses to answer it as absent, which would turn a transaction-scoped grant into a broader one. The message never includes the value.
82
+
83
+ **Fix:** repair the field to a JSON list of objects, or remove it from that document (`$unset: { authorizationDetails: '' }`), and let the user consent again.
84
+
85
+ ### `createMongoOAuth: pass the Db your app opened with @softistx/mongo (got undefined)`
86
+
87
+ **When:** `createMongoOAuth(db)` is called with `undefined`, `null` or any value that is not a `Db` (the message ends in `got undefined`, `got null` or the type of any other non-Db, e.g. `got string`: the type is reported, never the value), typically a JS caller or an `as any` before the client connected.
88
+
89
+ **Why:** the store takes a `Db`, not a URL or a client; a missing `db` (and `options` that are not an object, `createMongoOAuth: options must be an object`) is refused at once with a `TypeError` before any collection is touched.
90
+
91
+ **Fix:**
92
+
93
+ ```ts
94
+ import { createMongoOAuth } from '@softistx/janus-oauth-mongo';
95
+
96
+ const store = createMongoOAuth(client.db('app')); // a Db from a connected client
97
+ ```
98
+
99
+ ### `createMongoOAuth: partition must be a non-empty string`
100
+
101
+ **When:** `createMongoOAuth(db, { partition })` with a `partition` key that is not a non-empty string: an empty string, a number, `null` or `undefined`. Leaving the key out is the default layout; a present key must be a name.
102
+
103
+ **Why:** the partition is the first part of every key and of every index of the partitioned layout; an empty or non-string one would put two issuers in the same keyspace. It is refused at wiring, before any collection is touched. Leave `partition` out to keep the default layout.
104
+
105
+ **Fix:**
106
+
107
+ ```ts
108
+ const store = createMongoOAuth(db, { partition: tenant.issuer }); // a non-empty string you derive from the issuer
109
+ ```
110
+
111
+ ### `STORE_FAILED`: `a stored _id does not belong to this partition`
112
+
113
+ **When:** a read in a partitioned store (`oauthStore.<method>: the store could not answer`, with this as the `cause`).
114
+
115
+ **Why:** a document in an `oauthPartitioned*` collection has an `_id` that is not `JSON.stringify([partition, id])` for the store's partition, so it was not written by this adapter: a hand edit, or a migration that copied the default `_id` unchanged. The store refuses to guess.
116
+
117
+ **Fix:** rewrite the `_id` (and set `partition`) as `docs/guide/partitions.md` shows, or remove the document.
118
+
119
+ ### `purgeMongoOAuthPartition: partition must be a non-empty string`
120
+
121
+ **When:** `purgeMongoOAuthPartition(db, { partition })` with a `partition` that is missing, empty or not a string, or with `partition: 'default'` and no `signingKeys` choice (`purgeMongoOAuthPartition: the signing keys of the partition 'default' are also those of an unpartitioned deployment ...`). The same text, with its own prefix, is thrown by `createMongoOAuth` and `createMongoSigningKeys` for an empty or non-string `partition` (see their entries above); `createMongoSigningKeys` reads `undefined` or `null` as `default`, so it throws only for a present value that is not a non-empty string.
122
+
123
+ **Why:** the purge is destructive and cannot be undone, so it deletes nothing unless it knows exactly what to delete: there is no "purge everything". The name `default` is also where `createMongoSigningKeys(db)` keeps the keys of an unpartitioned deployment, so deleting them is said explicitly.
124
+
125
+ **Fix:**
126
+
127
+ ```ts
128
+ await purgeMongoOAuthPartition(db, { partition: tenant.issuer }); // a non-empty string
129
+ await purgeMongoOAuthPartition(db, { partition: 'default', signingKeys: false }); // keep the shared keys
130
+ ```
131
+
132
+ ### `purgeMongoOAuthPartition: signingKeys is a boolean`
133
+
134
+ **When:** `purgeMongoOAuthPartition(db, { partition, signingKeys })` with a `signingKeys` that is present and not a boolean: a string such as `'false'`, a number, or `null`. Leaving the key out, or passing `undefined`, keeps the default (`true`, delete the keys).
135
+
136
+ **Why:** `signingKeys` decides whether the partition's signing keys are destroyed, which cannot be undone. A value that is neither `true` nor `false` is refused before any I/O rather than read as one of them: `'false'` is truthy, so reading it would delete the keys the caller meant to keep.
137
+
138
+ **Fix:**
139
+
140
+ ```ts
141
+ await purgeMongoOAuthPartition(db, { partition: tenant.issuer }); // deletes the signing keys too
142
+ await purgeMongoOAuthPartition(db, { partition: tenant.issuer, signingKeys: false }); // keeps them
143
+ ```
144
+
145
+ ### `purgeMongoOAuthPartition: pass the Db your app opened with @softistx/mongo (got undefined)`
146
+
147
+ **When:** `purgeMongoOAuthPartition(db, { partition })` with a first argument that is `undefined` or `null` (the message ends in `got undefined`, `got null` or the type of any other non-Db, e.g. `got string`: the type is reported, never the value): a `db` read before the client connected, or a JS caller.
148
+
149
+ **Why:** the purge takes the `Db` your app opened, the one `createMongoOAuth` and `createMongoSigningKeys` were built on; without one there is nothing to delete from, and it is refused with a `TypeError` before any I/O.
150
+
151
+ **Fix:**
152
+
153
+ ```ts
154
+ import { purgeMongoOAuthPartition } from '@softistx/janus-oauth-mongo';
155
+
156
+ const db = client.db('app'); // a Db from a connected client
157
+ await purgeMongoOAuthPartition(db, { partition: tenant.issuer });
158
+ ```
159
+
160
+ ### `purgeMongoOAuthPartition: pass { partition }`
161
+
162
+ **When:** the options are missing or not an object: `purgeMongoOAuthPartition(db)`, or the `Db` left out so the options land in its place, `purgeMongoOAuthPartition({ partition: 'issuer-a' })`.
163
+
164
+ **Why:** the purge is destructive and cannot be undone, so it never falls back to a default: with no options there is no partition to empty, and there is no "purge everything".
165
+
166
+ **Fix:** pass the `Db` first and name the partition:
167
+
168
+ ```ts
169
+ await purgeMongoOAuthPartition(db, { partition: tenant.issuer });
170
+ ```
171
+
172
+ ### `STORE_FAILED` after repeated `TransientTransactionError`
173
+
174
+ **When:** many refreshes of the same grant at once.
175
+
176
+ **Why:** concurrent rotations conflict; the adapter retries a transaction five times, then gives up rather than hang as the driver's `withTransaction` can for 120 seconds. `error.cause` is the last conflict.
177
+
178
+ **Fix:** the client may retry the refresh; a rotation that lost the race is answered as a replay by the server, which is the intended outcome.
179
+
180
+ ### `not authorized on <db> to execute command` from `syncMongoOAuth`
181
+
182
+ **When:** the deployment step, or a request that created the collections itself.
183
+
184
+ **Why:** creating collections, validators and indexes needs the `dbAdmin` role; the store never creates them at request time.
185
+
186
+ **Fix:**
187
+
188
+ ```ts
189
+ import { syncMongoOAuth } from '@softistx/janus-oauth-mongo';
190
+
191
+ await syncMongoOAuth(db); // with a deployment user holding dbAdmin
192
+ ```
193
+
194
+ ### `listBoundGrants` is slow, or the `bound` index is missing
195
+
196
+ **When:** after upgrading, `oauth.grants.listBound(bound)` takes long on a large `oauthGrants` collection, or `syncMongoOAuth` reports a created index named `bound`; or the first `approve(…, { bound })` fails with `STORE_FAILED` / `Document failed validation` (code 121); or saving a client with `requirePushedAuthorizationRequests` fails the same way.
197
+
198
+ **Why:** the `bound` index (partial, on `bound.type`, `bound.id`, `_id`) is created by the sync, not by the store; until it runs, the listing scans the collection. The validator an earlier version wrote also has no `bound` field and refuses extra fields, so a bound grant fails validation, and a client with `requirePushedAuthorizationRequests` too, since the `oauthClients` validator does not list it (see [Document failed validation](#document-failed-validation-code-121)). Grants bound to none are not in the index.
199
+
200
+ **Fix:**
201
+
202
+ ```ts
203
+ await syncMongoOAuth(db); // or syncMongoOAuthPartitioned(db) with partitions
204
+ ```
205
+
206
+ ### A lapsed code or token is still found
207
+
208
+ **Why:** the TTL monitor runs about every 60 seconds, and codes and metadata clients keep a 24 hour grace on purpose. This is the port's rule 3.
209
+
210
+ **Fix:** none needed. The server compares `expiresAt`; do not read the collections directly to decide validity.
211
+
212
+ ### `STORE_FAILED` on `findKeys` or `findCurrentKey`: the signing keys do not decrypt
213
+
214
+ **When:** `findCurrentKey` (every JWT sign; it decrypts the current key only) or `findKeys` (`rotateSigningKeys`; the JWKS and token verification read `findPublicKeys`, which does not decrypt) throws `signingKeys.findCurrentKey: the store could not answer` (or `signingKeys.findKeys: …`), `error.cause` typically an `OperationError` (a corrupt payload can surface as a `SyntaxError`).
215
+
216
+ **Why:** the stored private JWKs were encrypted under another `encryptionKey` (lost, rotated without keeping the old key in the list, or set wrong in this environment), or a document was copied to another `partition`. A key that is not `current` never stops signing; only `rotateSigningKeys` reads it.
217
+
218
+ **Fix:** restore the master key that sealed them, or keep it in the list (`encryptionKey: [newKey, oldKey]`) and run `resealMongoSigningKeys`. If it is lost, use a new `partition` (or delete the `oauthSigningKeys` documents) and run `rotateSigningKeys`; it creates new keys. Tokens signed by the old keys stop verifying.
219
+
220
+ ### `createMongoSigningKeys: encryptionKey must be …` and `resealMongoSigningKeys: encryptionKey must be …`
221
+
222
+ **When:** wiring (`resealMongoSigningKeys` throws the same, under its own name). The full texts are `encryptionKey must be a Uint8Array of 32 bytes (got <type>)` and `encryptionKey must be 32 bytes for AES-256-GCM (got <n>)`; in a list the key is named `encryptionKey[<i>]`. Two more are about a list: `encryptionKey must hold at least one key (got an empty list)` and `encryptionKey[<i>] is the same key as encryptionKey[<j>]`. A `StoreFailure` `signingKeys.reseal: the store could not answer` is the other side: a record no key of the list opens (see the entry above). `partition must be a non-empty string` is the same kind of wiring error, and `createMongoSigningKeys: pass the Db your app opened with @softistx/mongo` is the Db error of the entry above, which `createMongoSigningKeys` throws too.
223
+
224
+ **Why:** AES-256-GCM takes exactly 32 bytes, as a `Uint8Array`; a string, or a base64 value not decoded, is refused.
225
+
226
+ **Fix:** `Buffer.from(process.env.JWKS_MASTER_KEY ?? '', 'base64')` of 32 random bytes (`openssl rand -base64 32`). In a keyring, list each key once and put at least the new key in: `[newKey, oldKey]`.
package/package.json CHANGED
@@ -1,6 +1,69 @@
1
1
  {
2
- "name": "@softistx/janus-oauth-mongo",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "@softistx/janus-oauth-mongo",
3
+ "version": "0.18.5",
4
+ "description": "The MongoDB store for @softistx/janus-oauth: clients, authorization requests, codes, grants and hashed tokens, with single-document atomic spends and TTL indexes",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "main": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "files": [
10
+ "dist",
11
+ "docs",
12
+ "README.md",
13
+ "package.json",
14
+ "LICENSE"
15
+ ],
16
+ "exports": {
17
+ ".": {
18
+ "types": "./dist/index.d.ts",
19
+ "import": "./dist/index.js",
20
+ "default": "./dist/index.js"
21
+ },
22
+ "./package.json": "./package.json"
23
+ },
24
+ "keywords": [
25
+ "oauth",
26
+ "oauth2",
27
+ "authorization-server",
28
+ "mongodb",
29
+ "janus",
30
+ "typescript"
31
+ ],
32
+ "repository": {
33
+ "type": "git",
34
+ "url": "git+https://github.com/softistx/nxgt-janus.git",
35
+ "directory": "packages/janus-oauth-mongo"
36
+ },
37
+ "publishConfig": {
38
+ "registry": "https://registry.npmjs.org/",
39
+ "access": "public"
40
+ },
41
+ "scripts": {
42
+ "build": "bun run ../../build.ts",
43
+ "test": "bun test src",
44
+ "typecheck": "bun check",
45
+ "typecheck:tsc": "tsc --noEmit"
46
+ },
47
+ "nxgt": {
48
+ "entrypoints": [
49
+ "src/index.ts"
50
+ ]
51
+ },
52
+ "devDependencies": {
53
+ "@softistx/mongo": "^0.30.1",
54
+ "@softistx/janus": "^0.74.0",
55
+ "@softistx/janus-oauth": "^0.23.7",
56
+ "@types/bun": "^1.4.4",
57
+ "mongodb": "^7.9.0",
58
+ "mongodb-memory-server-core": "11.3.0",
59
+ "zod": "^4.6.7"
60
+ },
61
+ "peerDependencies": {
62
+ "@softistx/mongo": ">=0.27.0 <1",
63
+ "@softistx/janus": "^0.74.0",
64
+ "@softistx/janus-oauth": "^0.23.7",
65
+ "mongodb": ">=7.0.0 <8",
66
+ "typescript": "^6.0.3 || ^7.0.0",
67
+ "zod": ">=4.6.5 <5"
68
+ }
69
+ }