@pikku/core 0.12.107 → 0.12.111

package/src/services/audit-service.ts

@@ -1,280 +0,0 @@
-import type {
-  CoreUserSession,
-  PikkuWire,
-  PikkuWiringTypes,
-} from '../types/core.types.js'
-import type { Logger } from './logger.js'
-import type { Safe } from '../classification/secret-value.js'
-
-export type AuditDurability = 'best-effort' | 'transactional'
-export type AuditOutcome = 'success' | 'failed' | 'denied'
-export type AuditSource = 'auto' | 'explicit'
-
-export type AuditConfig =
-  | boolean
-  | {
-      durability?: AuditDurability
-    }
-
-export type ResolvedAuditConfig = {
-  durability: AuditDurability
-}
-
-/**
- * Who an event happened under.
- *
- * A user, not an "actor": in pikku an actor is a synthetic person a scenario
- * drives, flagged `actor` on the user row, and the overwhelming majority of
- * audited events are caused by ordinary customers. Naming this `actor` made the
- * synthetic case unsayable — `actor.actor === true` — and implied every
- * recorded action was a test.
- *
- * `pikkuUserId` is the identity pikku resolves for every wire, so it is the one
- * field a signed-out caller still leaves behind.
- */
-export type AuditUserIdentity = {
-  userId?: string
-  orgId?: string
-  pikkuUserId?: string
-}
-
-export type AuditEvent = {
-  eventId?: string
-  type: string
-  source: AuditSource
-  outcome?: AuditOutcome
-  occurredAt: string
-  functionId?: string
-  wireType?: PikkuWiringTypes
-  wireId?: string
-  traceId?: string
-  transactionId?: string | null
-  queryId?: string | null
-  userIdentity?: AuditUserIdentity
-  input?: unknown
-  metadata?: Record<string, unknown>
-}
-
-export type AuditEventBatch = AuditEvent[]
-
-/**
- * A page of the trail, newest first, narrowed by the filters a reader picked.
- *
- * Every field is a conjunction, and an empty array is not a filter — it is
- * "match nothing", which would otherwise read as "match everything" and quietly
- * widen a scoped query.
- */
-export type AuditQuery = {
-  /** Restrict to these users. */
-  userIds?: string[]
-  /** Restrict to these `AuditEvent['type']` values. */
-  types?: string[]
-  /** Restrict to one organisation. */
-  orgId?: string
-  /** Inclusive lower bound on `occurredAt` (ISO 8601). */
-  from?: string
-  /** Exclusive upper bound on `occurredAt` (ISO 8601). */
-  to?: string
-  limit?: number
-  offset?: number
-}
-
-/**
- * The distinct values present in the trail, for populating filter controls.
- *
- * Computed over the whole trail rather than the current page — a filter list
- * that only offered what the current page happens to show could never be used
- * to reach anything else.
- */
-export type AuditFacets = {
-  userIds: string[]
-  types: string[]
-}
-
-export type AuditQueryResult = {
-  events: AuditEvent[]
-  /** Offset of the next page, or `null` at the end. */
-  nextCursor: number | null
-  /** Present only when the caller asked for it — it costs two extra scans. */
-  facets?: AuditFacets
-}
-
-export interface AuditService {
-  audit(event: AuditEvent): Promise<void>
-  write?(batch: AuditEventBatch): Promise<void>
-  /**
-   * The read side. Optional because a sink can legitimately be write-only — a
-   * queue producer that hands events to another system has nothing to read
-   * back. A reader that finds this absent should say the trail is not readable
-   * here rather than that it is empty; the two are very different answers.
-   */
-  query?(query: AuditQuery): Promise<AuditQueryResult>
-  /** Distinct users and types across the whole trail. Paired with {@link query}. */
-  facets?(): Promise<AuditFacets>
-}
-
-export class NoopAuditService implements AuditService {
-  async audit(_event: AuditEvent): Promise<void> {}
-
-  async write(_batch: AuditEventBatch): Promise<void> {}
-}
-
-export type AuditLogWriteInput = Omit<AuditEvent, 'occurredAt'>
-
-/**
- * The audit an invocation writes to. `write` is `Safe<>`-guarded like the
- * logger: an audit event carries `input` and `metadata` as `unknown`, so
- * nominality alone cannot stop a `SecretValue` landing in one. A secret
- * anywhere in the event, however deeply nested, collapses to `never`.
- *
- * An unrevealed `SecretValue` would serialize as `[secret]` anyway; the guard
- * is what makes that an explicit choice rather than a near miss.
- */
-export interface AuditLog {
-  readonly config: ResolvedAuditConfig | undefined
-  write<E extends AuditLogWriteInput>(event: Safe<E>): Promise<void>
-  flush(): Promise<void>
-  close(): Promise<void>
-}
-
-class DisabledInvocationAudit implements AuditLog {
-  public readonly config = undefined
-  private warned = false
-
-  constructor(
-    private readonly wire: PikkuWire<any, any, any, CoreUserSession>,
-    private readonly logger?: Logger
-  ) {}
-
-  async write(_event: AuditLogWriteInput): Promise<void> {
-    if (!this.warned) {
-      this.warned = true
-      // knowledge: decisions/security/a-dropped-audit-write-is-always-logged.md
-      const logger = this.wire.logger ?? this.logger
-      logger?.warn?.(
-        `audit.write() dropped for '${this.wire.functionId ?? 'unknown function'}' — the function has no audit config (set audit: true on it)`
-      )
-    }
-  }
-
-  async flush(): Promise<void> {}
-
-  async close(): Promise<void> {}
-}
-
-class InvocationAuditLog implements AuditLog {
-  private readonly buffer: AuditEvent[] = []
-
-  constructor(
-    public readonly config: ResolvedAuditConfig,
-    private readonly service: AuditService,
-    private readonly wire: PikkuWire<any, any, any, CoreUserSession>,
-    private readonly logger?: Logger
-  ) {}
-
-  async write(event: AuditLogWriteInput): Promise<void> {
-    const resolved = this.resolveEvent(event)
-
-    if (this.config.durability === 'transactional') {
-      await this.service.audit(resolved)
-      return
-    }
-
-    this.buffer.push(resolved)
-  }
-
-  async flush(): Promise<void> {
-    if (
-      this.config.durability === 'transactional' ||
-      this.buffer.length === 0
-    ) {
-      return
-    }
-
-    const batch = this.buffer.splice(0, this.buffer.length)
-    const queryEvents = batch.filter((event) => event.queryId != null)
-    if (queryEvents.length === 1) {
-      queryEvents[0]!.queryId = null
-    }
-
-    try {
-      if (this.service.write) {
-        await this.service.write(batch)
-        return
-      }
-
-      for (const event of batch) {
-        await this.service.audit(event)
-      }
-    } catch (error) {
-      const logger = this.wire.logger ?? this.logger
-      logger?.warn?.('best-effort audit flush failed', error)
-    }
-  }
-
-  async close(): Promise<void> {
-    await this.flush()
-  }
-
-  private resolveEvent(event: AuditLogWriteInput): AuditEvent {
-    return {
-      functionId: this.wire.functionId,
-      wireType: this.wire.wireType,
-      wireId: this.wire.wireId,
-      traceId: this.wire.traceId,
-      userIdentity:
-        event.userIdentity ?? resolveAuditUserIdentityFromWire(this.wire),
-      ...event,
-      occurredAt: new Date().toISOString(),
-    }
-  }
-}
-
-export const resolveAuditConfig = (
-  config?: AuditConfig
-): ResolvedAuditConfig | undefined => {
-  if (config === true) {
-    return { durability: 'best-effort' }
-  }
-
-  if (!config) {
-    return undefined
-  }
-
-  return {
-    durability: config.durability ?? 'best-effort',
-  }
-}
-
-export const createInvocationAudit = (
-  service: AuditService,
-  wire: PikkuWire<any, any, any, CoreUserSession>,
-  logger?: Logger
-): AuditLog => {
-  if (!wire.audit) {
-    return new DisabledInvocationAudit(wire, logger)
-  }
-
-  return new InvocationAuditLog(wire.audit, service, wire, logger)
-}
-
-export const resolveAuditUserIdentityFromWire = (
-  wire: PikkuWire<any, any, any, CoreUserSession>
-): AuditUserIdentity | undefined => {
-  const session = wire.session as CoreUserSession | undefined
-  const userIdentity: AuditUserIdentity = {
-    userId: session?.userId,
-    orgId: session?.orgId,
-    pikkuUserId: wire.pikkuUserId,
-  }
-
-  if (
-    !userIdentity.userId &&
-    !userIdentity.orgId &&
-    !userIdentity.pikkuUserId
-  ) {
-    return undefined
-  }
-
-  return userIdentity
-}

