@softistx/janus-graphql 0.0.0-stage → 0.30.1

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 (207) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +716 -2
  3. package/dist/api-keys/index.d.ts +11 -0
  4. package/dist/api-keys/index.d.ts.map +1 -0
  5. package/dist/api-keys/resolvers/deps.d.ts +39 -0
  6. package/dist/api-keys/resolvers/deps.d.ts.map +1 -0
  7. package/dist/api-keys/resolvers/index.d.ts +39 -0
  8. package/dist/api-keys/resolvers/index.d.ts.map +1 -0
  9. package/dist/api-keys/resolvers/list.d.ts +16 -0
  10. package/dist/api-keys/resolvers/list.d.ts.map +1 -0
  11. package/dist/api-keys/resolvers/manage.d.ts +17 -0
  12. package/dist/api-keys/resolvers/manage.d.ts.map +1 -0
  13. package/dist/api-keys/sdl.d.ts +14 -0
  14. package/dist/api-keys/sdl.d.ts.map +1 -0
  15. package/dist/api-keys/shape.d.ts +38 -0
  16. package/dist/api-keys/shape.d.ts.map +1 -0
  17. package/dist/api-keys/types.d.ts +149 -0
  18. package/dist/api-keys/types.d.ts.map +1 -0
  19. package/dist/avatar/index.d.ts +32 -0
  20. package/dist/avatar/index.d.ts.map +1 -0
  21. package/dist/avatar/resolvers.d.ts +41 -0
  22. package/dist/avatar/resolvers.d.ts.map +1 -0
  23. package/dist/avatar/sdl.d.ts +16 -0
  24. package/dist/avatar/sdl.d.ts.map +1 -0
  25. package/dist/bad-input.d.ts +17 -0
  26. package/dist/bad-input.d.ts.map +1 -0
  27. package/dist/connection/connection.d.ts +36 -0
  28. package/dist/connection/connection.d.ts.map +1 -0
  29. package/dist/connection/credential.d.ts +34 -0
  30. package/dist/connection/credential.d.ts.map +1 -0
  31. package/dist/connection/types.d.ts +61 -0
  32. package/dist/connection/types.d.ts.map +1 -0
  33. package/dist/context/create.d.ts +32 -0
  34. package/dist/context/create.d.ts.map +1 -0
  35. package/dist/context/index.d.ts +9 -0
  36. package/dist/context/index.d.ts.map +1 -0
  37. package/dist/context/registry.d.ts +72 -0
  38. package/dist/context/registry.d.ts.map +1 -0
  39. package/dist/context/resolve.d.ts +20 -0
  40. package/dist/context/resolve.d.ts.map +1 -0
  41. package/dist/device.d.ts +28 -0
  42. package/dist/device.d.ts.map +1 -0
  43. package/dist/directives/apply.d.ts +51 -0
  44. package/dist/directives/apply.d.ts.map +1 -0
  45. package/dist/directives/guard.d.ts +22 -0
  46. package/dist/directives/guard.d.ts.map +1 -0
  47. package/dist/directives/permission/enforce.d.ts +24 -0
  48. package/dist/directives/permission/enforce.d.ts.map +1 -0
  49. package/dist/directives/permission/model.d.ts +35 -0
  50. package/dist/directives/permission/model.d.ts.map +1 -0
  51. package/dist/directives/permission/path.d.ts +31 -0
  52. package/dist/directives/permission/path.d.ts.map +1 -0
  53. package/dist/directives/permission/validate.d.ts +42 -0
  54. package/dist/directives/permission/validate.d.ts.map +1 -0
  55. package/dist/directives/read.d.ts +43 -0
  56. package/dist/directives/read.d.ts.map +1 -0
  57. package/dist/directives/validate.d.ts +39 -0
  58. package/dist/directives/validate.d.ts.map +1 -0
  59. package/dist/directives/words.d.ts +7 -0
  60. package/dist/directives/words.d.ts.map +1 -0
  61. package/dist/errors/denial.d.ts +6 -0
  62. package/dist/errors/denial.d.ts.map +1 -0
  63. package/dist/errors/index.d.ts +12 -0
  64. package/dist/errors/index.d.ts.map +1 -0
  65. package/dist/errors/janus-error.d.ts +20 -0
  66. package/dist/errors/janus-error.d.ts.map +1 -0
  67. package/dist/errors/mask.d.ts +69 -0
  68. package/dist/errors/mask.d.ts.map +1 -0
  69. package/dist/fresh.d.ts +44 -0
  70. package/dist/fresh.d.ts.map +1 -0
  71. package/dist/helpers.d.ts +56 -0
  72. package/dist/helpers.d.ts.map +1 -0
  73. package/dist/index.d.ts +86 -0
  74. package/dist/index.d.ts.map +1 -0
  75. package/dist/index.js +3393 -0
  76. package/dist/index.js.map +75 -0
  77. package/dist/invitations/index.d.ts +12 -0
  78. package/dist/invitations/index.d.ts.map +1 -0
  79. package/dist/invitations/resolvers/anonymous.d.ts +11 -0
  80. package/dist/invitations/resolvers/anonymous.d.ts.map +1 -0
  81. package/dist/invitations/resolvers/deps.d.ts +38 -0
  82. package/dist/invitations/resolvers/deps.d.ts.map +1 -0
  83. package/dist/invitations/resolvers/index.d.ts +37 -0
  84. package/dist/invitations/resolvers/index.d.ts.map +1 -0
  85. package/dist/invitations/resolvers/owner.d.ts +17 -0
  86. package/dist/invitations/resolvers/owner.d.ts.map +1 -0
  87. package/dist/invitations/sdl/accept.d.ts +7 -0
  88. package/dist/invitations/sdl/accept.d.ts.map +1 -0
  89. package/dist/invitations/sdl/index.d.ts +14 -0
  90. package/dist/invitations/sdl/index.d.ts.map +1 -0
  91. package/dist/invitations/sdl/owner.d.ts +8 -0
  92. package/dist/invitations/sdl/owner.d.ts.map +1 -0
  93. package/dist/invitations/shape.d.ts +63 -0
  94. package/dist/invitations/shape.d.ts.map +1 -0
  95. package/dist/invitations/types/index.d.ts +5 -0
  96. package/dist/invitations/types/index.d.ts.map +1 -0
  97. package/dist/invitations/types/options.d.ts +104 -0
  98. package/dist/invitations/types/options.d.ts.map +1 -0
  99. package/dist/invitations/types/out.d.ts +136 -0
  100. package/dist/invitations/types/out.d.ts.map +1 -0
  101. package/dist/invitations/types/surface.d.ts +18 -0
  102. package/dist/invitations/types/surface.d.ts.map +1 -0
  103. package/dist/map-code.d.ts +10 -0
  104. package/dist/map-code.d.ts.map +1 -0
  105. package/dist/mask-error.d.ts +18 -0
  106. package/dist/mask-error.d.ts.map +1 -0
  107. package/dist/memo.d.ts +16 -0
  108. package/dist/memo.d.ts.map +1 -0
  109. package/dist/options.d.ts +17 -0
  110. package/dist/options.d.ts.map +1 -0
  111. package/dist/passkeys/deps.d.ts +23 -0
  112. package/dist/passkeys/deps.d.ts.map +1 -0
  113. package/dist/passkeys/first-factor.types.d.ts +38 -0
  114. package/dist/passkeys/first-factor.types.d.ts.map +1 -0
  115. package/dist/passkeys/index.d.ts +14 -0
  116. package/dist/passkeys/index.d.ts.map +1 -0
  117. package/dist/passkeys/resolvers.d.ts +23 -0
  118. package/dist/passkeys/resolvers.d.ts.map +1 -0
  119. package/dist/passkeys/sdl.d.ts +14 -0
  120. package/dist/passkeys/sdl.d.ts.map +1 -0
  121. package/dist/passkeys/shape.d.ts +14 -0
  122. package/dist/passkeys/shape.d.ts.map +1 -0
  123. package/dist/passkeys/sign-in.resolvers.d.ts +19 -0
  124. package/dist/passkeys/sign-in.resolvers.d.ts.map +1 -0
  125. package/dist/passkeys/sign-in.sdl.d.ts +16 -0
  126. package/dist/passkeys/sign-in.sdl.d.ts.map +1 -0
  127. package/dist/passkeys/types.d.ts +193 -0
  128. package/dist/passkeys/types.d.ts.map +1 -0
  129. package/dist/plugin.d.ts +59 -0
  130. package/dist/plugin.d.ts.map +1 -0
  131. package/dist/renewal.d.ts +51 -0
  132. package/dist/renewal.d.ts.map +1 -0
  133. package/dist/report.d.ts +29 -0
  134. package/dist/report.d.ts.map +1 -0
  135. package/dist/sdl.d.ts +12 -0
  136. package/dist/sdl.d.ts.map +1 -0
  137. package/dist/second-factor/index.d.ts +12 -0
  138. package/dist/second-factor/index.d.ts.map +1 -0
  139. package/dist/second-factor/resolvers/deps.d.ts +39 -0
  140. package/dist/second-factor/resolvers/deps.d.ts.map +1 -0
  141. package/dist/second-factor/resolvers/index.d.ts +39 -0
  142. package/dist/second-factor/resolvers/index.d.ts.map +1 -0
  143. package/dist/second-factor/resolvers/sign-in.d.ts +10 -0
  144. package/dist/second-factor/resolvers/sign-in.d.ts.map +1 -0
  145. package/dist/second-factor/resolvers/status.d.ts +10 -0
  146. package/dist/second-factor/resolvers/status.d.ts.map +1 -0
  147. package/dist/second-factor/resolvers/step-up.d.ts +16 -0
  148. package/dist/second-factor/resolvers/step-up.d.ts.map +1 -0
  149. package/dist/second-factor/resolvers/writes.d.ts +19 -0
  150. package/dist/second-factor/resolvers/writes.d.ts.map +1 -0
  151. package/dist/second-factor/sdl.d.ts +14 -0
  152. package/dist/second-factor/sdl.d.ts.map +1 -0
  153. package/dist/second-factor/shape.d.ts +18 -0
  154. package/dist/second-factor/shape.d.ts.map +1 -0
  155. package/dist/second-factor/types/index.d.ts +5 -0
  156. package/dist/second-factor/types/index.d.ts.map +1 -0
  157. package/dist/second-factor/types/options.d.ts +61 -0
  158. package/dist/second-factor/types/options.d.ts.map +1 -0
  159. package/dist/second-factor/types/out.d.ts +84 -0
  160. package/dist/second-factor/types/out.d.ts.map +1 -0
  161. package/dist/second-factor/types/surface.d.ts +89 -0
  162. package/dist/second-factor/types/surface.d.ts.map +1 -0
  163. package/dist/social/index.d.ts +10 -0
  164. package/dist/social/index.d.ts.map +1 -0
  165. package/dist/social/resolvers.d.ts +25 -0
  166. package/dist/social/resolvers.d.ts.map +1 -0
  167. package/dist/social/sdl.d.ts +13 -0
  168. package/dist/social/sdl.d.ts.map +1 -0
  169. package/dist/social/shape.d.ts +11 -0
  170. package/dist/social/shape.d.ts.map +1 -0
  171. package/dist/social/types.d.ts +160 -0
  172. package/dist/social/types.d.ts.map +1 -0
  173. package/dist/surface/api.d.ts +16 -0
  174. package/dist/surface/api.d.ts.map +1 -0
  175. package/dist/surface/request.d.ts +10 -0
  176. package/dist/surface/request.d.ts.map +1 -0
  177. package/dist/surface/signed-in.d.ts +30 -0
  178. package/dist/surface/signed-in.d.ts.map +1 -0
  179. package/dist/types.d.ts +117 -0
  180. package/dist/types.d.ts.map +1 -0
  181. package/dist/wiring.d.ts +56 -0
  182. package/dist/wiring.d.ts.map +1 -0
  183. package/docs/README.md +26 -0
  184. package/docs/guide/api-keys.md +365 -0
  185. package/docs/guide/avatars.md +129 -0
  186. package/docs/guide/context.md +371 -0
  187. package/docs/guide/directives.md +371 -0
  188. package/docs/guide/errors.md +318 -0
  189. package/docs/guide/federation.md +71 -0
  190. package/docs/guide/invitations.md +269 -0
  191. package/docs/guide/passkeys.md +207 -0
  192. package/docs/guide/second-factor.md +238 -0
  193. package/docs/guide/social.md +190 -0
  194. package/docs/guide/step-up.md +208 -0
  195. package/docs/guide/subscriptions.md +255 -0
  196. package/docs/guide/telemetry.md +45 -0
  197. package/docs/roadmap.md +124 -0
  198. package/docs/troubleshooting.md +1265 -0
  199. package/graphql/janus-api-keys.graphqls +237 -0
  200. package/graphql/janus-avatar.graphqls +19 -0
  201. package/graphql/janus-invitations.graphqls +280 -0
  202. package/graphql/janus-passkey-sign-in.graphqls +40 -0
  203. package/graphql/janus-passkeys.graphqls +134 -0
  204. package/graphql/janus-second-factor.graphqls +199 -0
  205. package/graphql/janus-social.graphqls +155 -0
  206. package/graphql/janus.graphqls +44 -0
  207. package/package.json +80 -5
