@pikku/core 0.12.107 → 0.12.112

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

@@ -1,93 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert'
-import { ScopedSecretService } from './scoped-secret-service.js'
-
-const createMockSecrets = () => ({
-  getSecret: async <T>(key: string) => ({ key }) as T,
-  hasSecret: async () => true,
-  setSecret: async () => {},
-  deleteSecret: async () => {},
-  getSecrets: async <T>(keys: string[]) =>
-    Object.fromEntries(keys.map((key) => [key, { key }])) as T,
-})
-
-describe('ScopedSecretService', () => {
-  test('should allow access to allowed keys', async () => {
-    const mock = createMockSecrets()
-    const scoped = new ScopedSecretService(mock, new Set(['KEY1', 'KEY2']))
-    const result = await scoped.getSecret('KEY1')
-    assert.deepStrictEqual(result, { key: 'KEY1' })
-  })
-
-  test('should deny access to non-allowed keys', async () => {
-    const mock = createMockSecrets()
-    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
-    await assert.rejects(() => scoped.getSecret('KEY2'), {
-      message: 'Access denied to secret key: KEY2',
-    })
-  })
-
-  test('should allow getSecret for allowed keys', async () => {
-    const mock = createMockSecrets()
-    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
-    const result = await scoped.getSecret('KEY1')
-    assert.deepStrictEqual(result, { key: 'KEY1' })
-  })
-
-  test('should deny getSecret for non-allowed keys', async () => {
-    const mock = createMockSecrets()
-    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
-    await assert.rejects(() => scoped.getSecret('FORBIDDEN'), {
-      message: 'Access denied to secret key: FORBIDDEN',
-    })
-  })
-
-  test('should allow hasSecret for allowed keys', async () => {
-    const mock = createMockSecrets()
-    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
-    const result = await scoped.hasSecret('KEY1')
-    assert.strictEqual(result, true)
-  })
-
-  test('should deny hasSecret for non-allowed keys', async () => {
-    const mock = createMockSecrets()
-    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
-    await assert.rejects(() => scoped.hasSecret('KEY2'), {
-      message: 'Access denied to secret key: KEY2',
-    })
-  })
-
-  test('should return batch secrets for allowed keys', async () => {
-    const mock = createMockSecrets()
-    const scoped = new ScopedSecretService(mock, new Set(['KEY1', 'KEY2']))
-    const result = await scoped.getSecrets(['KEY1', 'KEY2'])
-    assert.deepStrictEqual(result, {
-      KEY1: { key: 'KEY1' },
-      KEY2: { key: 'KEY2' },
-    })
-  })
-
-  test('should reject batch getSecrets when any key is not allowed', async () => {
-    const mock = createMockSecrets()
-    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
-    await assert.rejects(() => scoped.getSecrets(['KEY1', 'KEY2']), {
-      message: 'Access denied to secret key: KEY2',
-    })
-  })
-
-  test('should always throw on setSecret', async () => {
-    const mock = createMockSecrets()
-    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
-    await assert.rejects(() => scoped.setSecret('KEY1', 'val'), {
-      message: 'setSecret is not allowed in scoped secret service',
-    })
-  })
-
-  test('should always throw on deleteSecret', async () => {
-    const mock = createMockSecrets()
-    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
-    await assert.rejects(() => scoped.deleteSecret('KEY1'), {
-      message: 'deleteSecret is not allowed in scoped secret service',
-    })
-  })
-})

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

@@ -1,40 +0,0 @@
-import type { SecretValue } from '../classification/secret-value.js'
-import type { SecretService, SecretValues } from './secret-service.js'
-
-export class ScopedSecretService implements SecretService {
-  constructor(
-    private secrets: SecretService,
-    private allowedKeys: Set<string>
-  ) {}
-
-  private assertAllowed(key: string): void {
-    if (!this.allowedKeys.has(key)) {
-      throw new Error(`Access denied to secret key: ${key}`)
-    }
-  }
-
-  async getSecret<T = string>(key: string): Promise<SecretValue<T>> {
-    this.assertAllowed(key)
-    return this.secrets.getSecret<T>(key)
-  }
-
-  async hasSecret(key: string): Promise<boolean> {
-    this.assertAllowed(key)
-    return this.secrets.hasSecret(key)
-  }
-
-  async setSecret(_key: string, _value: unknown): Promise<void> {
-    throw new Error('setSecret is not allowed in scoped secret service')
-  }
-
-  async deleteSecret(_key: string): Promise<void> {
-    throw new Error('deleteSecret is not allowed in scoped secret service')
-  }
-
-  async getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(
-    keys: (keyof T & string)[]
-  ): Promise<Partial<SecretValues<T>>> {
-    keys.forEach((k) => this.assertAllowed(k))
-    return this.secrets.getSecrets<T>(keys)
-  }
-}

