@meith/api 0.31.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meith/api",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,6 +19,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@meith/core": "0.31.0"
+    "@meith/core": "0.32.0"
   }
 }

package/src/index.ts

@@ -44,8 +44,13 @@ export {
 export {
   type ApiTokenRecord,
   type ApiTokenRepository,
+  authenticateFeedToken,
   authenticateToken,
   bearerFrom,
+  FEED_TOKEN_PREFIX,
+  type FeedTokenOutcome,
+  type FeedTokenRecord,
+  type FeedTokenRepository,
   hashTokenSecret,
   hasScope,
   type IssuedToken,
@@ -55,6 +60,7 @@ export {
   parseToken,
   SCOPES,
   type Scope,
+  secretMatches,
   TOKEN_PREFIX,
   type TokenFailure,
   type TokenOutcome,
@@ -64,6 +70,9 @@ export {
   type DeliveryVerdict,
   deliveryHeaders,
   EVENT_HEADER,
+  formatWebhookPayload,
+  generateWebhookSecret,
+  isWebhookFormat,
   isWebhookTopic,
   MAX_ATTEMPTS,
   nextRetryDelaySeconds,
@@ -73,8 +82,12 @@ export {
   TIMESTAMP_HEADER,
   verdictFor,
   verifySignature,
+  WEBHOOK_FORMATS,
+  WEBHOOK_SECRET_PREFIX,
   WEBHOOK_TOPICS,
   type WebhookDelivery,
+  type WebhookFormat,
   type WebhookSubscription,
   type WebhookTopic,
+  webhookEventUrl,
 } from './webhooks'

package/src/tokens.ts

@@ -2,6 +2,8 @@ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
 
 export const TOKEN_PREFIX = 'forum_pat'
 
+export const FEED_TOKEN_PREFIX = 'forum_feed'
+
 const LOOKUP_LENGTH = 8
 const SECRET_BYTES = 32
 
@@ -53,12 +55,20 @@ export function hashTokenSecret(secret: string): string {
   return createHash('sha256').update(secret, 'utf8').digest('hex')
 }
 
-export function issueToken(): IssuedToken {
+const DECOY_HASH = hashTokenSecret('')
+
+export function secretMatches(presentedSecret: string, storedHash: string): boolean {
+  const candidate = Buffer.from(hashTokenSecret(presentedSecret), 'hex')
+  const stored = Buffer.from(storedHash, 'hex')
+  return candidate.length === stored.length && timingSafeEqual(candidate, stored)
+}
+
+export function issueToken(prefix: string = TOKEN_PREFIX): IssuedToken {
   const lookup = randomBytes(LOOKUP_LENGTH).toString('hex').slice(0, LOOKUP_LENGTH)
   const secret = randomBytes(SECRET_BYTES).toString('base64url')
 
   return {
-    token: `${TOKEN_PREFIX}_${lookup}_${secret}`,
+    token: `${prefix}_${lookup}_${secret}`,
     lookup,
     secretHash: hashTokenSecret(secret),
   }
@@ -69,8 +79,8 @@ export interface ParsedToken {
   readonly secret: string
 }
 
-export function parseToken(presented: string): ParsedToken | null {
-  const marker = `${TOKEN_PREFIX}_`
+export function parseToken(presented: string, prefix: string = TOKEN_PREFIX): ParsedToken | null {
+  const marker = `${prefix}_`
   if (!presented.startsWith(marker)) return null
 
   const rest = presented.slice(marker.length)
@@ -101,9 +111,7 @@ export async function authenticateToken(
   const record = await repository.findByLookup(parsed.lookup)
   if (record === null) return { ok: false, reason: 'unknown' }
 
-  const candidate = Buffer.from(hashTokenSecret(parsed.secret), 'hex')
-  const stored = Buffer.from(record.secretHash, 'hex')
-  if (candidate.length !== stored.length || !timingSafeEqual(candidate, stored)) {
+  if (!secretMatches(parsed.secret, record.secretHash)) {
     return { ok: false, reason: 'bad-secret' }
   }
 
@@ -115,6 +123,39 @@ export async function authenticateToken(
   return { ok: true, token: record }
 }
 
+export interface FeedTokenRecord {
+  readonly id: number
+  readonly userId: number
+  readonly lookup: string
+  readonly secretHash: string
+}
+
+export interface FeedTokenRepository {
+  findByLookup(lookup: string): Promise<FeedTokenRecord | null>
+}
+
+export type FeedTokenOutcome =
+  | { readonly ok: true; readonly record: FeedTokenRecord }
+  | { readonly ok: false }
+
+export async function authenticateFeedToken(
+  presented: string,
+  repository: FeedTokenRepository,
+): Promise<FeedTokenOutcome> {
+  const parsed = parseToken(presented, FEED_TOKEN_PREFIX)
+  if (parsed === null) return { ok: false }
+
+  const record = await repository.findByLookup(parsed.lookup)
+  if (record === null) {
+    secretMatches(parsed.secret, DECOY_HASH)
+    return { ok: false }
+  }
+
+  if (!secretMatches(parsed.secret, record.secretHash)) return { ok: false }
+
+  return { ok: true, record }
+}
+
 export function hasScope(token: ApiTokenRecord, scope: Scope): boolean {
   return token.scopes.includes(scope)
 }

package/src/webhooks.ts

@@ -1,4 +1,10 @@
-import { createHmac, timingSafeEqual } from 'node:crypto'
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+
+export const WEBHOOK_SECRET_PREFIX = 'whsec_'
+
+export function generateWebhookSecret(): string {
+  return `${WEBHOOK_SECRET_PREFIX}${randomBytes(24).toString('base64url')}`
+}
 
 export const SIGNATURE_HEADER = 'x-forum-signature'
 export const TIMESTAMP_HEADER = 'x-forum-timestamp'
@@ -94,3 +100,51 @@ export function verdictFor(status: number, attempt: number): DeliveryVerdict {
   if (status === 410) return 'dead'
   return nextRetryDelaySeconds(attempt) === null ? 'dead' : 'retry'
 }
+
+export const WEBHOOK_FORMATS = ['json', 'discord'] as const
+
+export type WebhookFormat = (typeof WEBHOOK_FORMATS)[number]
+
+export function isWebhookFormat(value: string): value is WebhookFormat {
+  return (WEBHOOK_FORMATS as readonly string[]).includes(value)
+}
+
+export function webhookEventUrl(
+  boardUrl: string,
+  topic: WebhookTopic,
+  ids: Readonly<Record<string, unknown>>,
+): string | null {
+  const base = boardUrl.replace(/\/+$/, '')
+  if (base === '') return null
+
+  const threadId = ids.threadId
+  const postId = ids.postId
+
+  if (topic === 'thread.created' && typeof threadId === 'number') {
+    return `${base}/threads/${threadId}`
+  }
+  if (
+    (topic === 'post.created' || topic === 'post.edited' || topic === 'post.deleted') &&
+    typeof threadId === 'number' &&
+    typeof postId === 'number'
+  ) {
+    return `${base}/threads/${threadId}#post-${postId}`
+  }
+  return null
+}
+
+export function formatWebhookPayload(
+  topic: WebhookTopic,
+  ids: Readonly<Record<string, unknown>>,
+  format: WebhookFormat,
+  boardUrl: string,
+): Record<string, unknown> {
+  const url = webhookEventUrl(boardUrl, topic, ids)
+
+  if (format === 'discord') {
+    const base = boardUrl.replace(/\/+$/, '')
+    return { content: url ?? (base === '' ? topic : `${topic} — ${base}`) }
+  }
+
+  return { event: topic, ...ids, ...(url === null ? {} : { url }) }
+}