@pikku/core 0.12.107 → 0.12.112

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

@@ -1,120 +0,0 @@
-import { isSecretValue } from '../classification/secret-value.js'
-import type { CredentialService } from './credential-service.js'
-import { defaultPikkuUserIdResolver } from './pikku-user-id.js'
-import type { PikkuRawWire } from '../types/core.types.js'
-
-export class PikkuCredentialWireService {
-  private credentials: Record<string, unknown> = {}
-  private loaded = false
-  private loadPromise: Promise<void> | undefined
-
-  constructor(
-    private credentialService?: CredentialService,
-    private wire?: PikkuRawWire,
-    private aliases?: Record<string, string>
-  ) {}
-
-  private resolveName(name: string): string {
-    return this.aliases?.[name] ?? name
-  }
-
-  /**
-   * A credential is one of the few places vault material is meant to end up, so
-   * a `SecretValue` is unwrapped here rather than rejected — `get` promises the
-   * raw material, and storing the wrapper would make that a lie.
-   */
-  set(name: string, value: unknown): void {
-    this.credentials[this.resolveName(name)] = isSecretValue(value)
-      ? value.reveal()
-      : value
-  }
-
-  get<T = unknown>(name: string): T | null | Promise<T | null> {
-    const key = this.resolveName(name)
-    if (this.loaded) return (this.credentials[key] as T) ?? null
-    return this.lazyLoad().then(() => (this.credentials[key] as T) ?? null)
-  }
-
-  getAll(): Record<string, unknown> | Promise<Record<string, unknown>> {
-    if (this.loaded) return this.credentials
-    return this.lazyLoad().then(() => this.credentials)
-  }
-
-  getScoped(
-    allowedNames: string[]
-  ): Record<string, unknown> | Promise<Record<string, unknown>> {
-    const buildScoped = () => {
-      const scoped: Record<string, unknown> = {}
-      for (const name of allowedNames) {
-        if (name in this.credentials) {
-          scoped[name] = this.credentials[name]
-        }
-      }
-      return scoped
-    }
-    if (this.loaded) return buildScoped()
-    return this.lazyLoad().then(buildScoped)
-  }
-
-  private lazyLoad(): Promise<void> {
-    if (this.loadPromise) return this.loadPromise
-    this.loadPromise = this.doLoad()
-    return this.loadPromise
-  }
-
-  /**
-   * `loaded` means "the credentials are in hand", never "a load has started".
-   *
-   * The distinction matters because `get`, `getAll` and `getScoped` all answer
-   * SYNCHRONOUSLY once it is set. Setting it before the await let every caller
-   * that arrived while the fetch was still in flight take that synchronous path
-   * over an empty map and receive `null` for a credential that exists — the
-   * first of N concurrent readers got the value and the rest silently did not.
-   * `loadPromise` is what guards against loading twice; this flag is only ever
-   * about whether the fast path is safe to take.
-   *
-   * `finally` rather than a trailing assignment: the two early returns (no
-   * service or wire, no resolvable user) are settled states as well — there is
-   * nothing to fetch — so they should reach the fast path too.
-   */
-  private async doLoad(): Promise<void> {
-    try {
-      if (!this.credentialService || !this.wire) return
-      const userId = defaultPikkuUserIdResolver(this.wire)
-      if (!userId) return
-      this.wire.pikkuUserId = userId
-      const allCreds = await this.credentialService.getAll(userId)
-      for (const [name, value] of Object.entries(allCreds)) {
-        if (!(name in this.credentials)) {
-          this.credentials[name] = value
-        }
-      }
-    } finally {
-      this.loaded = true
-    }
-  }
-}
-
-export function createMiddlewareCredentialWireProps(
-  credentialWire: PikkuCredentialWireService
-) {
-  return {
-    setCredential: (name: string, value: unknown) =>
-      credentialWire.set(name, value),
-  }
-}
-
-export function createWireServicesCredentialWireProps(
-  credentialWire: PikkuCredentialWireService,
-  allowedNames?: string[]
-) {
-  return {
-    setCredential: (name: string, value: unknown) =>
-      credentialWire.set(name, value),
-    getCredential: <T = unknown>(name: string) => credentialWire.get<T>(name),
-    getCredentials: () =>
-      allowedNames
-        ? credentialWire.getScoped(allowedNames)
-        : credentialWire.getAll(),
-  }
-}

