@pikku/core 0.12.107 → 0.12.111

package/src/services/queue-webhook-service.ts

@@ -1,150 +0,0 @@
-import { getSingletonServices } from '../pikku-state.js'
-import { getDurationInMilliseconds } from '../time-utils.js'
-import { safeFetch } from '../utils/safe-fetch.js'
-import type { JobOptions, QueueService } from '../wirings/queue/queue.types.js'
-import type { Logger } from './logger.js'
-import {
-  DEFAULT_WEBHOOK_RETRIES,
-  DEFAULT_WEBHOOK_SIGNATURE_HEADER,
-  PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME,
-  type SendWebhookInput,
-  type SendWebhookResult,
-  type WebhookJobData,
-  WebhookService,
-} from './webhook-service.js'
-
-const MAX_CAPTURED_RESPONSE_BODY = 2_000
-
-// knowledge: decisions/security/webhook-bodies-are-signed-before-they-are-enqueued.md
-export class QueueWebhookService extends WebhookService {
-  // knowledge: decisions/internals/webhook-service-collaborators-are-constructor-args-not-locator-lookups.md
-  constructor(protected queueService: QueueService) {
-    super()
-  }
-
-  public async send(input: SendWebhookInput): Promise<SendWebhookResult> {
-    const { jobData, options } = await this.prepareDelivery(input)
-    const jobId = await this.queueService.add(
-      PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME,
-      jobData,
-      options
-    )
-    return { jobId }
-  }
-
-  /**
-   * `protected` so a store-backed subclass can persist a delivery row and attach
-   * its `deliveryId` without re-implementing signing or the retry policy.
-   */
-  protected async prepareDelivery(
-    input: SendWebhookInput
-  ): Promise<{ jobData: WebhookJobData; options: JobOptions }> {
-    const services = getSingletonServices()
-    const webhookConfig = services.config?.webhook
-
-    const body = JSON.stringify(input.data)
-    const headers: Record<string, string> = {
-      'Content-Type': 'application/json',
-      ...(input.event ? { 'X-Pikku-Event': input.event } : {}),
-      ...input.headers,
-    }
-
-    let secret = input.secret
-    if (secret === undefined && webhookConfig?.secret) {
-      // Naive read: caching is the secret service's concern, not ours.
-      secret = (await services.secrets.getSecret(webhookConfig.secret)).reveal()
-      if (!secret) {
-        services.logger.error(
-          `Webhook signing secret '${webhookConfig.secret}' (config.webhook.secret) resolved to nothing — outgoing webhooks will be sent UNSIGNED.`
-        )
-      }
-    }
-    if (secret) {
-      const signatureHeader =
-        webhookConfig?.signatureHeader ?? DEFAULT_WEBHOOK_SIGNATURE_HEADER
-      headers[signatureHeader] = this.sign(secret, body)
-    }
-
-    const jobData: WebhookJobData = {
-      url: input.url,
-      ...(input.event ? { event: input.event } : {}),
-      body,
-      headers,
-    }
-
-    return { jobData, options: this.resolveJobOptions(input) }
-  }
-
-  // knowledge: decisions/internals/queue-jobs-always-carry-an-explicit-attempts-count.md
-  private resolveJobOptions(input: SendWebhookInput): JobOptions {
-    const webhookConfig = getSingletonServices().config?.webhook
-    const retries =
-      input.retries ?? webhookConfig?.retries ?? DEFAULT_WEBHOOK_RETRIES
-    const retryDelay = input.retryDelay ?? webhookConfig?.retryDelay
-    const backoff =
-      retryDelay !== undefined && retryDelay !== 'exponential'
-        ? { type: 'fixed', delay: getDurationInMilliseconds(retryDelay) }
-        : retries > 0 || retryDelay === 'exponential'
-          ? 'exponential'
-          : undefined
-    return { attempts: retries + 1, ...(backoff ? { backoff } : {}) }
-  }
-}
-
-// knowledge: decisions/internals/webhook-delivery-history-records-every-attempt-best-effort.md
-export async function pikkuWebhookWorkerFunc(
-  services: { logger: Logger; webhookService?: WebhookService },
-  { url, body, headers, deliveryId }: WebhookJobData
-): Promise<void> {
-  let statusCode: number | undefined
-  let responseBody: string | undefined
-  let error: string | undefined
-  let delivered = false
-
-  let allowedHosts: string[] | undefined
-  try {
-    allowedHosts = getSingletonServices().config?.webhook?.allowedHosts
-  } catch {
-    // Uninitialised singletons (a bare worker invocation): fall back to the
-    // default private-host block rather than failing the delivery.
-  }
-
-  try {
-    const response = await safeFetch(
-      url,
-      {
-        method: 'POST',
-        headers,
-        body,
-        signal: AbortSignal.timeout(30_000),
-      },
-      { allowedHosts }
-    )
-    statusCode = response.status
-    delivered = response.status >= 200 && response.status < 300
-    if (!delivered) {
-      responseBody = (await response.text().catch(() => ''))?.slice(
-        0,
-        MAX_CAPTURED_RESPONSE_BODY
-      )
-      error = `Webhook delivery to ${url} failed with status ${response.status}`
-    }
-  } catch (e) {
-    error = e instanceof Error ? e.message : String(e)
-  }
-
-  if (deliveryId && services.webhookService) {
-    await services.webhookService
-      .recordAttempt(deliveryId, { statusCode, responseBody, error, delivered })
-      .catch((storeError) =>
-        services.logger.error(
-          `Failed to record webhook delivery attempt for ${deliveryId}`,
-          storeError
-        )
-      )
-  }
-
-  if (!delivered) {
-    throw new Error(error ?? `Webhook delivery to ${url} failed`)
-  }
-}