package/src/services/secret-host-binding.test.ts

@@ -1,138 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import {
-  SecretHostNotAllowedError,
-  assertSecretAllowedForHost,
-} from './secret-host-binding.js'
-import type { SecretDefinitionsMeta } from '../wirings/secret/secret.types.js'
-
-const definitions: SecretDefinitionsMeta = {
-  notion: {
-    name: 'notion',
-    displayName: 'Notion',
-    secretId: 'NOTION_KEY',
-    allowedHosts: ['api.notion.com'],
-  },
-  stripe: {
-    name: 'stripe',
-    displayName: 'Stripe',
-    secretId: 'STRIPE_KEY',
-    allowedHosts: ['*.stripe.com'],
-  },
-  legacy: {
-    name: 'legacy',
-    displayName: 'Legacy',
-    secretId: 'LEGACY_KEY',
-  },
-}
-
-describe('assertSecretAllowedForHost', () => {
-  test('allows a declared host', () => {
-    assertSecretAllowedForHost(
-      'NOTION_KEY',
-      'https://api.notion.com/v1/pages',
-      definitions
-    )
-  })
-
-  test('refuses a host the secret was not declared for', () => {
-    assert.throws(
-      () =>
-        assertSecretAllowedForHost(
-          'NOTION_KEY',
-          'https://attacker.test/collect',
-          definitions
-        ),
-      SecretHostNotAllowedError
-    )
-  })
-
-  test('never puts the secret value in the message', () => {
-    assert.throws(
-      () =>
-        assertSecretAllowedForHost(
-          'NOTION_KEY',
-          'https://attacker.test/',
-          definitions
-        ),
-      (error: Error) =>
-        error.message.includes('NOTION_KEY') &&
-        error.message.includes('attacker.test')
-    )
-  })
-
-  test('matches a subdomain wildcard', () => {
-    assertSecretAllowedForHost(
-      'STRIPE_KEY',
-      'https://api.stripe.com/v1/charges',
-      definitions
-    )
-  })
-
-  test('anchors the wildcard on a dot, so a suffix lookalike is refused', () => {
-    assert.throws(
-      () =>
-        assertSecretAllowedForHost(
-          'STRIPE_KEY',
-          'https://stripe.com.attacker.test/',
-          definitions
-        ),
-      SecretHostNotAllowedError
-    )
-  })
-
-  test('a bare domain does not match its own subdomain wildcard', () => {
-    assert.throws(
-      () =>
-        assertSecretAllowedForHost(
-          'STRIPE_KEY',
-          'https://stripe.com/',
-          definitions
-        ),
-      SecretHostNotAllowedError
-    )
-  })
-
-  test('is case insensitive on the host', () => {
-    assertSecretAllowedForHost(
-      'NOTION_KEY',
-      'https://API.NOTION.COM/v1',
-      definitions
-    )
-  })
-
-  test('an undeclared secret is unrestricted by default', () => {
-    assertSecretAllowedForHost(
-      'LEGACY_KEY',
-      'https://anywhere.test/',
-      definitions
-    )
-    assertSecretAllowedForHost(
-      'UNKNOWN_KEY',
-      'https://anywhere.test/',
-      definitions
-    )
-  })
-
-  test('requireAllowedHosts refuses a secret that declares none', () => {
-    assert.throws(
-      () =>
-        assertSecretAllowedForHost(
-          'LEGACY_KEY',
-          'https://anywhere.test/',
-          definitions,
-          true
-        ),
-      SecretHostNotAllowedError
-    )
-  })
-
-  test('requireAllowedHosts still allows a declared pairing', () => {
-    assertSecretAllowedForHost(
-      'NOTION_KEY',
-      'https://api.notion.com/v1',
-      definitions,
-      true
-    )
-  })
-})

package/src/services/secret-host-binding.ts

