@crombolo/auth 0.65.1 → 0.67.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.67.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.67.0",
32
+ "@crombolo/data": "0.67.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/device.ts CHANGED
@@ -15,6 +15,18 @@ import { generateToken, hashToken } from './pkce.ts'
15
15
 
16
16
  /** The client id the CLI signs in as. */
17
17
  export const REMOTE_CLIENT_ID = 'crombolo-cli'
18
+
19
+ /**
20
+ * The client a token exchanged through a provider is issued to (story 364),
21
+ * with the provider's id after the colon: what marks its sessions as a machine's.
22
+ */
23
+ export const EXCHANGE_CLIENT_PREFIX = 'crombolo-exchange:'
24
+
25
+ /** The provider an exchanged token came through, when the client is one. */
26
+ export const exchangeProviderOf = (clientId: string): string | undefined =>
27
+ clientId.startsWith(EXCHANGE_CLIENT_PREFIX)
28
+ ? clientId.slice(EXCHANGE_CLIENT_PREFIX.length)
29
+ : undefined
18
30
  export const DEVICE_CODE_SECONDS = 10 * 60
19
31
  export const DEVICE_POLL_SECONDS = 5
20
32
 
@@ -116,6 +128,44 @@ export class DeviceStore {
116
128
  }
117
129
  }
118
130
 
131
+ /**
132
+ * A device signed in already, with no code to approve: a token exchanged
133
+ * through a provider (story 364), listed and signed out like any other.
134
+ */
135
+ async signedInByExchange(init: {
136
+ clientId: string
137
+ clientName: string
138
+ userId: number
139
+ sessionId: string
140
+ expiresAt: Date
141
+ }): Promise<void> {
142
+ const now = new Date()
143
+ for (let attempt = 0; ; attempt++) {
144
+ try {
145
+ await this.#db.q
146
+ .insertInto('device_authorization')
147
+ .values({
148
+ device_code_hash: hashToken(generateToken()),
149
+ user_code: userCode(),
150
+ client_id: init.clientId,
151
+ client_name: init.clientName,
152
+ scope: '',
153
+ status: 'issued',
154
+ user_id: init.userId,
155
+ session_id: init.sessionId,
156
+ interval_seconds: DEVICE_POLL_SECONDS,
157
+ expires_at: DbDate.toDb(init.expiresAt),
158
+ decided_at: DbDate.toDb(now),
159
+ create_date: DbDate.toDb(now),
160
+ })
161
+ .execute()
162
+ return
163
+ } catch (error) {
164
+ if (attempt >= 4) throw error
165
+ }
166
+ }
167
+ }
168
+
119
169
  async byDeviceCode(deviceCode: string): Promise<DeviceAuthorizationRow | undefined> {
120
170
  const row = await this.#db.q
121
171
  .selectFrom('device_authorization')
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'
package/src/oidc.ts CHANGED
@@ -17,6 +17,8 @@ export interface OidcClaims {
17
17
  name: string
18
18
  /** Where group or role values come from, for mapping onto groups. */
19
19
  groups?: string
20
+ /** What names the person across tokens for other apps of the provider; `sub` when unset. */
21
+ identity?: string
20
22
  }
21
23
 
22
24
  /** One provider, as a preset describes it. */
@@ -41,6 +43,8 @@ export interface OidcIdentity {
41
43
  name: string | undefined
42
44
  /** The values of the provider's groups claim, when it names one. */
43
45
  groups: string[]
46
+ /** The value of the claim that names the person (story 364): `sub` unless the provider says. */
47
+ identity: string | undefined
44
48
  claims: JWTPayload
45
49
  }
46
50
 
@@ -189,6 +193,7 @@ export class OidcClient {
189
193
  emailVerified: verified === true || verified === 'true',
190
194
  name: stringClaim(claims, this.options.claims.name),
191
195
  groups: listClaim(claims, this.options.claims.groups),
196
+ identity: stringClaim(claims, this.options.claims.identity ?? 'sub'),
192
197
  claims,
193
198
  }
194
199
  }