package/src/services/remote-jobs.test.ts

@@ -1,106 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import { BadRequestError, UnauthorizedError } from '../errors/errors.js'
-import { resetPikkuState, setSingletonServices } from '../pikku-state.js'
-import { remoteJobsSecret } from '../middleware/remote-jobs-secret.js'
-import {
-  REMOTE_JOBS_SECRET_HEADER,
-  pikkuRemoteScheduledJobFunc,
-} from './remote-jobs.js'
-
-const silentLogger = {
-  info: () => {},
-  warn: () => {},
-  error: () => {},
-  debug: () => {},
-} as any
-
-const wire = (header?: string) =>
-  ({
-    http: { request: { header: () => header ?? null } },
-  }) as any
-
-const services = (secret?: string) =>
-  ({ variables: { get: async () => secret } }) as any
-
-describe('remoteJobsSecret', () => {
-  test('lets a caller holding the secret through', async () => {
-    let reached = false
-    await remoteJobsSecret(services('s3cret'), wire('s3cret'), async () => {
-      reached = true
-    })
-    assert.equal(reached, true)
-  })
-
-  test('rejects a caller presenting the wrong secret', async () => {
-    await assert.rejects(
-      remoteJobsSecret(services('s3cret'), wire('nope'), async () => {}),
-      UnauthorizedError
-    )
-  })
-
-  test('rejects when the deployment configured no secret at all', async () => {
-    await assert.rejects(
-      remoteJobsSecret(services(undefined), wire('anything'), async () => {}),
-      UnauthorizedError
-    )
-  })
-
-  test('rejects a caller presenting no header', async () => {
-    await assert.rejects(
-      remoteJobsSecret(services('s3cret'), wire(), async () => {}),
-      UnauthorizedError
-    )
-  })
-
-  test('reads the header the dispatchers already send', async () => {
-    const seen: string[] = []
-    await assert.rejects(
-      remoteJobsSecret(
-        services('s3cret'),
-        {
-          http: {
-            request: {
-              header: (name: string) => {
-                seen.push(name)
-                return null
-              },
-            },
-          },
-        } as any,
-        async () => {}
-      ),
-      UnauthorizedError
-    )
-    assert.deepEqual(seen, [REMOTE_JOBS_SECRET_HEADER])
-  })
-
-  test('awaits a variables service that resolves asynchronously', async () => {
-    let reached = false
-    await remoteJobsSecret(
-      {
-        variables: {
-          get: () => new Promise((resolve) => setTimeout(() => resolve('s3cret'), 1)),
-        },
-      } as any,
-      wire('s3cret'),
-      async () => {
-        reached = true
-      }
-    )
-    assert.equal(reached, true)
-  })
-})
-
-describe('pikkuRemoteScheduledJobFunc', () => {
-  test('acks a task this deployment does not have rather than asking for a retry', async () => {
-    resetPikkuState()
-    setSingletonServices({ logger: silentLogger } as any)
-    await assert.rejects(
-      pikkuRemoteScheduledJobFunc({ logger: silentLogger }, {
-        taskName: 'not-a-task',
-      }),
-      BadRequestError
-    )
-  })
-})

package/src/services/remote-jobs.ts