@@ -1,51 +0,0 @@
-import type { SecretDefinitionsMeta } from '../wirings/secret/secret.types.js'
-
-export class SecretHostNotAllowedError extends Error {
-  constructor(
-    public readonly secretId: string,
-    public readonly host: string,
-    allowedHosts: string[] | undefined
-  ) {
-    super(
-      allowedHosts?.length
-        ? `Secret '${secretId}' may not be sent to '${host}' — it is declared for ${allowedHosts.map((h) => `'${h}'`).join(', ')}. Add the host to allowedHosts on its defineSecret if this is intended.`
-        : `Secret '${secretId}' has no allowedHosts and this project requires one. Declare the hosts it may be sent to on its defineSecret.`
-    )
-    this.name = 'SecretHostNotAllowedError'
-  }
-}
-
-/** Exact match, or a single leading `*.` wildcard anchored on a dot. */
-const hostMatches = (host: string, pattern: string): boolean => {
-  const h = host.toLowerCase()
-  const p = pattern.toLowerCase()
-  if (p.startsWith('*.')) {
-    return h.endsWith(p.slice(1)) && h.length > p.length - 1
-  }
-  return h === p
-}
-
-/** Refuses a secret/host pairing the declarations do not permit. */
-export const assertSecretAllowedForHost = (
-  secretId: string,
-  url: string | URL,
-  secretDefinitions: SecretDefinitionsMeta | undefined,
-  requireAllowedHosts = false
-): void => {
-  const host = (typeof url === 'string' ? new URL(url) : url).hostname
-  const definition = Object.values(secretDefinitions ?? {}).find(
-    (d) => d.secretId === secretId
-  )
-  const allowedHosts = definition?.allowedHosts
-
-  if (!allowedHosts?.length) {
-    if (requireAllowedHosts) {
-      throw new SecretHostNotAllowedError(secretId, host, allowedHosts)
-    }
-    return
-  }
-
-  if (!allowedHosts.some((pattern) => hostMatches(host, pattern))) {
-    throw new SecretHostNotAllowedError(secretId, host, allowedHosts)
-  }
-}

package/src/services/secret-service.ts

@@ -1,25 +0,0 @@
-import type { SecretValue } from '../classification/secret-value.js'
-
-/** A record of secrets, each still wrapped. */
-export type SecretValues<T> = { [K in keyof T]: SecretValue<T[K]> }
-
-export interface SecretService {
-  /**
-   * Throws if the secret is not found, unless `defineSecret` declared it
-   * `optional` — then absence resolves `undefined`. Unwrap the result with
-   * `.reveal()`.
-   */
-  getSecret<T = string>(key: string): Promise<SecretValue<T>>
-  /** Answers for any key, including a disallowed one — it must not throw. */
-  hasSecret(key: string): Promise<boolean>
-  setSecret(key: string, value: unknown): Promise<void>
-  deleteSecret(key: string): Promise<void>
-  /**
-   * Missing keys are omitted rather than throwing, hence `Partial<T>`: callers
-   * must handle keys absent at runtime. Pass a shape as `T` to avoid casting,
-   * e.g. `getSecrets<{ FOO: string; BAR: { id: string } }>(['FOO', 'BAR'])`.
-   */
-  getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(
-    keys: (keyof T & string)[]
-  ): Promise<Partial<SecretValues<T>>>
-}

package/src/services/secretless.test.ts

@@ -1,54 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import { SecretAccessDeniedError, withoutSecrets } from './secretless.js'
-
-const services = () => ({
-  logger: { info: () => {} },
-  secrets: { getSecret: async () => 'super-secret' },
-  db: { query: async () => [] },
-})
-
-describe('withoutSecrets', () => {
-  test('throws when secrets is read', () => {
-    const stripped = withoutSecrets(services(), 'a pikku function') as any
-    assert.throws(() => stripped.secrets, SecretAccessDeniedError)
-  })
-
-  test('throws when secrets is destructured, at the point of the mistake', () => {
-    const stripped = withoutSecrets(services(), 'a pikku function') as any
-    assert.throws(() => {
-      const { secrets } = stripped
-      return secrets
-    }, SecretAccessDeniedError)
-  })
-
-  test('names the context so the message points somewhere', () => {
-    const stripped = withoutSecrets(services(), 'a permission') as any
-    assert.throws(
-      () => stripped.secrets,
-      (error: Error) => error.message.includes('a permission')
-    )
-  })
-
-  test('leaves every other service reachable', () => {
-    const stripped = withoutSecrets(services(), 'a pikku function')
-    assert.ok(stripped.logger)
-    assert.ok(stripped.db)
-  })
-
-  test('does not mutate the original services object', async () => {
-    const original = services()
-    withoutSecrets(original, 'a pikku function')
-    assert.equal(await original.secrets.getSecret(), 'super-secret')
-  })
-
-  test('is a no-op when there is no secrets service', () => {
-    const bare = { logger: {} }
-    assert.equal(withoutSecrets(bare, 'a pikku function'), bare)
-  })
-
-  test('does not leak the value through spreading', () => {
-    const stripped = withoutSecrets(services(), 'a pikku function')
-    assert.equal('secrets' in { ...stripped }, false)
-  })
-})

package/src/services/secretless.ts