package/src/services/content-service.ts

@@ -1,65 +0,0 @@
-export interface SignContentKeyArgs<TBucket extends string = string> {
-  bucket: TBucket
-  contentKey: string
-  dateLessThan: Date
-  dateGreaterThan?: Date
-}
-
-export interface SignURLArgs {
-  url: string
-  dateLessThan: Date
-  dateGreaterThan?: Date
-}
-
-export interface GetUploadURLArgs<TBucket extends string = string> {
-  bucket: TBucket
-  fileKey: string
-  contentType: string
-  size?: number
-  visibility?: 'private' | 'public'
-}
-
-export interface UploadURLResult {
-  uploadUrl: string
-  assetKey: string
-  uploadHeaders?: Record<string, string>
-  uploadMethod?: 'PUT' | 'POST'
-}
-
-export interface BucketKeyArgs<TBucket extends string = string> {
-  bucket: TBucket
-  key: string
-}
-
-export interface WriteFileArgs<
-  TBucket extends string = string,
-> extends BucketKeyArgs<TBucket> {
-  stream: ReadableStream | NodeJS.ReadableStream
-}
-
-export interface CopyFileArgs<
-  TBucket extends string = string,
-> extends BucketKeyArgs<TBucket> {
-  fromAbsolutePath: string
-}
-
-export interface ContentService<TBucket extends string = string> {
-  signContentKey(args: SignContentKeyArgs<TBucket>): Promise<string>
-
-  signURL(args: SignURLArgs): Promise<string>
-
-  /** Bucket policy (size limits, MIME allowlist) is enforced by the implementation, not the caller. */
-  getUploadURL(args: GetUploadURLArgs<TBucket>): Promise<UploadURLResult>
-
-  deleteFile(args: BucketKeyArgs<TBucket>): Promise<boolean>
-
-  writeFile(args: WriteFileArgs<TBucket>): Promise<boolean>
-
-  copyFile(args: CopyFileArgs<TBucket>): Promise<boolean>
-
-  readFile(
-    args: BucketKeyArgs<TBucket>
-  ): Promise<ReadableStream | NodeJS.ReadableStream>
-
-  readFileAsBuffer(args: BucketKeyArgs<TBucket>): Promise<Buffer>
-}