@@ -1,92 +0,0 @@
-import { BadRequestError, PikkuMissingMetaError } from '../errors/errors.js'
-import { QueueJobDiscardedError, runQueueJob } from '../wirings/queue/queue-runner.js'
-import type { QueueJob, QueueJobStatus } from '../wirings/queue/queue.types.js'
-import {
-  ScheduledTaskNotFoundError,
-  runScheduledTask,
-} from '../wirings/scheduler/scheduler-runner.js'
-import type { Logger } from './logger.js'
-
-/** The variable holding the shared secret every remote job must present. */
-export const REMOTE_JOBS_SECRET_VARIABLE = 'PIKKU_DISPATCH_SECRET'
-
-export const REMOTE_JOBS_SECRET_HEADER = 'x-pikku-dispatch'
-
-export const REMOTE_QUEUE_JOB_PATH = '/__pikku/queue-job'
-
-export const REMOTE_SCHEDULER_JOB_PATH = '/__pikku/scheduler-job'
-
-export interface RemoteQueueJobData {
-  queueName: string
-  data?: unknown
-  jobId?: string
-  traceId?: string
-}
-
-export interface RemoteScheduledJobData {
-  taskName: string
-}
-
-/**
- * A dispatched job is delivered, not owned: the sender retries, so a permanent
- * failure has to read differently from a transient one. An unknown worker or a
- * discarded job answers 4xx so the sender stops; anything else propagates and
- * is delivered again.
- */
-export async function pikkuRemoteQueueJobFunc(
-  { logger }: { logger: Logger },
-  { queueName, data, jobId, traceId }: RemoteQueueJobData
-): Promise<void> {
-  const job: QueueJob = {
-    queueName,
-    data,
-    id: jobId ?? traceId ?? `remote-${Date.now()}`,
-    status: async (): Promise<QueueJobStatus> => 'active',
-    metadata: () => ({
-      processedAt: new Date(),
-      attemptsMade: 0,
-      maxAttempts: undefined,
-      result: undefined,
-      progress: 0,
-      createdAt: new Date(),
-      completedAt: undefined,
-      failedAt: undefined,
-      error: undefined,
-    }),
-    waitForCompletion: async () => {
-      throw new Error('remote jobs do not support waitForCompletion')
-    },
-  }
-
-  try {
-    await runQueueJob({ job, traceId })
-  } catch (error) {
-    if (
-      error instanceof PikkuMissingMetaError ||
-      error instanceof QueueJobDiscardedError
-    ) {
-      throw new BadRequestError(error.message)
-    }
-    logger.error(
-      `remote-jobs: queue '${queueName}' failed: ${error instanceof Error ? error.message : String(error)}`
-    )
-    throw error
-  }
-}
-
-export async function pikkuRemoteScheduledJobFunc(
-  { logger }: { logger: Logger },
-  { taskName }: RemoteScheduledJobData
-): Promise<void> {
-  try {
-    await runScheduledTask({ name: taskName, traceId: `cron-${taskName}` })
-  } catch (error) {
-    if (error instanceof ScheduledTaskNotFoundError) {
-      throw new BadRequestError(error.message)
-    }
-    logger.error(
-      `remote-jobs: task '${taskName}' failed: ${error instanceof Error ? error.message : String(error)}`
-    )
-    throw error
-  }
-}

package/src/services/scheduler-service.ts

@@ -1,37 +0,0 @@
-import type { CoreUserSession } from '../types/core.types.js'
-
-export interface ScheduledTaskSummary {
-  taskId: string
-  rpcName: string
-  scheduledFor: Date
-}
-
-export interface ScheduledTaskInfo extends ScheduledTaskSummary {
-  data?: any
-  session?: CoreUserSession
-  status?: 'scheduled' | 'active' | 'completed' | 'failed'
-}
-
-export abstract class SchedulerService {
-  abstract init(): Promise<void>
-
-  /** `delay` is milliseconds as a number, or a duration string such as `"5h"` / `"30m"`. */
-  abstract scheduleRPC(
-    delay: number | string,
-    rpcName: string,
-    data?: any,
-    session?: CoreUserSession
-  ): Promise<string>
-
-  abstract unschedule(taskId: string): Promise<boolean>
-
-  abstract getTask(taskId: string): Promise<ScheduledTaskInfo | null>
-
-  abstract getAllTasks(): Promise<ScheduledTaskSummary[]>
-
-  abstract close(): Promise<void>
-
-  async start(): Promise<void> {}
-
-  async stop(): Promise<void> {}
-}

package/src/services/schema-service.ts

@@ -1,10 +0,0 @@
-export interface SchemaService {
-  compileSchema: (name: string, value: any) => Promise<void> | void
-
-  validateSchema: (schema: string, data: any) => Promise<void> | void
-
-  getSchemaNames: () => Set<string>
-
-  /** Empty when the schema is not registered. */
-  getSchemaKeys: (schemaName: string) => string[]
-}