@@ -1,29 +0,0 @@
-import type { SecretlessServices } from '../types/core.types.js'
-
-export class SecretAccessDeniedError extends Error {
-  constructor(context: string) {
-    super(
-      `'secrets' is not available inside ${context}. SecretService is confined to pikkuServices, pikkuWireServices, addon service factories and middleware — give a service the secret when you construct it and ask that service here.`
-    )
-    this.name = 'SecretAccessDeniedError'
-  }
-}
-
-/** Returns `services` with `secrets` replaced by a throwing accessor. */
-export const withoutSecrets = <T extends object>(
-  services: T,
-  context: string
-): SecretlessServices<T> => {
-  if (!('secrets' in services)) {
-    return services as SecretlessServices<T>
-  }
-  const stripped = { ...services } as Record<string, unknown>
-  Object.defineProperty(stripped, 'secrets', {
-    get() {
-      throw new SecretAccessDeniedError(context)
-    },
-    configurable: true,
-    enumerable: false,
-  })
-  return stripped as SecretlessServices<T>
-}

package/src/services/session-store.ts

@@ -1,9 +0,0 @@
-import type { CoreUserSession } from '../types/core.types.js'
-
-export interface SessionStore<
-  UserSession extends CoreUserSession = CoreUserSession,
-> {
-  get(pikkuUserId: string): Promise<UserSession | undefined>
-  set(pikkuUserId: string, session: UserSession): Promise<void>
-  clear(pikkuUserId: string): Promise<void>
-}

package/src/services/stub-tracker.test.ts

@@ -1,104 +0,0 @@
-import { describe, test, beforeEach, afterEach } from 'node:test'
-import assert from 'node:assert/strict'
-import {
-  StubTracker,
-  stub,
-  spy,
-  isTestRun,
-  getStubTracker,
-} from './stub-tracker.js'
-
-describe('StubTracker', () => {
-  test('records calls and exposes them via getCalls', () => {
-    const tracker = new StubTracker()
-    tracker.record('email', 'send', [{ to: 'a@b.c' }])
-    tracker.record('payments', 'charge', [{ amount: 5 }])
-
-    assert.equal(tracker.getCalls().length, 2)
-    const emailCalls = tracker.getCalls('email')
-    assert.equal(emailCalls.length, 1)
-    assert.deepEqual(emailCalls[0], {
-      service: 'email',
-      method: 'send',
-      args: [{ to: 'a@b.c' }],
-    })
-  })
-
-  test('reset clears recorded calls and strict-mode touches', () => {
-    const tracker = new StubTracker()
-    tracker.record('email', 'send', [])
-    tracker.reset()
-    assert.equal(tracker.getCalls().length, 0)
-    tracker.verify()
-  })
-
-  test('legacy stub() proxy records through the same tracker', async () => {
-    const tracker = new StubTracker()
-    const email = tracker.stub<{ send: (msg: unknown) => Promise<void> }>(
-      'email'
-    )
-    await email.send({ to: 'x@y.z' })
-    assert.deepEqual(tracker.getCalls('email')[0]?.args, [{ to: 'x@y.z' }])
-    tracker.assert('email', 'send')
-  })
-})
-
-describe('stub/spy core utils', () => {
-  beforeEach(() => getStubTracker().reset())
-
-  test('stub() records into the default tracker and uses the implementation', async () => {
-    const email = stub<{ send: (msg: unknown) => Promise<{ ok: boolean }> }>(
-      'email',
-      { send: async () => ({ ok: true }) }
-    )
-    const result = await email.send({ to: 'a@b.c' })
-    assert.deepEqual(result, { ok: true })
-    assert.deepEqual(getStubTracker().getCalls('email')[0], {
-      service: 'email',
-      method: 'send',
-      args: [{ to: 'a@b.c' }],
-    })
-  })
-
-  test('stub() without an implementation resolves undefined', async () => {
-    const payments = stub<{ charge: (x: unknown) => Promise<unknown> }>(
-      'payments'
-    )
-    assert.equal(await payments.charge({ amount: 5 }), undefined)
-    assert.equal(getStubTracker().getCalls('payments').length, 1)
-  })
-
-  test('spy() records calls and passes through to the real service', async () => {
-    let realCalled = 0
-    const real = {
-      config: { retries: 3 },
-      send: async (msg: { to: string }) => {
-        realCalled++
-        return { delivered: msg.to }
-      },
-    }
-    const email = spy('email', real)
-
-    assert.deepEqual(await email.send({ to: 'a@b.c' }), {
-      delivered: 'a@b.c',
-    })
-    assert.equal(realCalled, 1)
-    assert.equal(email.config.retries, 3)
-    assert.equal(getStubTracker().getCalls('email').length, 1)
-  })
-})
-
-describe('isTestRun', () => {
-  const original = process.env.PIKKU_TEST_RUN
-  afterEach(() => {
-    if (original === undefined) delete process.env.PIKKU_TEST_RUN
-    else process.env.PIKKU_TEST_RUN = original
-  })
-
-  test('reflects the PIKKU_TEST_RUN environment variable', () => {
-    delete process.env.PIKKU_TEST_RUN
-    assert.equal(isTestRun(), false)
-    process.env.PIKKU_TEST_RUN = 'true'
-    assert.equal(isTestRun(), true)
-  })
-})