@@ -0,0 +1,365 @@
1
+ # API keys
2
+
3
+ This page is for letting signed-in users create, list and revoke personal API
4
+ keys from a GraphQL API, optionally bound to an object such as a workspace: the
5
+ schema, the wiring, the lifetimes, who may do what, the secret, the step-up,
6
+ paging, the limits and the errors. It is opt-in: nothing here is declared by
7
+ `janusTypeDefs`, and a server without API keys imports none of it.
8
+
9
+ What a key is, how a request is signed by one, its prefix, `maxActive`,
10
+ `freshWithin` and how binding works are
11
+ [`@softistx/janus`'s API keys](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/README.md).
12
+ This package puts `auth.apiKeys.create`, `list`, `listBound` and `revoke` in the
13
+ schema. Binding keys needs `@softistx/janus` with bound API keys
14
+ (`apiKeys.listBound`) and a store that supports it.
15
+
16
+ ## The schema
17
+
18
+ ```ts
19
+ import {
20
+ apiKeysResolvers,
21
+ apiKeysTypeDefs,
22
+ can,
23
+ type JanusContext,
24
+ janusMaskError,
25
+ janusTypeDefs,
26
+ useJanus,
27
+ } from '@softistx/janus-graphql';
28
+ import { createSchema, createYoga, type YogaInitialContext } from 'graphql-yoga';
29
+
30
+ // The context the hooks read: each hook is a method, so `ctx` takes your type.
31
+ type Context = YogaInitialContext & JanusContext<typeof auth, typeof access>;
32
+
33
+ const typeDefs = /* GraphQL */ `
34
+ type Query { hello: String! }
35
+ type Mutation { noop: Boolean }
36
+ `;
37
+
38
+ const schema = createSchema({
39
+ typeDefs: [janusTypeDefs, apiKeysTypeDefs, typeDefs],
40
+ resolvers: {
41
+ ...apiKeysResolvers({
42
+ auth, // janus({ …, apiKeys: { store, prefix, lifetimes: ['30d', '90d', '365d'], maxActive } })
43
+ lifetimes: { days: [30, 90, 365], default: 90 },
44
+ bound: (asked) => (asked === null ? null : { type: 'workspace', id: asked }),
45
+ authorize: {
46
+ create: ({ bound }, ctx: Context) => bound !== null && can(ctx, 'member', bound),
47
+ list: ({ bound, every }, ctx: Context) =>
48
+ bound !== null && can(ctx, every ? 'owner' : 'member', bound),
49
+ revoke: ({ bound, own }, ctx: Context) =>
50
+ own === true || (bound !== null && can(ctx, 'owner', bound)),
51
+ },
52
+ }),
53
+ },
54
+ });
55
+
56
+ createYoga({ schema, plugins: [useJanus({ auth, access })], maskedErrors: { maskError: janusMaskError() } });
57
+ ```
58
+
59
+ `apiKeysTypeDefs` `extend`s your `Query` and `Mutation` and needs
60
+ `janusTypeDefs` (the three directives). The same text ships as
61
+ `graphql/janus-api-keys.graphqls`. `apiKeysResolvers()` answers a map with
62
+ `Query` and `Mutation` keys: spread it into your resolvers, or merge it
63
+ (`mergeResolvers`) when you declare your own `Query`. Timestamps are ISO-8601 `String`s.
64
+
65
+ | Field | Who | What |
66
+ | --- | --- | --- |
67
+ | `apiKeys(boundTo?, limit?, after?)` | A signed-in user `authorize.list` lets list | The user's own keys (standing, revoked and expired), oldest first |
68
+ | `boundApiKeys(boundTo?, limit?, after?)` | as above | Every key bound to the object, whoever holds it |
69
+ | `apiKeyLifetimes` | A signed-in user | `{ days, default }`: what `createApiKey` offers |
70
+ | `createApiKey(name, lifetimeDays?, scopes?, boundTo?)` | A signed-in user `authorize.create` lets create | Creates a key and answers its `secret` once |
71
+ | `revokeApiKey(id, boundTo?)` | A signed-in user `authorize.revoke` lets revoke | Revokes a key and answers it |
72
+
73
+ Every field is `@authenticated`. An API key's owner is a signed-in user too
74
+ under `useJanus({ apiKey: true })`, except to create a key (see
75
+ [the step-up](#the-step-up-and-the-e-mail)).
76
+
77
+ ```graphql
78
+ mutation {
79
+ createApiKey(name: "CI", lifetimeDays: 90, scopes: ["deploy:read"], boundTo: "acme") {
80
+ secret
81
+ apiKey { id prefix status expiresAt bound { type id } }
82
+ }
83
+ }
84
+ ```
85
+
86
+ ## Options
87
+
88
+ | Option | Type | Default | Effect |
89
+ | --- | --- | --- | --- |
90
+ | `auth` | what `janus()` answered | required | Its instance needs `apiKeys` |
91
+ | `lifetimes` | `ApiKeyLifetimes` | required | The lifetimes `createApiKey` offers, in days, and the default |
92
+ | `authorize` | `ApiKeysAuthorize` | required | Who may create, list and revoke: `{ create, list, revoke }` |
93
+ | `bound` | `(asked, ctx) => ApiKeyBound \| null` | absent | The object a call is about; absent, keys are never bound |
94
+
95
+ ```ts
96
+ import type {
97
+ ApiKeyCreateSubject,
98
+ ApiKeyLifetimes,
99
+ ApiKeyListSubject,
100
+ ApiKeyRevokeSubject,
101
+ ApiKeySubjectBase,
102
+ ApiKeysAuth,
103
+ ApiKeysAuthorize,
104
+ ApiKeysResolvers,
105
+ ApiKeysResolversOptions,
106
+ } from '@softistx/janus-graphql';
107
+ ```
108
+
109
+ `ApiKeysResolversOptions<A extends ApiKeysAuth>` is the options, `ApiKeysAuth`
110
+ the part of the `janus()` instance these resolvers read (`apiKeys.create`,
111
+ `list`, `listBound`, `revoke`), and `ApiKeysResolvers` the map.
112
+
113
+ ## Lifetimes
114
+
115
+ `lifetimes.days` are the choices, in whole days, and `lifetimes.default` the one
116
+ `createApiKey` takes when `lifetimeDays` is absent. Each day count must be one of
117
+ the lifetimes `janus({ apiKeys: { lifetimes } })` configures (`'30d'` for `30`),
118
+ else the core refuses the key with `API_KEY_INVALID`.
119
+
120
+ ```ts
121
+ export interface ApiKeyLifetimes {
122
+ readonly days: readonly [number, ...number[]];
123
+ readonly default: number;
124
+ }
125
+ ```
126
+
127
+ ```graphql
128
+ query { apiKeyLifetimes { days default } } # { days: [30, 90, 365], default: 90 }
129
+ mutation { createApiKey(name: "CI") { apiKey { expiresAt } secret } } # 90 days
130
+ mutation { createApiKey(name: "CI", lifetimeDays: 7) { secret } } # BAD_USER_INPUT, field: lifetimeDays
131
+ ```
132
+
133
+ A `lifetimeDays` outside `days` is `BAD_USER_INPUT`
134
+ (`lifetimeDays must be one of 30, 90, 365`, `extensions.field: 'lifetimeDays'`),
135
+ checked before `authorize` is asked.
136
+
137
+ ## Who may do what: `authorize`
138
+
139
+ The core authorises nobody, so `authorize` is required, with its three hooks,
140
+ and is the only guard. A hook answers `true` to let the call through; `false`
141
+ answers `NOT_FOUND`, so an object's existence is not revealed; a thrown
142
+ `GraphQLError` is answered as it is (a step-up from `requireFresh()`, or
143
+ `denial('FORBIDDEN')` for a scope beyond the caller's role).
144
+
145
+ ```ts
146
+ export interface ApiKeysAuthorize {
147
+ readonly create: (subject: ApiKeyCreateSubject, ctx: Context) => boolean | Promise<boolean>;
148
+ readonly list: (subject: ApiKeyListSubject, ctx: Context) => boolean | Promise<boolean>;
149
+ readonly revoke: (subject: ApiKeyRevokeSubject, ctx: Context) => boolean | Promise<boolean>;
150
+ }
151
+ ```
152
+
153
+ Every subject carries `user` (the signed-in user, an API key's owner included)
154
+ and `bound` (the object `bound(...)` answered, or `null`). Then:
155
+
156
+ | Hook | Extra fields | Holds |
157
+ | --- | --- | --- |
158
+ | `create` | `input` | `{ name, lifetimeDays, scopes }`: the lifetime asked for or the default, and `scopes` as asked, `null` for an unscoped key |
159
+ | `list` | `every`, `page` | `every` is `false` for `apiKeys`, `true` for `boundApiKeys`; `page` is the `limit` and `after` the query gave (only those present) |
160
+ | `revoke` | `key?`, `own?` | The stored key, read before `authorize` runs, and whether it is the user's own; both absent when the id names no key the call may reach |
161
+
162
+ Refuse the scopes the caller may not grant in `create`:
163
+
164
+ ```ts
165
+ authorize: {
166
+ create: async ({ bound, input }, ctx: Context) => {
167
+ if (bound === null || !(await can(ctx, 'member', bound))) return false;
168
+ if (input.scopes?.some((scope) => scope.startsWith('admin:'))) {
169
+ throw denial('FORBIDDEN'); // a thrown GraphQLError is answered as it is
170
+ }
171
+ return true;
172
+ },
173
+ // …
174
+ },
175
+ ```
176
+
177
+ (`denial` is exported from `@softistx/janus-graphql`.)
178
+
179
+ `false` is `NOT_FOUND` for all three. For `revoke`, an id that names no key the
180
+ call may reach is also `NOT_FOUND`, the same answer a refusal gives. The hook is
181
+ still asked, on the user and `bound` and without a `key`, so a known and an
182
+ unknown id take the same path. Its answer is ignored and so is any error it
183
+ throws except a `GraphQLError` (a step-up, say), which is answered as it is. A
184
+ hook that reads `subject.key` need not guard against this.
185
+
186
+ Type a standalone guard with the exported `ApiKeyCreateSubject`,
187
+ `ApiKeyListSubject` and `ApiKeyRevokeSubject`.
188
+
189
+ ## Binding keys to an object: `bound`
190
+
191
+ An application that gives each key one object to act in (a workspace, an
192
+ account) passes `bound(boundTo, ctx)`. `boundTo` is the field's `boundTo`
193
+ argument, or `null` when absent, and the context may name the object instead
194
+ (a header, the route). Answer `{ type, id }`, or `null` for no object.
195
+
196
+ ```ts
197
+ bound: (asked, ctx: Context) => {
198
+ const id = asked ?? ctx.request?.headers.get('x-workspace') ?? null;
199
+ return id === null ? null : { type: 'workspace', id };
200
+ },
201
+ ```
202
+
203
+ - An answer of `null` with no `boundTo` asked: the call is about the user's
204
+ **unbound** keys, and `subject.bound` is `null`.
205
+ - A `boundTo` that is asked and answered `null` is `NOT_FOUND`.
206
+ - Without a `bound` hook, keys are never bound, and any `boundTo` is
207
+ `NOT_FOUND`.
208
+ - A `GraphQLError` thrown by the hook is answered as it is.
209
+
210
+ `boundTo` is 1 to 200 characters, else `BAD_USER_INPUT` (`field: 'boundTo'`).
211
+
212
+ ## Listing
213
+
214
+ `apiKeys` is the user's own keys, standing, revoked and expired, oldest first. When
215
+ the application binds keys, only those bound to the call's object (the unbound
216
+ ones when the call names none). `boundApiKeys` is every key bound to the
217
+ object, whoever holds it: the owner's view. It needs an object, so a call
218
+ without one is `NOT_FOUND`, and `authorize.list` is asked with `every: true`.
219
+
220
+ ```graphql
221
+ query {
222
+ apiKeys(boundTo: "acme", limit: 20) {
223
+ items { id name prefix status scopes createdAt expiresAt lastUsedAt }
224
+ nextCursor
225
+ }
226
+ boundApiKeys(boundTo: "acme") { items { id userId name status } nextCursor }
227
+ }
228
+ ```
229
+
230
+ `limit` is a positive integer, 20 by default and at most 100 (a larger value is
231
+ read as 100); `after` is the previous page's `nextCursor`. Pages are oldest
232
+ first. `nextCursor` is `null` on the last page. A list of the user's keys
233
+ bound to an object is one call of the core, `apiKeys.list(user, { bound })`:
234
+ a store with `listUserBoundApiKeys` (the Mongo, Drizzle and memory stores)
235
+ answers it in one read, and any other store has the core read the user's keys
236
+ 100 at a time, revoked and expired included, until the page fills. Each
237
+ `revokeApiKey` reads the key once before the revoke and once after
238
+ (`apiKeys.get`). A `limit` that is not a
239
+ positive integer is `BAD_USER_INPUT`; a malformed `after` is `INVALID_CURSOR`.
240
+
241
+ `JanusApiKey.status` is `ACTIVE`, `REVOKED` or `EXPIRED`, read at the request's
242
+ time (`useJanus({ clock })`): revoked wins over expired. `expiresAt` is when the
243
+ key stops working; `lastUsedAt` is `null` until the key is first used, and moves
244
+ at most once per throttle window; `revokedAt` is `null` while the key stands.
245
+ `prefix` is the start of the token, enough to recognise the key and not to use it.
246
+
247
+ ## Creating a key: the secret once
248
+
249
+ `createApiKey` answers `{ apiKey, secret }`. The `secret` is the whole token,
250
+ answered **once** and never stored: a lost secret is a new key. The response is
251
+ `Cache-Control: no-store` (through `useJanus()`'s `onResponse`, so over HTTP
252
+ through Yoga), so no cache keeps it.
253
+
254
+ ```ts
255
+ const response = await fetch('https://api.example.test/graphql', {
256
+ method: 'POST',
257
+ headers: { 'content-type': 'application/json', cookie: session },
258
+ body: JSON.stringify({
259
+ query: 'mutation ($b: ID) { createApiKey(name: "CI", boundTo: $b) { secret apiKey { id prefix } } }',
260
+ variables: { b: 'acme' },
261
+ }),
262
+ });
263
+ // response.headers.get('cache-control') === 'no-store'
264
+ ```
265
+
266
+ | Argument | Type | Default | Effect |
267
+ | --- | --- | --- | --- |
268
+ | `name` | `String!` | required | The label, 1 to 100 characters once trimmed |
269
+ | `lifetimeDays` | `Int` | `lifetimes.default` | One of `lifetimes.days` |
270
+ | `scopes` | `[String!]` | `null` | What the key may do (`mcp:read`); absent, whatever its user may. Janus never enforces them: the application does, where it serves the key's requests |
271
+ | `boundTo` | `ID` | none | The object the key is bound to, through `bound` |
272
+
273
+ ### The step-up and the e-mail
274
+
275
+ `createApiKey` is the core's `apiKeys.create`, so its rules are the core's:
276
+
277
+ - **A recent proof.** `STEP_UP_REQUIRED`, 403, unless the session proved who it
278
+ is within `apiKeys.freshWithin`: sign in again or confirm a step-up, then send
279
+ the request again (see [the step-up guide](step-up.md)).
280
+ - **Never by a key.** A request signed by an API key is always
281
+ `STEP_UP_REQUIRED` on `createApiKey`: a key never creates a key.
282
+ - **A verified e-mail.** A user whose address was never verified is refused with
283
+ `EMAIL_UNVERIFIED`, 403, on a type that holds an e-mail. Nothing is written.
284
+ - **A ceiling.** A user holding `maxActive` standing keys is refused with
285
+ `API_KEY_LIMIT`, 409, `extensions.maxActive`.
286
+
287
+ ## Revoking a key
288
+
289
+ `revokeApiKey(id, boundTo?)` revokes the signed-in user's own key, or, as
290
+ `authorize.revoke` allows, one bound to the call's object that belongs to
291
+ somebody else (`own` is `false`: an owner removing a leaked key). It answers the
292
+ key as stored after. Revoking a revoked key is not an error.
293
+
294
+ ```graphql
295
+ mutation { revokeApiKey(id: "…", boundTo: "acme") { id status revokedAt } }
296
+ ```
297
+
298
+ ```ts
299
+ revoke: ({ bound, key, own }, ctx: Context) =>
300
+ own === true || (bound !== null && key?.bound?.id === bound.id && can(ctx, 'owner', bound)),
301
+ ```
302
+
303
+ An id that names neither is `NOT_FOUND` whatever `authorize` answers (see
304
+ [above](#who-may-do-what-authorize)).
305
+
306
+ ## Limits
307
+
308
+ The arguments are checked before `authorize` or a store is asked, and refused as
309
+ `BAD_USER_INPUT`, 400, with the argument in `extensions.field`. They mirror
310
+ `@softistx/janus`'s own bounds.
311
+
312
+ | Argument | Maximum | `field` |
313
+ | --- | --- | --- |
314
+ | `name` | 100 characters, once trimmed | `name` |
315
+ | `scopes` | 32 scopes | `scopes` |
316
+ | each scope | 100 characters | `scopes` |
317
+ | `boundTo` | 1 to 200 characters | `boundTo` |
318
+ | `lifetimeDays` | one of `lifetimes.days` | `lifetimeDays` |
319
+
320
+ The package holds them as `API_KEY_LIMITS`
321
+ (`{ name: 100, scopes: 32, scope: 100, boundTo: 200 }`); it is not exported, so
322
+ a form repeats the numbers.
323
+
324
+ ## Errors
325
+
326
+ | Code | Status | When |
327
+ | --- | --- | --- |
328
+ | `BAD_USER_INPUT` | 400 | A value over its maximum, a `lifetimeDays` outside `lifetimes.days`, an empty `boundTo`, or a `limit` that is not a positive integer; `extensions.field` names it |
329
+ | `NOT_FOUND` | 404 | An `authorize` hook answered `false`; a `boundTo` with no `bound` hook, or one the hook answers `null` for; `boundApiKeys` with no object; a `revokeApiKey` id that names no key the call may reach |
330
+ | `FORBIDDEN` | 403 | A hook threw `denial('FORBIDDEN')`, say for a scope beyond the caller's role |
331
+ | `UNAUTHENTICATED` | 401 | A guarded field with no signed-in user |
332
+ | `STEP_UP_REQUIRED` | 403 | `createApiKey` from a session older than `apiKeys.freshWithin`, and always from a request signed by a key |
333
+ | `EMAIL_UNVERIFIED` | 403 | `createApiKey` for an address never verified, on a type that holds an e-mail |
334
+ | `API_KEY_INVALID` | 400 | A name or scopes the core cannot keep, or a lifetime `lifetimes.days` offers but `janus({ apiKeys: { lifetimes } })` does not configure (then `extensions.field: "lifetimeDays"`); `extensions.field` names the argument |
335
+ | `USER_INACTIVE` | 403 | `createApiKey` for a deactivated user (`active: false` in the store) |
336
+ | `API_KEY_LIMIT` | 409 | The user holds the most standing keys; `extensions.maxActive` |
337
+ | `INVALID_CURSOR` | 400 | An `after` that is not a cursor `apiKeys` or `boundApiKeys` issued |
338
+
339
+ The core's refusals are rethrown as their `GraphQLError`, so `janusMaskError()`
340
+ answers the code and status (see [errors](errors.md)).
341
+
342
+ ### Refused at wiring
343
+
344
+ `apiKeysResolvers()` throws a `TypeError` when it is called, before the server
345
+ starts:
346
+
347
+ | Message | Cause |
348
+ | --- | --- |
349
+ | `apiKeysResolvers(): auth has no apiKeys — give janus() \`apiKeys\`` | `janus()` was not given `apiKeys`, or `auth` is not what `janus()` answered |
350
+ | `apiKeysResolvers(): \`authorize\` needs \`create\`, \`list\` and \`revoke\` — the core authorises nobody, so say who may manage keys` | A hook is missing |
351
+ | `apiKeysResolvers(): \`bound\` must be a function of the asked id and the context` | `bound` is given and is not a function |
352
+ | `apiKeysResolvers(): lifetimes must list at least one lifetime in days — for example { days: [30, 90, 365], default: 90 }` | `lifetimes` absent or `days` empty |
353
+ | `apiKeysResolvers(): lifetimes.days must be positive whole numbers of days` | A day count is zero, negative or fractional |
354
+ | `apiKeysResolvers(): lifetimes.default must be one of lifetimes.days` | The default is not a choice |
355
+
356
+ See [Troubleshooting](../troubleshooting.md) for the fix of each.
357
+
358
+ ## Traps
359
+
360
+ - **`authorize` is the only guard.** A signed-in user with an `authorize` that
361
+ answers `true` can create keys; the core authorises nobody.
362
+ - **The secret is answered once.** Show it to the user at once; the server
363
+ cannot recover it.
364
+ - **`scopes` are not enforced here.** They are stored and answered; the
365
+ application checks them where it serves a key's requests.
@@ -0,0 +1,129 @@
1
+ # Account avatars
2
+
3
+ This page is for putting an account's avatar in your schema: `JanusAvatar`,
4
+ the parent a field returns, and the `url(size:)` that points at **your own
5
+ authenticated route**. It is opt-in: nothing here is declared by `janusTypeDefs`,
6
+ and a server that wants no avatars imports none of it.
7
+
8
+ `@softistx/janus` keeps only the avatar's id — `user.avatar`, `{ id, updatedAt } |
9
+ null` — and your application keeps the bytes. This package does not serve
10
+ them: it builds the URL of the route that does. That route, the upload and
11
+ the privacy rule are in [`@softistx/janus`'s avatars
12
+ guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/avatars.md).
13
+
14
+ ## The schema
15
+
16
+ ```ts
17
+ import {
18
+ avatarResolvers,
19
+ janusAvatarTypeDefs,
20
+ janusTypeDefs,
21
+ requireUser,
22
+ toJanusAvatar,
23
+ } from '@softistx/janus-graphql';
24
+ import { createSchema } from 'graphql-yoga';
25
+
26
+ const typeDefs = /* GraphQL */ `
27
+ type Viewer {
28
+ id: ID!
29
+ name: String!
30
+ avatar: JanusAvatar @permission(name: "viewAvatar", type: "user", id: "parent.id")
31
+ }
32
+ type Query {
33
+ viewer: Viewer @authenticated
34
+ }
35
+ `;
36
+
37
+ export const schema = createSchema({
38
+ typeDefs: [janusTypeDefs, janusAvatarTypeDefs, typeDefs],
39
+ resolvers: {
40
+ ...avatarResolvers({
41
+ // where the app's own route lives: it checks the session and the access rule
42
+ url: ({ userId, id }, size) => `/avatars/${userId}/${size}?v=${encodeURIComponent(id)}`,
43
+ }),
44
+ Query: { viewer: (_, __, ctx) => requireUser(ctx) },
45
+ Viewer: { avatar: (user) => toJanusAvatar(user) },
46
+ },
47
+ });
48
+ ```
49
+
50
+ `janusAvatarTypeDefs` ships twice, like `janusTypeDefs`: a string, and
51
+ `graphql/janus-avatar.graphqls` in the package, held identical by a spec.
52
+
53
+ ```graphql
54
+ type JanusAvatar {
55
+ id: ID!
56
+ updatedAt: String!
57
+ url(size: Int!): String!
58
+ }
59
+ ```
60
+
61
+ - **`id`** is the id your application stored the image under — new with every
62
+ upload.
63
+ - **`updatedAt`** is an ISO-8601 string, for example
64
+ `2026-10-24T08:30:00.000Z`. It is a `String`, not a `DateTime`, so the
65
+ package needs no scalar and cannot collide with the one your schema already
66
+ declares; parse it on the client.
67
+ - **`url(size:)`** is what your `url` function answers.
68
+
69
+ Put `avatar: JanusAvatar` on the types you own — `Viewer`, `Member` — and
70
+ return `toJanusAvatar(user)` from the field: `null` for a user with no
71
+ avatar, else the parent `JanusAvatar`'s resolvers read.
72
+
73
+ ## The `url` function
74
+
75
+ `url(avatar, size)` receives the `AvatarParent` — `{ userId, id, updatedAt }`:
76
+ the account, its current avatar id and when it was set; a route needs
77
+ at least the first two — and the size. Answer the path of **a route of yours** and put the
78
+ id in it (`?v=${encodeURIComponent(id)}`; ids are the application's own
79
+ strings, so encode them): a new upload has a new id, so the browser's cache fetches
80
+ the new image and keeps the old one for the old URL.
81
+
82
+ `size` reaches `url` as a positive integer. GraphQL itself refuses a value
83
+ that is not an `Int`; a `size` of `0` or below is refused `BAD_USER_INPUT`,
84
+ status 400, by the resolver. Which positive sizes you store is
85
+ your route's to decide — it answers 404 for the others.
86
+
87
+ ## Who may see an avatar
88
+
89
+ The field is as open as you leave it. Guard it as any other:
90
+
91
+ ```graphql
92
+ avatar: JanusAvatar @permission(name: "viewAvatar", type: "user", id: "parent.id")
93
+ ```
94
+
95
+ `@permission` with `id: "parent.id"` asks `access.can` about the parent itself,
96
+ so no loader is needed. That is right only when the field's parent object is
97
+ the janus user: on a `Member` type whose parent is a membership row,
98
+ `parent.id` is the membership's, not the account's — name the account's id
99
+ field or guard in the resolver. A loader is required only for an `args.*` id, or a
100
+ `parent.<field>` other than `id`, on a type whose `fromField` reads the
101
+ object. A denied field is an error (`NOT_FOUND`). To answer `null` instead, check in the
102
+ resolver:
103
+
104
+ ```ts
105
+ Viewer: {
106
+ avatar: async (user, _args, ctx) =>
107
+ (await can(ctx, 'viewAvatar', user)) ? toJanusAvatar(user) : null,
108
+ },
109
+ ```
110
+
111
+ **The field decides who learns the URL; the route decides who gets the
112
+ bytes.** Check the session and the rule in the route as well — a URL leaks
113
+ through a log, a screenshot or a pasted link, and a route that serves whoever
114
+ asks makes the URL a public one.
115
+
116
+ ## Traps
117
+
118
+ - **The URL must point at a route that checks the session and the access
119
+ rule**, never a public or signed bucket URL — the reason is in
120
+ [`@softistx/janus`'s avatars guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/avatars.md).
121
+ - **`toJanusAvatar` and `avatarResolvers` check nothing.** Guard the field.
122
+ - **The size is not capped here.** `url(size: 100000)` is a string like any
123
+ other; your route refuses the sizes it does not store.
124
+
125
+ ## See also
126
+
127
+ - [`@softistx/janus`'s avatars guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/avatars.md) — the upload and proxy routes, and the privacy recipe
128
+ - [Directives](directives.md) — `@permission`, its ids and its loaders
129
+ - [Troubleshooting](../troubleshooting.md#bad_user_input-400-size-must-be-a-positive-integer) — the `size must be a positive integer` error