package/src/services/deployment-service.ts

@@ -1,32 +0,0 @@
-export interface DeploymentServiceConfig {
-  heartbeatInterval?: number
-  heartbeatTtl?: number
-}
-
-export interface DeploymentConfig {
-  deploymentId: string
-  endpoint: string
-  functions?: string[]
-}
-
-export interface DeploymentInfo {
-  deploymentId: string
-  endpoint: string
-}
-
-export interface DeploymentService {
-  init(): Promise<void>
-  start(config: DeploymentConfig): Promise<void>
-  stop(): Promise<void>
-  /**
-   * The implementation owns the whole transport: resolving the target
-   * (endpoint, service binding), propagating the session (JWT signing,
-   * headers) and making the call. Callers supply no transport detail.
-   */
-  invoke(
-    funcName: string,
-    data: unknown,
-    session?: unknown,
-    traceId?: string
-  ): Promise<unknown>
-}

package/src/services/email-service.test.ts

@@ -1,100 +0,0 @@
-import assert from 'node:assert/strict'
-import { test } from 'node:test'
-
-import type {
-  EmailAttachment,
-  EmailService,
-  SendEmailInput,
-  SendEmailResult,
-  SendHTMLEmailInput,
-  SendTemplateEmailInput,
-  SendTextEmailInput,
-} from './email-service.js'
-
-const receipt: EmailAttachment = {
-  filename: 'receipt.pdf',
-  content: new Uint8Array([1, 2, 3]),
-  contentType: 'application/pdf',
-}
-
-const logo: EmailAttachment = {
-  filename: 'logo.png',
-  content: 'aGVsbG8=',
-  contentType: 'image/png',
-  contentId: 'logo',
-  disposition: 'inline',
-}
-
-test('a text email carries attachments', () => {
-  const input: SendTextEmailInput = {
-    to: 'user@example.com',
-    text: 'Your receipt is attached',
-    attachments: [receipt],
-  }
-
-  assert.deepEqual(input.attachments, [receipt])
-})
-
-test('an html email carries attachments', () => {
-  const input: SendHTMLEmailInput = {
-    to: 'user@example.com',
-    html: '<img src="cid:logo" />',
-    attachments: [logo],
-  }
-
-  assert.equal(input.attachments?.[0]?.disposition, 'inline')
-  assert.equal(input.attachments?.[0]?.contentId, 'logo')
-})
-
-test('a template email carries attachments', () => {
-  const input: SendTemplateEmailInput = {
-    to: 'user@example.com',
-    template: { name: 'receipt', locale: 'en', data: { total: 10 } },
-    attachments: [receipt, logo],
-  }
-
-  assert.equal(input.attachments?.length, 2)
-})
-
-test('attachments are optional on every variant', () => {
-  const inputs: SendEmailInput[] = [
-    { to: 'user@example.com', text: 'hello' },
-    { to: 'user@example.com', html: '<p>hello</p>' },
-    { to: 'user@example.com', template: { name: 'welcome' } },
-  ]
-
-  for (const input of inputs) {
-    assert.equal(input.attachments, undefined)
-  }
-})
-
-test('a wrapping service forwards attachments to its delegate', async () => {
-  const sent: SendEmailInput[] = []
-  const delegate: EmailService = {
-    async send(input): Promise<SendEmailResult> {
-      sent.push(input as SendEmailInput)
-      return { messageId: 'delegated' }
-    },
-  }
-
-  const wrapper: EmailService = {
-    async send(input): Promise<SendEmailResult> {
-      const { template, ...rest } = input as SendTemplateEmailInput
-      return delegate.send({
-        ...rest,
-        subject: `rendered:${template.name}`,
-        html: '<p>rendered</p>',
-      })
-    },
-  }
-
-  const result = await wrapper.send({
-    to: 'user@example.com',
-    template: { name: 'receipt' },
-    attachments: [receipt],
-  })
-
-  assert.equal(result.messageId, 'delegated')
-  assert.equal(sent.length, 1)
-  assert.deepEqual(sent[0]!.attachments, [receipt])
-})