package/src/service.ts CHANGED
@@ -7,6 +7,8 @@ import {
7
7
  DEVICE_CODE_SECONDS,
8
8
  DEVICE_POLL_SECONDS,
9
9
  type DeviceAuthorizationRow,
10
+ EXCHANGE_CLIENT_PREFIX,
11
+ exchangeProviderOf,
10
12
  type SignedInDevice,
11
13
  } from './device.ts'
12
14
  import { hashPassword, isNativeHash, passwordConfigJson, verifyPassword } from './password.ts'
@@ -99,6 +101,8 @@ export interface ViewingAs {
99
101
  export interface ResolvedIdentity {
100
102
  user: UserRow
101
103
  sessionId: string
104
+ /** The provider a token exchanged through it came by (story 364); never set for a browser's session. */
105
+ exchangedThrough?: string
102
106
  allowedSections: Array<SectionAlias | ExtensionSectionAlias>
103
107
  groupKeys: string[]
104
108
  isAdmin: boolean
@@ -394,15 +398,18 @@ export class AuthService {
394
398
  if (!user) return undefined
395
399
  const own = await this.#store.loadAuthorization(user.id)
396
400
  const view = session.view
401
+ const provider = exchangeProviderOf(token.clientId)
402
+ const through = provider ? { exchangedThrough: provider } : {}
397
403
  if (view && view.until.getTime() > now.getTime() && own.isAdmin) {
398
404
  const theirs = await this.#store.loadGroupAuthorization(view.groupKeys)
399
405
  return {
400
406
  ...identityFrom(user, theirs),
401
407
  sessionId: token.sessionId,
402
408
  viewingAs: { groups: groupsOf(theirs), until: view.until },
409
+ ...through,
403
410
  }
404
411
  }
405
- return { ...identityFrom(user, own), sessionId: token.sessionId }
412
+ return { ...identityFrom(user, own), sessionId: token.sessionId, ...through }
406
413
  }
407
414
 
408
415
  /**
@@ -532,6 +539,48 @@ export class AuthService {
532
539
  return { ok: true, grant: await this.#issue(user.id, sessionId, clientId, row.scope), user }
533
540
  }
534
541
 
542
+ /**
543
+ * Signs a user in for a token exchanged through a provider (story 364): the
544
+ * same refusals as any sign-in, then a signed-in device of its own with an
545
+ * access token and no refresh token, so it ends when the token does.
546
+ */
547
+ async signInByExchange(
548
+ login: string,
549
+ provider: { id: string; name: string },
550
+ seconds: number,
551
+ ipAddress?: string,
552
+ ): Promise<
553
+ | { status: 'success'; user: UserRow; accessToken: string; expiresIn: number }
554
+ | { status: 'notAllowed'; reason: 'lockedOut' | 'notApproved' | 'unknown' }
555
+ > {
556
+ const user = await this.#store.findUserByLogin(login)
557
+ if (!user) return { status: 'notAllowed', reason: 'unknown' }
558
+ if (user.isLockedOut) return { status: 'notAllowed', reason: 'lockedOut' }
559
+ if (!user.isApproved) return { status: 'notAllowed', reason: 'notApproved' }
560
+ const sessionId = crypto.randomUUID()
561
+ const clientId = `${EXCHANGE_CLIENT_PREFIX}${provider.id}`
562
+ const expiresAt = new Date(Date.now() + seconds * 1000)
563
+ await this.#store.recordLoginSuccess(user.id, sessionId, ipAddress)
564
+ await this.#store.devices.signedInByExchange({
565
+ clientId,
566
+ clientName: `Signed in through ${provider.name}`,
567
+ userId: user.id,
568
+ sessionId,
569
+ expiresAt,
570
+ })
571
+ const accessToken = generateToken()
572
+ await this.#store.createToken({
573
+ token: accessToken,
574
+ type: 'access',
575
+ userId: user.id,
576
+ sessionId,
577
+ clientId,
578
+ scope: '',
579
+ expiresAt,
580
+ })
581
+ return { status: 'success', user, accessToken, expiresIn: seconds }
582
+ }
583
+
535
584
  /** The devices signed in as this user. */
536
585
  signedInDevices(userId: number): Promise<SignedInDevice[]> {
537
586
  return this.#store.devices.signedIn(userId)