package/src/services/scope-service.ts

@@ -1,91 +0,0 @@
-import type { FlatScope } from '../wirings/scope/scope.types.js'
-import type { SystemRole } from '../wirings/role/role.types.js'
-
-export interface Role {
-  name: string
-  description?: string
-  scopes: string[]
-  /**
-   * True when the role was declared in code with `defineSystemRole` rather
-   * than composed by an admin. System roles may be granted, but not renamed,
-   * re-scoped or deleted — see {@link ScopeService.syncSystemRoles}.
-   */
-  system?: boolean
-  /**
-   * False when a system role's declaration has been removed from code but its
-   * row survives: still held by whoever holds it, no longer offered for new
-   * grants, awaiting `pikku roles prune`.
-   */
-  declared?: boolean
-}
-
-// knowledge: decisions/security/scope-resolution-happens-at-the-session-boundary-and-sync-never-deletes.md
-export interface ScopeService {
-  syncScopes(scopes: FlatScope[]): Promise<void>
-
-  /** The union of role-derived scopes and scopes granted directly. */
-  resolveScopes(userId: string): Promise<string[]>
-
-  /**
-   * The whole vocabulary a role can be composed from. `declared: false` marks a
-   * scope still in the store but no longer declared in code: inert, since no
-   * function can require it, and awaiting `pikku scopes prune`.
-   */
-  listScopes(): Promise<Array<FlatScope & { declared: boolean }>>
-
-  /**
-   * Registers the roles declared with `defineSystemRole`. Additive on the same
-   * terms as {@link syncScopes}: a removed declaration leaves the row in place,
-   * marked `declared: false`, rather than revoking everyone's grant on deploy.
-   *
-   * A role's scope set *is* re-synced, because that is the declaration's whole
-   * content — editing `defineSystemRole` is how you change what a system role
-   * means, and the deploy is when it takes effect.
-   *
-   * Called once during startup with the generated role list.
-   */
-  syncSystemRoles(roles: SystemRole[]): Promise<void>
-
-  /**
-   * Creates an admin-composed role.
-   *
-   * Must throw {@link SystemRoleShadowedError} when `role.name` matches a
-   * declared system role. Two rows answering to one name make "does this user
-   * hold `buyer`?" depend on which the store returns first.
-   */
-  createRole(role: Role): Promise<void>
-  /** Must throw {@link SystemRoleImmutableError} for a system role. */
-  deleteRole(name: string): Promise<void>
-  /** Must throw {@link SystemRoleImmutableError} for a system role. */
-  setRoleScopes(name: string, scopes: string[]): Promise<void>
-  listRoles(): Promise<Role[]>
-
-  addUserToRole(userId: string, role: string, grantedBy?: string): Promise<void>
-  removeUserFromRole(userId: string, role: string): Promise<void>
-  listUserRoles(userId: string): Promise<string[]>
-
-  /** Grants outside of any role; additive with the user's role-derived scopes. */
-  addScopeToUser(
-    userId: string,
-    scope: string,
-    grantedBy?: string
-  ): Promise<void>
-  removeScopeFromUser(userId: string, scope: string): Promise<void>
-  /** Only the scopes granted directly, not those inherited from roles. */
-  listUserScopes(userId: string): Promise<string[]>
-
-  /** Undeclared scopes with the roles that would lose them; powers `pikku scopes audit`. */
-  findStaleScopes(): Promise<Array<{ scope: string; roles: string[] }>>
-
-  /** Removes undeclared scopes, cascading them out of roles. */
-  pruneScopes(): Promise<string[]>
-
-  /**
-   * System roles in the store whose declaration has gone, with the number of
-   * users still holding each. Powers `pikku roles audit`.
-   */
-  findStaleSystemRoles(): Promise<Array<{ role: string; users: number }>>
-
-  /** Removes undeclared system roles, cascading them out of user grants. */
-  pruneSystemRoles(): Promise<string[]>
-}

package/src/services/scoped-credential-service.test.ts