package/src/services/email-service.ts

@@ -1,60 +0,0 @@
-import type { Safe } from '../classification/secret-value.js'
-
-export interface EmailTemplateReference {
-  name: string
-  locale?: string
-  data?: Record<string, unknown>
-}
-
-export interface EmailAttachment {
-  filename: string
-  /**
-   * Raw bytes, or the content already base64-encoded. A `string` is always
-   * read as base64 — never as a plain-text body — so text attachments must be
-   * encoded by the caller.
-   */
-  content: Uint8Array | string
-  contentType?: string
-  contentId?: string
-  disposition?: 'attachment' | 'inline'
-}
-
-export interface BaseSendEmailInput {
-  to: string | string[]
-  from?: string
-  cc?: string | string[]
-  bcc?: string | string[]
-  replyTo?: string | string[]
-  headers?: Record<string, string>
-  subject?: string
-  attachments?: EmailAttachment[]
-}
-
-export interface SendTextEmailInput extends BaseSendEmailInput {
-  text: string
-  html?: never
-  template?: never
-}
-
-export interface SendHTMLEmailInput extends BaseSendEmailInput {
-  html: string
-  text?: string
-  template?: never
-}
-
-export interface SendTemplateEmailInput extends BaseSendEmailInput {
-  template: EmailTemplateReference
-  html?: never
-  text?: never
-}
-
-export type SendEmailInput =
-  SendTextEmailInput | SendHTMLEmailInput | SendTemplateEmailInput
-
-export interface SendEmailResult {
-  messageId?: string
-}
-
-export interface EmailService {
-  send<T extends SendEmailInput>(input: Safe<T>): Promise<SendEmailResult>
-}

package/src/services/email-template.test.ts

