@crombolo/auth 0.65.1 → 0.66.0

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crombolo/auth",
3
- "version": "0.65.1",
3
+ "version": "0.66.0",
4
4
  "description": "Internal to crombolo, with no compatibility promise: use @crombolo/crombolo. OAuth2 authorization server, password hashing, cookies and member tickets for crombolo.",
5
5
  "license": "MIT",
6
6
  "author": "Crombolo",
@@ -28,8 +28,8 @@
28
28
  "access": "public"
29
29
  },
30
30
  "dependencies": {
31
- "@crombolo/core": "0.65.1",
32
- "@crombolo/data": "0.65.1",
31
+ "@crombolo/core": "0.66.0",
32
+ "@crombolo/data": "0.66.0",
33
33
  "jose": "^6.2.12",
34
34
  "uqr": "^0.1.3"
35
35
  }
@@ -0,0 +1,299 @@
1
+ /**
2
+ * Command-line tokens (story 351): a person's own long-lived credential for a
3
+ * script or a CI job, acting as them with their permissions as they are now.
4
+ * Only a token's hash is kept; the token itself is shown once, when it is made.
5
+ * docs/operations.md, "Command-line tokens".
6
+ */
7
+ import { CliTokenPermissions, normaliseUuid } from '@crombolo/core'
8
+ import { type Db, DbDate } from '@crombolo/data'
9
+ import { generateToken, hashToken } from './pkce.ts'
10
+ import { AuthStore, type UserRow } from './store.ts'
11
+
12
+ /** What every token starts with, so secret scanners can recognise one. */
13
+ export const CLI_TOKEN_PREFIX = 'crombolo_pat_'
14
+
15
+ export const DEFAULT_CLI_TOKEN_DAYS = 30
16
+ export const DEFAULT_CLI_TOKEN_MAX_DAYS = 90
17
+ const DAY_MS = 86_400_000
18
+ const HOUR_MS = 3_600_000
19
+
20
+ export const isCliToken = (token: string): boolean => token.startsWith(CLI_TOKEN_PREFIX)
21
+
22
+ export interface CliTokenSettings {
23
+ /** `cliTokens`: off, no token is issued and every one is refused. */
24
+ enabled: boolean
25
+ /** `cliTokenMaxDays`: the longest a token may last. */
26
+ maxDays: number
27
+ }
28
+
29
+ export interface CliToken {
30
+ key: string
31
+ userId: number
32
+ name: string
33
+ createdAt: Date
34
+ expiresAt: Date
35
+ lastUsedAt: Date | null
36
+ revokedAt: Date | null
37
+ revokedBy: string | null
38
+ }
39
+
40
+ export interface CliTokenPerson {
41
+ id: number
42
+ key: string
43
+ name: string
44
+ }
45
+
46
+ export type CliTokenRefusal =
47
+ | 'unknown'
48
+ | 'expired'
49
+ | 'revoked'
50
+ | 'disabled'
51
+ | 'locked'
52
+ | 'removed'
53
+ | 'not-allowed'
54
+ | 'off'
55
+
56
+ /** Why a token was refused, in a sentence each. */
57
+ export const CLI_TOKEN_REFUSALS: Readonly<Record<CliTokenRefusal, string>> = {
58
+ unknown: 'This site does not know that token.',
59
+ expired: 'That token has expired.',
60
+ revoked: 'That token has been revoked.',
61
+ disabled: "That token's person has been disabled.",
62
+ locked: "That token's person is locked out.",
63
+ removed: "That token's person has been removed from the site.",
64
+ 'not-allowed':
65
+ "That token's person is no longer in a group that gives command-line tokens, so it doesn't work for now.",
66
+ off: 'This site does not take command-line tokens.',
67
+ }
68
+
69
+ export type IssueRefusal = 'off' | 'not-allowed' | 'name' | 'name-taken' | 'days'
70
+
71
+ export type Issued =
72
+ | { ok: true; token: string; issued: CliToken }
73
+ | { ok: false; refused: IssueRefusal; message: string }
74
+
75
+ export type ResolvedCliToken =
76
+ | { ok: true; user: UserRow; token: CliToken; firstUse: boolean }
77
+ | { ok: false; reason: CliTokenRefusal; token?: CliToken }
78
+
79
+ const toToken = (row: {
80
+ key: string
81
+ user_id: number
82
+ name: string
83
+ created_at: unknown
84
+ expires_at: unknown
85
+ last_used_at: unknown
86
+ revoked_at: unknown
87
+ revoked_by: string | null
88
+ }): CliToken => ({
89
+ key: normaliseUuid(String(row.key)),
90
+ userId: Number(row.user_id),
91
+ name: String(row.name),
92
+ createdAt: DbDate.fromDb(row.created_at) ?? new Date(0),
93
+ expiresAt: DbDate.fromDb(row.expires_at) ?? new Date(0),
94
+ lastUsedAt: DbDate.fromDb(row.last_used_at) ?? null,
95
+ revokedAt: DbDate.fromDb(row.revoked_at) ?? null,
96
+ revokedBy: row.revoked_by ?? null,
97
+ })
98
+
99
+ const COLUMNS = [
100
+ 'key',
101
+ 'user_id',
102
+ 'name',
103
+ 'created_at',
104
+ 'expires_at',
105
+ 'last_used_at',
106
+ 'revoked_at',
107
+ 'revoked_by',
108
+ ] as const
109
+
110
+ export class CliTokens {
111
+ #db: Db
112
+ #store: AuthStore
113
+ #settings: CliTokenSettings
114
+
115
+ constructor(db: Db, settings: CliTokenSettings) {
116
+ this.#db = db
117
+ this.#store = new AuthStore(db)
118
+ this.#settings = settings
119
+ }
120
+
121
+ get settings(): CliTokenSettings {
122
+ return this.#settings
123
+ }
124
+
125
+ /** A person by key, e-mail or login, for listing or revoking someone's tokens. */
126
+ async person(who: string): Promise<CliTokenPerson | undefined> {
127
+ const wanted = who.trim().toLowerCase()
128
+ const uuid = /^\{?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\}?$/.test(wanted)
129
+ const row = await this.#db.q
130
+ .selectFrom('user_account')
131
+ .select(['id', 'key', 'user_name'])
132
+ .where((eb) =>
133
+ uuid
134
+ ? eb('key', '=', normaliseUuid(wanted))
135
+ : eb.or([
136
+ eb(eb.fn('lower', ['email']), '=', wanted),
137
+ eb(eb.fn('lower', ['login']), '=', wanted),
138
+ ]),
139
+ )
140
+ .executeTakeFirst()
141
+ return (
142
+ row && {
143
+ id: Number(row.id),
144
+ key: normaliseUuid(String(row.key)),
145
+ name: String(row.user_name),
146
+ }
147
+ )
148
+ }
149
+
150
+ /** A token's person, or a stand-in once they have been removed. */
151
+ async ownerOf(token: CliToken): Promise<CliTokenPerson> {
152
+ const row = await this.#db.q
153
+ .selectFrom('user_account')
154
+ .select(['id', 'key', 'user_name'])
155
+ .where('id', '=', token.userId)
156
+ .executeTakeFirst()
157
+ return row
158
+ ? { id: Number(row.id), key: normaliseUuid(String(row.key)), name: String(row.user_name) }
159
+ : { id: token.userId, key: '', name: 'a removed user' }
160
+ }
161
+
162
+ /** Whether the person's groups give them command-line tokens now. */
163
+ async mayCreate(userId: number): Promise<boolean> {
164
+ const authorization = await this.#store.loadAuthorization(userId)
165
+ return authorization.permissions.includes(CliTokenPermissions.Create)
166
+ }
167
+
168
+ /** A new token for the person, returned once: `days` defaults to 30 and is capped by the site. */
169
+ async issue(userId: number, name: string, days?: number, now = new Date()): Promise<Issued> {
170
+ const refuse = (refused: IssueRefusal, message: string): Issued => ({
171
+ ok: false,
172
+ refused,
173
+ message,
174
+ })
175
+ const { enabled, maxDays } = this.#settings
176
+ if (!enabled) return refuse('off', CLI_TOKEN_REFUSALS.off)
177
+ if (!(await this.mayCreate(userId)))
178
+ return refuse(
179
+ 'not-allowed',
180
+ "None of your groups gives you command-line tokens, so you can't create one.",
181
+ )
182
+ const trimmed = name.trim()
183
+ // biome-ignore lint/suspicious/noControlCharactersInRegex: refusing them is the point
184
+ if (trimmed.length === 0 || trimmed.length > 100 || /[\u0000-\u001f]/.test(trimmed))
185
+ return refuse('name', 'Give the token a name of up to 100 characters.')
186
+ const lasting = days ?? Math.min(DEFAULT_CLI_TOKEN_DAYS, maxDays)
187
+ if (!Number.isInteger(lasting) || lasting < 1 || lasting > maxDays)
188
+ return refuse(
189
+ 'days',
190
+ `A token lasts from 1 to ${maxDays} day${maxDays === 1 ? '' : 's'} on this site.`,
191
+ )
192
+ if ((await this.byName(userId, trimmed)) !== undefined)
193
+ return refuse('name-taken', `You already have a token called "${trimmed}".`)
194
+ const token = `${CLI_TOKEN_PREFIX}${generateToken(32)}`
195
+ const issued: CliToken = {
196
+ key: crypto.randomUUID(),
197
+ userId,
198
+ name: trimmed,
199
+ createdAt: now,
200
+ expiresAt: new Date(now.getTime() + lasting * DAY_MS),
201
+ lastUsedAt: null,
202
+ revokedAt: null,
203
+ revokedBy: null,
204
+ }
205
+ await this.#db.q
206
+ .insertInto('cli_token')
207
+ .values({
208
+ key: issued.key,
209
+ user_id: userId,
210
+ name: issued.name,
211
+ token_hash: hashToken(token),
212
+ created_at: DbDate.toDb(issued.createdAt),
213
+ expires_at: DbDate.toDb(issued.expiresAt),
214
+ })
215
+ .execute()
216
+ return { ok: true, token, issued }
217
+ }
218
+
219
+ /** A person's tokens not yet revoked, or everyone's, newest first. */
220
+ async list(userId?: number): Promise<CliToken[]> {
221
+ let query = this.#db.q
222
+ .selectFrom('cli_token')
223
+ .select(COLUMNS)
224
+ .where('revoked_at', 'is', null)
225
+ .orderBy('created_at', 'desc')
226
+ .orderBy('id', 'desc')
227
+ if (userId !== undefined) query = query.where('user_id', '=', userId)
228
+ return (await query.execute()).map(toToken)
229
+ }
230
+
231
+ /** A person's token by its name, among those not revoked. */
232
+ async byName(userId: number, name: string): Promise<CliToken | undefined> {
233
+ const row = await this.#db.q
234
+ .selectFrom('cli_token')
235
+ .select(COLUMNS)
236
+ .where('user_id', '=', userId)
237
+ .where('name', '=', name.trim())
238
+ .where('revoked_at', 'is', null)
239
+ .executeTakeFirst()
240
+ return row && toToken(row)
241
+ }
242
+
243
+ async byKey(key: string): Promise<CliToken | undefined> {
244
+ const row = await this.#db.q
245
+ .selectFrom('cli_token')
246
+ .select(COLUMNS)
247
+ .where('key', '=', normaliseUuid(key))
248
+ .executeTakeFirst()
249
+ return row && toToken(row)
250
+ }
251
+
252
+ /** Revokes a token, by whom; the token as it was, or undefined when there is none to revoke. */
253
+ async revoke(key: string, byUserKey: string, now = new Date()): Promise<CliToken | undefined> {
254
+ const token = await this.byKey(key)
255
+ if (!token || token.revokedAt) return undefined
256
+ await this.#db.q
257
+ .updateTable('cli_token')
258
+ .set({ revoked_at: DbDate.toDb(now), revoked_by: normaliseUuid(byUserKey) })
259
+ .where('key', '=', token.key)
260
+ .execute()
261
+ return token
262
+ }
263
+
264
+ /**
265
+ * The person a token acts as, or why it may not. Its use is noted at most once
266
+ * an hour; `firstUse` says this is the first, for the audit log.
267
+ */
268
+ async resolve(token: string, now = new Date()): Promise<ResolvedCliToken> {
269
+ if (!isCliToken(token)) return { ok: false, reason: 'unknown' }
270
+ if (!this.#settings.enabled) return { ok: false, reason: 'off' }
271
+ const row = await this.#db.q
272
+ .selectFrom('cli_token')
273
+ .select(COLUMNS)
274
+ .where('token_hash', '=', hashToken(token))
275
+ .executeTakeFirst()
276
+ if (!row) return { ok: false, reason: 'unknown' }
277
+ const found = toToken(row)
278
+ const refused = (reason: CliTokenRefusal): ResolvedCliToken => ({
279
+ ok: false,
280
+ reason,
281
+ token: found,
282
+ })
283
+ if (found.revokedAt) return refused('revoked')
284
+ if (found.expiresAt.getTime() <= now.getTime()) return refused('expired')
285
+ const user = await this.#store.findUserById(found.userId)
286
+ if (!user) return refused('removed')
287
+ if (!user.isApproved) return refused('disabled')
288
+ if (user.isLockedOut) return refused('locked')
289
+ if (!(await this.mayCreate(user.id))) return refused('not-allowed')
290
+ const firstUse = found.lastUsedAt === null
291
+ if (firstUse || now.getTime() - (found.lastUsedAt?.getTime() ?? 0) >= HOUR_MS)
292
+ await this.#db.q
293
+ .updateTable('cli_token')
294
+ .set({ last_used_at: DbDate.toDb(now) })
295
+ .where('key', '=', found.key)
296
+ .execute()
297
+ return { ok: true, user, token: found, firstUse }
298
+ }
299
+ }
package/src/index.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  export * from './admin.ts'
2
2
  export * from './antiforgery.ts'
3
+ export * from './cli-tokens.ts'
3
4
  export * from './cookies.ts'
4
5
  export * from './device.ts'
5
6
  export * from './member-session.ts'