@@ -1,86 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { ScopedCredentialService } from './scoped-credential-service.js'
-import type { CredentialService } from './credential-service.js'
-
-const createCredentialService = (): CredentialService => {
-  const store: Record<string, Record<string, unknown>> = {
-    'user-1': { slack: 'slack-token', stripe: 'stripe-key' },
-    'user-2': { slack: 'other-slack-token' },
-  }
-  return {
-    get: async (name, userId = 'user-1') =>
-      (store[userId]?.[name] ?? null) as never,
-    set: async (name, value, userId = 'user-1') => {
-      store[userId] = { ...store[userId], [name]: value }
-    },
-    delete: async (name, userId = 'user-1') => {
-      delete store[userId]?.[name]
-    },
-    has: async (name, userId = 'user-1') => name in (store[userId] ?? {}),
-    getAll: async (userId) => store[userId] ?? {},
-    getUsersWithCredential: async (name) =>
-      Object.keys(store).filter((userId) => name in store[userId]!),
-    getAllUsers: async () => Object.keys(store),
-  }
-}
-
-const scoped = (names: string[]) =>
-  new ScopedCredentialService(createCredentialService(), new Set(names))
-
-describe('ScopedCredentialService', () => {
-  test('a declared credential is readable and writable', async () => {
-    const credentials = scoped(['slack'])
-
-    assert.equal(await credentials.get('slack'), 'slack-token')
-    assert.equal(await credentials.has('slack'), true)
-    await credentials.set('slack', 'refreshed')
-    assert.equal(await credentials.get('slack'), 'refreshed')
-    await credentials.delete('slack')
-    assert.equal(await credentials.get('slack'), null)
-  })
-
-  test('an undeclared credential is denied on every accessor', async () => {
-    const credentials = scoped(['slack'])
-
-    await assert.rejects(() => credentials.get('stripe'), /denied/i)
-    await assert.rejects(() => credentials.has('stripe'), /denied/i)
-    await assert.rejects(() => credentials.set('stripe', 'x'), /denied/i)
-    await assert.rejects(() => credentials.delete('stripe'), /denied/i)
-    await assert.rejects(
-      () => credentials.getUsersWithCredential('stripe'),
-      /denied/i
-    )
-  })
-
-  test('getAll returns only the declared credentials, not the whole user', async () => {
-    const credentials = scoped(['slack'])
-
-    assert.deepEqual(await credentials.getAll('user-1'), {
-      slack: 'slack-token',
-    })
-  })
-
-  test('enumerating every user of the app is denied outright', async () => {
-    const credentials = scoped(['slack'])
-
-    await assert.rejects(() => credentials.getAllUsers(), /denied/i)
-  })
-
-  test('the users of a declared credential are still visible', async () => {
-    const credentials = scoped(['slack'])
-
-    assert.deepEqual(await credentials.getUsersWithCredential('slack'), [
-      'user-1',
-      'user-2',
-    ])
-  })
-
-  test('an addon that declares nothing reaches nothing', async () => {
-    const credentials = scoped([])
-
-    await assert.rejects(() => credentials.get('slack'), /denied/i)
-    assert.deepEqual(await credentials.getAll('user-1'), {})
-  })
-})

package/src/services/scoped-credential-service.ts

@@ -1,63 +0,0 @@
-import type { CredentialService } from './credential-service.js'
-
-/**
- * A `CredentialService` narrowed to the credentials a package declared.
- *
- * Unlike `ScopedSecretService` this stays writable — an addon refreshing its
- * own OAuth token is the normal case. What it cannot do is reach a credential
- * it never declared, or enumerate the app's users.
- */
-export class ScopedCredentialService implements CredentialService {
-  constructor(
-    private credentials: CredentialService,
-    private allowedNames: Set<string>
-  ) {}
-
-  private assertAllowed(name: string): void {
-    if (!this.allowedNames.has(name)) {
-      throw new Error(`Access denied to credential: ${name}`)
-    }
-  }
-
-  async get<T = unknown>(name: string, userId?: string): Promise<T | null> {
-    this.assertAllowed(name)
-    return this.credentials.get<T>(name, userId)
-  }
-
-  async set(name: string, value: unknown, userId?: string): Promise<void> {
-    this.assertAllowed(name)
-    return this.credentials.set(name, value, userId)
-  }
-
-  async delete(name: string, userId?: string): Promise<void> {
-    this.assertAllowed(name)
-    return this.credentials.delete(name, userId)
-  }
-
-  async has(name: string, userId?: string): Promise<boolean> {
-    this.assertAllowed(name)
-    return this.credentials.has(name, userId)
-  }
-
-  async getAll(userId: string): Promise<Record<string, unknown>> {
-    const all = await this.credentials.getAll(userId)
-    const scoped: Record<string, unknown> = {}
-    for (const name of this.allowedNames) {
-      if (name in all) {
-        scoped[name] = all[name]
-      }
-    }
-    return scoped
-  }
-
-  async getUsersWithCredential(name: string): Promise<string[]> {
-    this.assertAllowed(name)
-    return this.credentials.getUsersWithCredential(name)
-  }
-
-  async getAllUsers(): Promise<string[]> {
-    throw new Error(
-      'Access denied: enumerating users is not allowed in a scoped credential service'
-    )
-  }
-}