@@ -1,311 +0,0 @@
-import assert from 'node:assert'
-import { describe, test } from 'node:test'
-import { renderEmail, type EmailAssets } from './email-template.js'
-
-const THEME = {
-  appName: 'Pikku App',
-  colors: {
-    background: '#f5f7fb',
-    surface: '#ffffff',
-    text: '#101828',
-    border: '#d0d5dd',
-    primary: '#7c3aed',
-  },
-  fonts: {
-    body: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
-  },
-}
-
-const LOCALES = {
-  en: {
-    passwordReset: {
-      subject: 'Reset your {{appName}} password',
-      note: 'If you did not ask for this, you can ignore it.',
-      cta: 'Choose a new password',
-    },
-  },
-}
-
-const PARTIALS = {
-  layout: `<!doctype html>
-<html lang="{{locale}}">
-  <head><title>{{subject}}</title></head>
-  <body style="font-family:{{theme.fonts.body}};color:{{theme.colors.text}};">
-    <div>{{content}}</div>
-  </body>
-</html>`,
-  footer: `<div class="footer" style="color:{{theme.colors.border}};">{{t.passwordReset.note}}</div>`,
-}
-
-const HTML = `<div>
-  <p>Hello {{userName}}.</p>
-  <a href="{{resetUrl}}" style="background:{{theme.colors.primary}};">{{t.passwordReset.cta}}</a>
-  <p>{{{rawNotice}}}</p>
-</div>
-{{> footer}}`
-
-const SUBJECT = `{{t.passwordReset.subject}}\n`
-
-const TEXT = `{{t.passwordReset.subject}}
-
-Hello {{userName}}.
-
-{{t.passwordReset.cta}}: {{resetUrl}}
-`
-
-const ASSETS: EmailAssets = {
-  theme: THEME,
-  locales: LOCALES,
-  partials: PARTIALS,
-  templates: {
-    'password-reset': {
-      html: HTML,
-      subject: SUBJECT,
-      text: TEXT,
-      variables: ['appName', 'rawNotice', 'resetUrl', 'userName'],
-      hashes: {
-        en: {
-          contentHash: 'content-hash',
-          htmlHash: 'html-hash',
-          subjectHash: 'subject-hash',
-          textHash: 'text-hash',
-        },
-      },
-    },
-  },
-}
-
-const render = (data: Record<string, unknown>) =>
-  renderEmail(ASSETS, { name: 'password-reset', locale: 'en', data })
-
-describe('renderEmail escaping', () => {
-  test('a value containing a double quote cannot break out of an attribute', () => {
-    const { html } = render({
-      resetUrl: 'https://x.test/" onmouseover="alert(1)',
-    })
-    assert.ok(
-      !html.includes('onmouseover="alert(1)"'),
-      `attribute broke out:\n${html}`
-    )
-    assert.ok(
-      html.includes('href="https://x.test/&quot; onmouseover=&quot;alert(1)"'),
-      `quote was not escaped:\n${html}`
-    )
-  })
-
-  test('a value containing markup renders escaped, with no raw script tag', () => {
-    const { html } = render({
-      resetUrl: '"><script>alert(1)</script><a href="',
-    })
-    assert.ok(!html.includes('<script>'), `raw <script> present:\n${html}`)
-    assert.ok(html.includes('&lt;script&gt;alert(1)&lt;/script&gt;'))
-  })
-
-  test('a value containing handlebars is not re-expanded', () => {
-    const { html } = render({ resetUrl: '{{t.passwordReset.note}}' })
-    assert.ok(
-      !html.includes('If you did not ask for this, you can ignore it.</a>'),
-      `caller value was re-expanded as a template:\n${html}`
-    )
-    assert.ok(html.includes('href="{{t.passwordReset.note}}"'))
-  })
-
-  test('a value cannot forge a partial reference', () => {
-    const { html } = render({ resetUrl: '{{> footer}}' })
-    assert.ok(html.includes('href="{{&gt; footer}}"'), html)
-  })
-
-  test('a font stack with embedded quotes renders a valid style attribute', () => {
-    const { html } = render({ resetUrl: 'https://x.test/reset' })
-    assert.ok(
-      html.includes(
-        '<body style="font-family:-apple-system, BlinkMacSystemFont, &quot;Segoe UI&quot;, Roboto, sans-serif;color:#101828;">'
-      ),
-      `theme font stack corrupted the style attribute:\n${html}`
-    )
-  })
-
-  test('an app name with an apostrophe and an ampersand stays inside the tag', () => {
-    const { html, subject } = render({
-      appName: "Peet's & Co",
-      resetUrl: 'https://x.test/reset',
-    })
-    assert.ok(
-      html.includes('<title>Reset your Peet&#39;s &amp; Co password</title>'),
-      html
-    )
-    assert.strictEqual(subject, "Reset your Peet's & Co password")
-  })
-
-  test('{{content}} and partials still render raw', () => {
-    const { html } = render({ resetUrl: 'https://x.test/reset' })
-    assert.ok(html.includes('<a href="https://x.test/reset"'), html)
-    assert.ok(html.includes('<div class="footer"'), html)
-    assert.ok(
-      html.includes('>If you did not ask for this, you can ignore it.</div>'),
-      html
-    )
-  })
-
-  test('the triple-brace form is an opt-in raw escape hatch', () => {
-    const { html } = render({
-      resetUrl: 'https://x.test/reset',
-      rawNotice: '<strong>read me</strong>',
-    })
-    assert.ok(html.includes('<p><strong>read me</strong></p>'), html)
-  })
-
-  test('locale strings that reference caller variables still expand', () => {
-    const { subject, text } = render({
-      userName: 'Ada',
-      resetUrl: 'https://x.test/reset',
-    })
-    assert.strictEqual(subject, 'Reset your Pikku App password')
-    assert.ok(text?.includes('Hello Ada.'), text)
-    assert.ok(
-      text?.includes('Choose a new password: https://x.test/reset'),
-      text
-    )
-  })
-
-  test('plain-text outputs are not html escaped', () => {
-    const { text } = render({
-      userName: 'Ada & Bob',
-      resetUrl: 'https://x.test/reset?a=1&b=2',
-    })
-    assert.ok(text?.includes('Hello Ada & Bob.'), text)
-    assert.ok(text?.includes('https://x.test/reset?a=1&b=2'), text)
-  })
-
-  // The recursion bounds are why a malicious partial or locale string cannot
-  // hang the render, and neither is reachable from the generated wrapper's
-  // types — only a template author can trip them.
-  test('a partial that includes itself terminates instead of hanging', () => {
-    const { html } = renderEmail(
-      {
-        ...ASSETS,
-        partials: { loop: '<i>{{> loop}}</i>' },
-        templates: {
-          ...ASSETS.templates,
-          'password-reset': {
-            ...ASSETS.templates['password-reset']!,
-            html: '{{> loop}}',
-          },
-        },
-      },
-      { name: 'password-reset', locale: 'en', data: {} }
-    )
-    assert.equal(html.match(/<i>/g)?.length, 5)
-  })
-
-  test('a locale string that references itself terminates instead of hanging', () => {
-    const { subject } = renderEmail(
-      {
-        ...ASSETS,
-        locales: { en: { loop: 'a{{t.loop}}' } },
-        templates: {
-          ...ASSETS.templates,
-          'password-reset': {
-            ...ASSETS.templates['password-reset']!,
-            subject: '{{t.loop}}',
-          },
-        },
-      },
-      { name: 'password-reset', locale: 'en', data: {} }
-    )
-    // Five trusted passes plus the final substitute pass, and the token the
-    // last one produced is left as text rather than expanded again.
-    assert.equal(subject, 'aaaaaa{{t.loop}}')
-  })
-})
-
-describe('renderEmail lookups', () => {
-  test('an unknown template names itself rather than rendering an empty mail', () => {
-    assert.throws(
-      () => renderEmail(ASSETS, { name: 'nope' }),
-      /Unknown email template: nope/
-    )
-  })
-
-  test('an unknown locale names itself', () => {
-    assert.throws(
-      () => renderEmail(ASSETS, { name: 'password-reset', locale: 'de' }),
-      /Unknown email locale: de/
-    )
-  })
-
-  test('the locale defaults to en', () => {
-    assert.equal(renderEmail(ASSETS, { name: 'password-reset' }).locale, 'en')
-  })
-
-  test('the content hash comes from the rendered locale', () => {
-    assert.equal(render({}).hash, 'content-hash')
-  })
-
-  test('a template with no text produces no text field at all', () => {
-    const result = renderEmail(
-      {
-        ...ASSETS,
-        templates: {
-          'password-reset': {
-            ...ASSETS.templates['password-reset']!,
-            text: '',
-          },
-        },
-      },
-      { name: 'password-reset' }
-    )
-    assert.equal('text' in result, false)
-  })
-})
-
-/**
- * `content` is the layout's slot, not a name a caller may fill. It is the one
- * value written without escaping, because by then it holds a body that has
- * already been rendered and escaped.
- */
-describe('renderEmail treats content as the layout slot only', () => {
-  const assets = (html: string, layout?: string): EmailAssets => ({
-    theme: { appName: 'Shop' },
-    locales: { en: {} },
-    partials: layout ? { layout } : {},
-    templates: {
-      welcome: {
-        html,
-        subject: 'Hi',
-        text: '',
-        variables: [],
-        hashes: {
-          en: {
-            contentHash: 'h',
-            htmlHash: 'h',
-            subjectHash: 'h',
-            textHash: 'h',
-          },
-        },
-      },
-    },
-  })
-
-  test('caller data named content is escaped like any other value', () => {
-    const { html } = renderEmail(assets('<p>{{ content }}</p>'), {
-      name: 'welcome',
-      data: { content: '<img src=x onerror=alert(1)>' },
-    })
-
-    assert.ok(
-      !html.includes('<img src=x'),
-      `caller content must not be written raw, got: ${html}`
-    )
-    assert.match(html, /&lt;img src=x/)
-  })
-
-  test('the layout still receives the rendered body unescaped', () => {
-    const { html } = renderEmail(
-      assets('<p>hello</p>', '<main>{{ content }}</main>'),
-      { name: 'welcome' }
-    )
-
-    assert.equal(html, '<main><p>hello</p></main>')
-  })
-})