@softistx/janus-graphql 0.0.0-stage → 0.30.2
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.
- package/LICENSE +21 -0
- package/README.md +716 -2
- package/dist/api-keys/index.d.ts +11 -0
- package/dist/api-keys/index.d.ts.map +1 -0
- package/dist/api-keys/resolvers/deps.d.ts +39 -0
- package/dist/api-keys/resolvers/deps.d.ts.map +1 -0
- package/dist/api-keys/resolvers/index.d.ts +39 -0
- package/dist/api-keys/resolvers/index.d.ts.map +1 -0
- package/dist/api-keys/resolvers/list.d.ts +16 -0
- package/dist/api-keys/resolvers/list.d.ts.map +1 -0
- package/dist/api-keys/resolvers/manage.d.ts +17 -0
- package/dist/api-keys/resolvers/manage.d.ts.map +1 -0
- package/dist/api-keys/sdl.d.ts +14 -0
- package/dist/api-keys/sdl.d.ts.map +1 -0
- package/dist/api-keys/shape.d.ts +38 -0
- package/dist/api-keys/shape.d.ts.map +1 -0
- package/dist/api-keys/types.d.ts +149 -0
- package/dist/api-keys/types.d.ts.map +1 -0
- package/dist/avatar/index.d.ts +32 -0
- package/dist/avatar/index.d.ts.map +1 -0
- package/dist/avatar/resolvers.d.ts +41 -0
- package/dist/avatar/resolvers.d.ts.map +1 -0
- package/dist/avatar/sdl.d.ts +16 -0
- package/dist/avatar/sdl.d.ts.map +1 -0
- package/dist/bad-input.d.ts +17 -0
- package/dist/bad-input.d.ts.map +1 -0
- package/dist/connection/connection.d.ts +36 -0
- package/dist/connection/connection.d.ts.map +1 -0
- package/dist/connection/credential.d.ts +34 -0
- package/dist/connection/credential.d.ts.map +1 -0
- package/dist/connection/types.d.ts +61 -0
- package/dist/connection/types.d.ts.map +1 -0
- package/dist/context/create.d.ts +32 -0
- package/dist/context/create.d.ts.map +1 -0
- package/dist/context/index.d.ts +9 -0
- package/dist/context/index.d.ts.map +1 -0
- package/dist/context/registry.d.ts +72 -0
- package/dist/context/registry.d.ts.map +1 -0
- package/dist/context/resolve.d.ts +20 -0
- package/dist/context/resolve.d.ts.map +1 -0
- package/dist/device.d.ts +28 -0
- package/dist/device.d.ts.map +1 -0
- package/dist/directives/apply.d.ts +51 -0
- package/dist/directives/apply.d.ts.map +1 -0
- package/dist/directives/guard.d.ts +22 -0
- package/dist/directives/guard.d.ts.map +1 -0
- package/dist/directives/permission/enforce.d.ts +24 -0
- package/dist/directives/permission/enforce.d.ts.map +1 -0
- package/dist/directives/permission/model.d.ts +35 -0
- package/dist/directives/permission/model.d.ts.map +1 -0
- package/dist/directives/permission/path.d.ts +31 -0
- package/dist/directives/permission/path.d.ts.map +1 -0
- package/dist/directives/permission/validate.d.ts +42 -0
- package/dist/directives/permission/validate.d.ts.map +1 -0
- package/dist/directives/read.d.ts +43 -0
- package/dist/directives/read.d.ts.map +1 -0
- package/dist/directives/validate.d.ts +39 -0
- package/dist/directives/validate.d.ts.map +1 -0
- package/dist/directives/words.d.ts +7 -0
- package/dist/directives/words.d.ts.map +1 -0
- package/dist/errors/denial.d.ts +6 -0
- package/dist/errors/denial.d.ts.map +1 -0
- package/dist/errors/index.d.ts +12 -0
- package/dist/errors/index.d.ts.map +1 -0
- package/dist/errors/janus-error.d.ts +20 -0
- package/dist/errors/janus-error.d.ts.map +1 -0
- package/dist/errors/mask.d.ts +69 -0
- package/dist/errors/mask.d.ts.map +1 -0
- package/dist/fresh.d.ts +44 -0
- package/dist/fresh.d.ts.map +1 -0
- package/dist/helpers.d.ts +56 -0
- package/dist/helpers.d.ts.map +1 -0
- package/dist/index.d.ts +86 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3393 -0
- package/dist/index.js.map +75 -0
- package/dist/invitations/index.d.ts +12 -0
- package/dist/invitations/index.d.ts.map +1 -0
- package/dist/invitations/resolvers/anonymous.d.ts +11 -0
- package/dist/invitations/resolvers/anonymous.d.ts.map +1 -0
- package/dist/invitations/resolvers/deps.d.ts +38 -0
- package/dist/invitations/resolvers/deps.d.ts.map +1 -0
- package/dist/invitations/resolvers/index.d.ts +37 -0
- package/dist/invitations/resolvers/index.d.ts.map +1 -0
- package/dist/invitations/resolvers/owner.d.ts +17 -0
- package/dist/invitations/resolvers/owner.d.ts.map +1 -0
- package/dist/invitations/sdl/accept.d.ts +7 -0
- package/dist/invitations/sdl/accept.d.ts.map +1 -0
- package/dist/invitations/sdl/index.d.ts +14 -0
- package/dist/invitations/sdl/index.d.ts.map +1 -0
- package/dist/invitations/sdl/owner.d.ts +8 -0
- package/dist/invitations/sdl/owner.d.ts.map +1 -0
- package/dist/invitations/shape.d.ts +63 -0
- package/dist/invitations/shape.d.ts.map +1 -0
- package/dist/invitations/types/index.d.ts +5 -0
- package/dist/invitations/types/index.d.ts.map +1 -0
- package/dist/invitations/types/options.d.ts +104 -0
- package/dist/invitations/types/options.d.ts.map +1 -0
- package/dist/invitations/types/out.d.ts +136 -0
- package/dist/invitations/types/out.d.ts.map +1 -0
- package/dist/invitations/types/surface.d.ts +18 -0
- package/dist/invitations/types/surface.d.ts.map +1 -0
- package/dist/map-code.d.ts +10 -0
- package/dist/map-code.d.ts.map +1 -0
- package/dist/mask-error.d.ts +18 -0
- package/dist/mask-error.d.ts.map +1 -0
- package/dist/memo.d.ts +16 -0
- package/dist/memo.d.ts.map +1 -0
- package/dist/options.d.ts +17 -0
- package/dist/options.d.ts.map +1 -0
- package/dist/passkeys/deps.d.ts +23 -0
- package/dist/passkeys/deps.d.ts.map +1 -0
- package/dist/passkeys/first-factor.types.d.ts +38 -0
- package/dist/passkeys/first-factor.types.d.ts.map +1 -0
- package/dist/passkeys/index.d.ts +14 -0
- package/dist/passkeys/index.d.ts.map +1 -0
- package/dist/passkeys/resolvers.d.ts +23 -0
- package/dist/passkeys/resolvers.d.ts.map +1 -0
- package/dist/passkeys/sdl.d.ts +14 -0
- package/dist/passkeys/sdl.d.ts.map +1 -0
- package/dist/passkeys/shape.d.ts +14 -0
- package/dist/passkeys/shape.d.ts.map +1 -0
- package/dist/passkeys/sign-in.resolvers.d.ts +19 -0
- package/dist/passkeys/sign-in.resolvers.d.ts.map +1 -0
- package/dist/passkeys/sign-in.sdl.d.ts +16 -0
- package/dist/passkeys/sign-in.sdl.d.ts.map +1 -0
- package/dist/passkeys/types.d.ts +193 -0
- package/dist/passkeys/types.d.ts.map +1 -0
- package/dist/plugin.d.ts +59 -0
- package/dist/plugin.d.ts.map +1 -0
- package/dist/renewal.d.ts +51 -0
- package/dist/renewal.d.ts.map +1 -0
- package/dist/report.d.ts +29 -0
- package/dist/report.d.ts.map +1 -0
- package/dist/sdl.d.ts +12 -0
- package/dist/sdl.d.ts.map +1 -0
- package/dist/second-factor/index.d.ts +12 -0
- package/dist/second-factor/index.d.ts.map +1 -0
- package/dist/second-factor/resolvers/deps.d.ts +39 -0
- package/dist/second-factor/resolvers/deps.d.ts.map +1 -0
- package/dist/second-factor/resolvers/index.d.ts +39 -0
- package/dist/second-factor/resolvers/index.d.ts.map +1 -0
- package/dist/second-factor/resolvers/sign-in.d.ts +10 -0
- package/dist/second-factor/resolvers/sign-in.d.ts.map +1 -0
- package/dist/second-factor/resolvers/status.d.ts +10 -0
- package/dist/second-factor/resolvers/status.d.ts.map +1 -0
- package/dist/second-factor/resolvers/step-up.d.ts +16 -0
- package/dist/second-factor/resolvers/step-up.d.ts.map +1 -0
- package/dist/second-factor/resolvers/writes.d.ts +19 -0
- package/dist/second-factor/resolvers/writes.d.ts.map +1 -0
- package/dist/second-factor/sdl.d.ts +14 -0
- package/dist/second-factor/sdl.d.ts.map +1 -0
- package/dist/second-factor/shape.d.ts +18 -0
- package/dist/second-factor/shape.d.ts.map +1 -0
- package/dist/second-factor/types/index.d.ts +5 -0
- package/dist/second-factor/types/index.d.ts.map +1 -0
- package/dist/second-factor/types/options.d.ts +61 -0
- package/dist/second-factor/types/options.d.ts.map +1 -0
- package/dist/second-factor/types/out.d.ts +84 -0
- package/dist/second-factor/types/out.d.ts.map +1 -0
- package/dist/second-factor/types/surface.d.ts +89 -0
- package/dist/second-factor/types/surface.d.ts.map +1 -0
- package/dist/social/index.d.ts +10 -0
- package/dist/social/index.d.ts.map +1 -0
- package/dist/social/resolvers.d.ts +25 -0
- package/dist/social/resolvers.d.ts.map +1 -0
- package/dist/social/sdl.d.ts +13 -0
- package/dist/social/sdl.d.ts.map +1 -0
- package/dist/social/shape.d.ts +11 -0
- package/dist/social/shape.d.ts.map +1 -0
- package/dist/social/types.d.ts +160 -0
- package/dist/social/types.d.ts.map +1 -0
- package/dist/surface/api.d.ts +16 -0
- package/dist/surface/api.d.ts.map +1 -0
- package/dist/surface/request.d.ts +10 -0
- package/dist/surface/request.d.ts.map +1 -0
- package/dist/surface/signed-in.d.ts +30 -0
- package/dist/surface/signed-in.d.ts.map +1 -0
- package/dist/types.d.ts +117 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/wiring.d.ts +56 -0
- package/dist/wiring.d.ts.map +1 -0
- package/docs/README.md +26 -0
- package/docs/guide/api-keys.md +365 -0
- package/docs/guide/avatars.md +129 -0
- package/docs/guide/context.md +371 -0
- package/docs/guide/directives.md +371 -0
- package/docs/guide/errors.md +318 -0
- package/docs/guide/federation.md +71 -0
- package/docs/guide/invitations.md +269 -0
- package/docs/guide/passkeys.md +207 -0
- package/docs/guide/second-factor.md +238 -0
- package/docs/guide/social.md +190 -0
- package/docs/guide/step-up.md +208 -0
- package/docs/guide/subscriptions.md +255 -0
- package/docs/guide/telemetry.md +45 -0
- package/docs/roadmap.md +124 -0
- package/docs/troubleshooting.md +1265 -0
- package/graphql/janus-api-keys.graphqls +237 -0
- package/graphql/janus-avatar.graphqls +19 -0
- package/graphql/janus-invitations.graphqls +280 -0
- package/graphql/janus-passkey-sign-in.graphqls +40 -0
- package/graphql/janus-passkeys.graphqls +134 -0
- package/graphql/janus-second-factor.graphqls +199 -0
- package/graphql/janus-social.graphqls +155 -0
- package/graphql/janus.graphqls +44 -0
- 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
|