package/src/services/credential-service.ts

@@ -1,20 +0,0 @@
-/**
- * Dynamic credentials — OAuth tokens, per-user API keys — that change at
- * runtime, as opposed to `SecretService`'s static developer-configured values.
- * Throughout, an omitted `userId` means the platform-level credential.
- */
-export interface CredentialService {
-  get<T = unknown>(name: string, userId?: string): Promise<T | null>
-
-  set(name: string, value: unknown, userId?: string): Promise<void>
-
-  delete(name: string, userId?: string): Promise<void>
-
-  has(name: string, userId?: string): Promise<boolean>
-
-  getAll(userId: string): Promise<Record<string, unknown>>
-
-  getUsersWithCredential(name: string): Promise<string[]>
-
-  getAllUsers(): Promise<string[]>
-}

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

@@ -1,235 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert'
-import {
-  PikkuCredentialWireService,
-  createMiddlewareCredentialWireProps,
-  createWireServicesCredentialWireProps,
-} from './credential-wire-service.js'
-import type { CredentialService } from './credential-service.js'
-import type { PikkuWire } from '../types/core.types.js'
-
-const mockCredentialService = (
-  creds: Record<string, unknown>
-): CredentialService => ({
-  get: async (name: string) => creds[name] ?? null,
-  set: async () => {},
-  delete: async () => {},
-  has: async (name: string) => name in creds,
-  getAll: async () => creds,
-})
-
-describe('PikkuCredentialWireService', () => {
-  test('should set and get credentials manually', async () => {
-    const service = new PikkuCredentialWireService()
-    service.set('stripe', { apiKey: 'sk_test' })
-    const result = await service.getAll()
-    assert.deepStrictEqual(result, { stripe: { apiKey: 'sk_test' } })
-  })
-
-  test('should return sync after first load (no credential service)', async () => {
-    const service = new PikkuCredentialWireService()
-    service.set('foo', 'bar')
-    await service.getAll()
-    const result = service.getAll()
-    assert.ok(!(result instanceof Promise), 'expected sync return')
-    assert.deepStrictEqual(result, { foo: 'bar' })
-  })
-
-  test('should lazy-load from credential service on first getAll', async () => {
-    const credService = mockCredentialService({
-      stripe: { apiKey: 'sk_live' },
-      github: { token: 'ghp_abc' },
-    })
-    const wire: PikkuWire = { session: { userId: 'user-1' } as any }
-    const service = new PikkuCredentialWireService(credService, wire)
-
-    const result = await service.getAll()
-    assert.deepStrictEqual(result, {
-      stripe: { apiKey: 'sk_live' },
-      github: { token: 'ghp_abc' },
-    })
-  })
-
-  test('should set pikkuUserId on wire after lazy load', async () => {
-    const credService = mockCredentialService({})
-    const wire: PikkuWire = { session: { userId: 'user-1' } as any }
-    const service = new PikkuCredentialWireService(credService, wire)
-
-    await service.getAll()
-    assert.strictEqual(wire.pikkuUserId, 'user-1')
-  })
-
-  test('should not overwrite manually set credentials during lazy load', async () => {
-    const credService = mockCredentialService({
-      stripe: { apiKey: 'from-db' },
-    })
-    const wire: PikkuWire = { session: { userId: 'user-1' } as any }
-    const service = new PikkuCredentialWireService(credService, wire)
-
-    service.set('stripe', { apiKey: 'from-middleware' })
-    const result = await service.getAll()
-    assert.deepStrictEqual(result.stripe, { apiKey: 'from-middleware' })
-  })
-
-  test('should return sync on subsequent calls after lazy load', async () => {
-    const credService = mockCredentialService({ stripe: { key: '123' } })
-    const wire: PikkuWire = { session: { userId: 'user-1' } as any }
-    const service = new PikkuCredentialWireService(credService, wire)
-
-    await service.getAll()
-    const result = service.getAll()
-    assert.ok(!(result instanceof Promise), 'expected sync return')
-    assert.deepStrictEqual(result, { stripe: { key: '123' } })
-  })
-
-  test('should not load when no userId resolvable', async () => {
-    let called = false
-    const credService: CredentialService = {
-      get: async () => null,
-      set: async () => {},
-      delete: async () => {},
-      has: async () => false,
-      getAll: async () => {
-        called = true
-        return {}
-      },
-    }
-    const wire: PikkuWire = {}
-    const service = new PikkuCredentialWireService(credService, wire)
-
-    const result = await service.getAll()
-    assert.deepStrictEqual(result, {})
-    assert.strictEqual(called, false)
-  })
-
-  test('should deduplicate concurrent lazy load calls', async () => {
-    let callCount = 0
-    const credService: CredentialService = {
-      get: async () => null,
-      set: async () => {},
-      delete: async () => {},
-      has: async () => false,
-      getAll: async () => {
-        callCount++
-        return { stripe: { key: 'test' } }
-      },
-    }
-    const wire: PikkuWire = { session: { userId: 'user-1' } as any }
-    const service = new PikkuCredentialWireService(credService, wire)
-
-    const [r1, r2] = await Promise.all([service.getAll(), service.getAll()])
-    assert.strictEqual(callCount, 1)
-    assert.deepStrictEqual(r1, r2)
-  })
-
-  /**
-   * The regression the `loaded` flag was written to avoid.
-   *
-   * `get` answers synchronously once `loaded` is set, so setting the flag
-   * before the fetch resolved gave every caller that arrived during the load a
-   * confident `null` for a credential that exists. `getAll` hid it: it hands
-   * back the live `credentials` object, which is filled in before anyone
-   * asserts on it, so only a reader that copies a VALUE out sees the gap.
-   */
-  test('should not answer null while a lazy load is still in flight', async () => {
-    const credService = mockCredentialService({ stripe: { key: 'sk_live' } })
-    const wire: PikkuWire = { session: { userId: 'user-1' } as any }
-    const service = new PikkuCredentialWireService(credService, wire)
-
-    // Issued in one tick, exactly as `Promise.all` over sibling RPC calls does.
-    const results = await Promise.all([
-      service.get('stripe'),
-      service.get('stripe'),
-      service.get('stripe'),
-    ])
-
-    for (const [index, result] of results.entries()) {
-      assert.deepStrictEqual(
-        result,
-        { key: 'sk_live' },
-        `concurrent reader ${index} lost the credential`
-      )
-    }
-  })
-
-  test('should not answer null during a slow lazy load', async () => {
-    const credService: CredentialService = {
-      get: async () => null,
-      set: async () => {},
-      delete: async () => {},
-      has: async () => true,
-      getAll: async () => {
-        await new Promise((resolve) => setTimeout(resolve, 10))
-        return { stripe: { key: 'sk_live' } }
-      },
-    }
-    const wire: PikkuWire = { session: { userId: 'user-1' } as any }
-    const service = new PikkuCredentialWireService(credService, wire)
-
-    const first = service.get('stripe')
-    const second = service.get('stripe')
-    assert.deepStrictEqual(await first, { key: 'sk_live' })
-    assert.deepStrictEqual(await second, { key: 'sk_live' })
-  })
-
-  test('should still take the sync path when there is nothing to load', async () => {
-    // Both early returns are settled states, so they must set `loaded` too.
-    const service = new PikkuCredentialWireService(
-      mockCredentialService({ stripe: { key: '1' } }),
-      {}
-    )
-    await service.getAll()
-    assert.ok(
-      !(service.getAll() instanceof Promise),
-      'expected sync return after an unresolvable user'
-    )
-  })
-
-  test('getScoped should only return allowed names', async () => {
-    const credService = mockCredentialService({
-      stripe: { key: '1' },
-      github: { token: '2' },
-      slack: { webhook: '3' },
-    })
-    const wire: PikkuWire = { session: { userId: 'user-1' } as any }
-    const service = new PikkuCredentialWireService(credService, wire)
-
-    const result = await service.getScoped(['stripe', 'slack'])
-    assert.deepStrictEqual(result, {
-      stripe: { key: '1' },
-      slack: { webhook: '3' },
-    })
-  })
-})
-
-describe('createMiddlewareCredentialWireProps', () => {
-  test('should provide setCredential that writes to service', async () => {
-    const service = new PikkuCredentialWireService()
-    const props = createMiddlewareCredentialWireProps(service)
-    props.setCredential('stripe', { apiKey: 'test' })
-    const result = await service.getAll()
-    assert.deepStrictEqual(result, { stripe: { apiKey: 'test' } })
-  })
-})
-
-describe('createWireServicesCredentialWireProps', () => {
-  test('should provide both setCredential and getCredentials', async () => {
-    const service = new PikkuCredentialWireService()
-    const props = createWireServicesCredentialWireProps(service)
-    props.setCredential('stripe', { apiKey: 'test' })
-    const result = await props.getCredentials()
-    assert.deepStrictEqual(result, { stripe: { apiKey: 'test' } })
-  })
-
-  test('should scope getCredentials when allowedNames provided', async () => {
-    const credService = mockCredentialService({
-      stripe: { key: '1' },
-      github: { token: '2' },
-    })
-    const wire: PikkuWire = { session: { userId: 'user-1' } as any }
-    const service = new PikkuCredentialWireService(credService, wire)
-    const props = createWireServicesCredentialWireProps(service, ['stripe'])
-    const result = await props.getCredentials()
-    assert.deepStrictEqual(result, { stripe: { key: '1' } })
-  })
-})