@pikku/core 0.12.106 → 0.12.111

package/src/app-leaf-surface.test.ts

@@ -1,222 +0,0 @@
-import { test, describe } from 'node:test'
-import * as assert from 'assert'
-import ts from 'typescript'
-import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
-import { dirname, join, relative } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-/**
- * `#pikku` is the app tier's only door onto Pikku, and it is a namespace rather
- * than a module: `#pikku/http`, `#pikku/workflow`, one subpath per wiring.
- *
- * The bare specifier used to resolve to `.pikku/pikku-types.gen.ts`, which
- * re-exported all twelve wiring leaves with `export *` — undoing the split the
- * leaves exist for, each of which still says so in its own header ("HTTP-specific
- * type definitions for tree-shaking optimization"). Reaching that barrel put 33
- * distinct `@pikku/core` subpaths into the module graph, and neither of the two
- * consumers could drop them again: bundlers keep `export *` chains because the
- * app declares no `sideEffects`, and Node and tsx do not tree-shake at all, so
- * an app with no queues still executed `@pikku/core/queue` at boot.
- *
- * Deleting the barrel also turns the addon boundary from advice into a rule. An
- * addon's leaves are never generated, so `#pikku/http` fails to resolve at the
- * specifier rather than yielding "no exported member" from a hub that quietly
- * dropped the re-export.
- */
-const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..')
-
-/**
- * Membership is discovered, not listed: every directory holding a
- * `pikku.config.json` is a Pikku project, so a project added later arrives
- * guarded rather than invisible. Listing them by hand is how an earlier
- * version of this guard reported green on four packages it had never scanned.
- */
-const skipped = new Set([
-  'node_modules',
-  'dist',
-  '.pikku',
-  '.next',
-  'build',
-  '.git',
-  'coverage',
-  // Agent scratch worktrees are whole Pikku projects generated by whatever CLI
-  // version happened to scaffold them, so discovery finds them and reports a
-  // barrel this repo does not own. They are gitignored and belong to no
-  // workspace, which is what makes them out of scope rather than merely noisy.
-  '.claude',
-])
-
-const findProjects = (dir: string, out: string[] = []): string[] => {
-  for (const entry of readdirSync(dir)) {
-    if (skipped.has(entry)) continue
-    const path = join(dir, entry)
-    if (!statSync(path).isDirectory()) continue
-    if (existsSync(join(path, 'pikku.config.json'))) out.push(path)
-    findProjects(path, out)
-  }
-  return out
-}
-
-const walk = (dir: string, out: string[] = []): string[] => {
-  for (const entry of readdirSync(dir)) {
-    if (skipped.has(entry)) continue
-    const path = join(dir, entry)
-    if (statSync(path).isDirectory()) walk(path, out)
-    else if (path.endsWith('.ts') || path.endsWith('.tsx')) out.push(path)
-  }
-  return out
-}
-
-/**
- * `.gen.*` and `.d.ts` are the generator's own output — what they import is
- * decided by the codegen templates, and `.pikku` is skipped outright.
- */
-const isGenerated = (path: string) =>
-  path.includes('.gen.') || path.endsWith('.d.ts')
-
-const projectSourceFiles = (project: string) => {
-  const files: string[] = []
-  for (const entry of readdirSync(project)) {
-    if (skipped.has(entry)) continue
-    const path = join(project, entry)
-    if (!statSync(path).isDirectory()) continue
-    if (existsSync(join(path, 'pikku.config.json'))) continue
-    walk(path, files)
-  }
-  return files.filter((file) => !isGenerated(file))
-}
-
-/**
- * Parsed rather than grepped: the CLI's serializers hold the specifiers they
- * emit inside template literals, and those are output text rather than imports
- * the CLI itself makes.
- */
-const barrelSpecifiers = (file: string) => {
-  const source = ts.createSourceFile(
-    file,
-    readFileSync(file, 'utf8'),
-    ts.ScriptTarget.Latest,
-    true
-  )
-  const found: { specifier: string; line: number }[] = []
-  for (const statement of source.statements) {
-    if (
-      !ts.isImportDeclaration(statement) &&
-      !ts.isExportDeclaration(statement)
-    ) {
-      continue
-    }
-    const moduleSpecifier = statement.moduleSpecifier
-    if (!moduleSpecifier || !ts.isStringLiteral(moduleSpecifier)) continue
-    const specifier = moduleSpecifier.text
-    const isBarrel =
-      specifier === '#pikku' ||
-      /^#pikku\/pikku-types\.gen(\.js)?$/.test(specifier)
-    if (!isBarrel) continue
-    const { line } = source.getLineAndCharacterOfPosition(
-      statement.getStart(source)
-    )
-    found.push({ specifier, line: line + 1 })
-  }
-  return found
-}
-
-/**
- * Names a leaf carries, mapped to the leaf that carries them. An app reaching
- * `@pikku/core` for one of these is the smell that says the generator is not
- * emitting something it should — the definer is already generated into the
- * project's own `.pikku`, so naming core instead couples the app to a package
- * it otherwise never imports.
- */
-const namesOwnedByALeaf = new Map<string, string>([
-  ['defineCredential', '#pikku/auth'],
-  ['defineSecret', '#pikku/secrets'],
-  ['defineVariable', '#pikku/variables'],
-  ['defineScope', '#pikku/scopes'],
-  ['defineSystemRole', '#pikku/scopes'],
-  ['cors', '#pikku/middleware'],
-  ['InvalidOriginError', '#pikku/error'],
-])
-
-const coreNamesThatHaveALeaf = (file: string) => {
-  const source = ts.createSourceFile(
-    file,
-    readFileSync(file, 'utf8'),
-    ts.ScriptTarget.Latest,
-    true
-  )
-  const found: { name: string; leaf: string; line: number }[] = []
-  for (const statement of source.statements) {
-    if (!ts.isImportDeclaration(statement)) continue
-    const moduleSpecifier = statement.moduleSpecifier
-    if (!ts.isStringLiteral(moduleSpecifier)) continue
-    if (!/^@pikku\/core(\/|$)/.test(moduleSpecifier.text)) continue
-
-    const bindings = statement.importClause?.namedBindings
-    if (!bindings || !ts.isNamedImports(bindings)) continue
-    for (const element of bindings.elements) {
-      const name = (element.propertyName ?? element.name).text
-      const leaf = namesOwnedByALeaf.get(name)
-      if (!leaf) continue
-      const { line } = source.getLineAndCharacterOfPosition(
-        element.getStart(source)
-      )
-      found.push({ name, leaf, line: line + 1 })
-    }
-  }
-  return found
-}
-
-describe('app leaf surface', () => {
-  test('no Pikku project reaches past a leaf for a name the leaf carries', () => {
-    const projects = findProjects(repoRoot)
-    assert.ok(projects.length > 0, 'expected to discover Pikku projects')
-
-    // A project nested inside another (an addon under `e2e/packages`) is
-    // discovered on its own account and again as its parent's source, so the
-    // same offence is reached twice.
-    const offenders = new Set<string>()
-    for (const project of projects) {
-      for (const file of projectSourceFiles(project)) {
-        for (const { name, leaf, line } of coreNamesThatHaveALeaf(file)) {
-          offenders.add(
-            `${relative(repoRoot, file)}:${line}  ${name} — import it from '${leaf}'`
-          )
-        }
-      }
-    }
-
-    assert.deepStrictEqual(
-      [...offenders].sort(),
-      [],
-      `An app developer imports from '#pikku/<leaf>'. Reaching past it to ` +
-        `'@pikku/core' for a name the leaf already carries is the smell that ` +
-        `says the generator is not emitting something it should.\n\n` +
-        [...offenders].sort().join('\n')
-    )
-  })
-
-  test('no Pikku project reaches the app tier through a barrel', () => {
-    const projects = findProjects(repoRoot)
-    assert.ok(projects.length > 0, 'expected to discover Pikku projects')
-
-    const offenders: string[] = []
-    for (const project of projects) {
-      for (const file of projectSourceFiles(project)) {
-        for (const { specifier, line } of barrelSpecifiers(file)) {
-          offenders.push(`${relative(repoRoot, file)}:${line}  ${specifier}`)
-        }
-      }
-    }
-
-    assert.deepStrictEqual(
-      offenders,
-      [],
-      `The app tier reaches Pikku through one subpath per wiring — ` +
-        `'#pikku/http', '#pikku/workflow', '#pikku/function'.\n` +
-        `A barrel import pulls every wiring's core dependencies into the ` +
-        `module graph, and nothing downstream can drop them again.\n\n` +
-        offenders.join('\n')
-    )
-  })
-})

package/src/bootstrap-compat/root.ts

@@ -1,20 +0,0 @@
-/**
- * Bootstrap compatibility, not a public entry point.
- *
- * The package root carried a 206-name barrel; it is gone, and every name now
- * lives on the subpath that owns it. What is left here is the handful of types
- * the CLI pinned in `packages/cli/build.sh` still writes into the files it
- * generates for the CLI itself — an unresolved type there is a silent `any` in
- * the CLI's own generated surface, not a build failure, which is why this
- * exists rather than letting it break loudly.
- *
- * `bootstrap-compat.test.ts` fails if the pinned CLI's output drifts from this
- * list. Delete this file and its `exports` entry once the pin moves to a CLI
- * released from this branch.
- */
-export type { PikkuWire, SecretlessServices } from '../types/core.types.js'
-export type { CorePikkuMiddleware } from '../middleware/middleware.types.js'
-export type { PickRequired } from '../utils.js'
-export type { CorePermissionGroup } from '../function/functions.types.js'
-export type { ListInput, ListOutput } from '../function/list.types.js'
-export type { SecretService } from '../services/secret-service.js'

package/src/classification/column-form.test.ts

@@ -1,97 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import {
-  hashToken,
-  unsafeAsHashed,
-  unsafeAsSealed,
-  unsafeAsWrapped,
-} from './column-form.js'
-import type {
-  HashedValue,
-  SealedValue,
-  WrappedValue,
-} from './data-classification.js'
-import { deriveKEK, envelopeEncrypt, envelopeRewrap } from '../crypto-utils.js'
-
-const KEY_MATERIAL = 'x'.repeat(32)
-
-describe('hashToken', () => {
-  test('is the sha256 of the input, lowercase hex', async () => {
-    // Known vector, so a refactor of the hex encoding cannot quietly change
-    // what every stored hash in every downstream database means.
-    assert.equal(
-      await hashToken('abc'),
-      'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad'
-    )
-  })
-
-  test('is stable across calls', async () => {
-    assert.equal(await hashToken('token'), await hashToken('token'))
-  })
-
-  test('separates different inputs', async () => {
-    assert.notEqual(await hashToken('a'), await hashToken('b'))
-  })
-})
-
-describe('the form brands', () => {
-  test('a plain string is not assignable to any of them', () => {
-    // @ts-expect-error plaintext cannot be written to a wrapped column
-    const wrapped: WrappedValue = 'not-ciphertext'
-    // @ts-expect-error plaintext cannot be written to a sealed column
-    const sealed: SealedValue = 'not-ciphertext'
-    // @ts-expect-error a raw token cannot be written where its hash belongs
-    const hashed: HashedValue = 'raw-token'
-    assert.ok(wrapped && sealed && hashed)
-  })
-
-  test('the three do not substitute for one another', () => {
-    const wrapped = unsafeAsWrapped('ct')
-    // @ts-expect-error a value fabric cannot read is not one it can
-    const asWrapped: WrappedValue = unsafeAsSealed('ct')
-    // @ts-expect-error a digest is not ciphertext
-    const asHashed: HashedValue = wrapped
-    assert.ok(asWrapped && asHashed)
-  })
-
-  test('but each still widens to string, so reads and query operands are unaffected', () => {
-    const asString: string = unsafeAsWrapped('ct')
-    assert.equal(asString, 'ct')
-    assert.equal(`${unsafeAsHashed('abc')}`, 'abc')
-  })
-})
-
-describe('the envelope primitives produce the brand', () => {
-  test('envelopeEncrypt returns ciphertext that is writable to a wrapped column', async () => {
-    const kek = await deriveKEK(KEY_MATERIAL, 'c2FsdA')
-    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, 'value')
-    // No cast: this is the whole mechanism — the only way to satisfy the
-    // column type is to have actually encrypted something.
-    const forColumn: WrappedValue = ciphertext
-    const dekForColumn: WrappedValue = wrappedDEK
-    assert.ok(forColumn.length > 0 && dekForColumn.length > 0)
-  })
-
-  test('a rewrapped DEK is still writable, so rotation needs no escape hatch', async () => {
-    const oldKek = await deriveKEK(KEY_MATERIAL, 'c2FsdA')
-    const newKek = await deriveKEK('y'.repeat(32), 'c2FsdA')
-    const { wrappedDEK } = await envelopeEncrypt(oldKek, 'value')
-    const rewrapped: WrappedValue = await envelopeRewrap(
-      oldKek,
-      newKek,
-      wrappedDEK
-    )
-    assert.notEqual(rewrapped, wrappedDEK)
-  })
-
-  test('decrypting accepts a bare string, so reading a row back needs no cast', async () => {
-    const kek = await deriveKEK(KEY_MATERIAL, 'c2FsdA')
-    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, 'value')
-    const { envelopeDecrypt } = await import('../crypto-utils.js')
-    const fromRow: string = ciphertext
-    assert.equal(
-      await envelopeDecrypt<string>(kek, fromRow, wrappedDEK),
-      'value'
-    )
-  })
-})

package/src/classification/column-form.ts

@@ -1,55 +0,0 @@
-// knowledge: decisions/internals/core-column-form-is-an-axis-of-its-own.md
-import type {
-  HashedValue,
-  SealedValue,
-  WrappedValue,
-} from './data-classification.js'
-
-/**
- * SHA-256 of a credential, lowercase hex — the sole producer of `HashedValue`.
- *
- * Deliberately unpeppered. These are high-entropy random bearer tokens, not
- * passwords: there is no candidate set to search, so a pepper would add a key
- * to manage and a rotation story to own while buying nothing. A column holding
- * a *low*-entropy secret is not a `hashed` column — it wants a password KDF and
- * a different type entirely.
- *
- * Async because it runs on WebCrypto rather than `node:crypto`, so the same
- * code path works in a Worker. Callers that hash a bearer token on every
- * request are already async.
- */
-export const hashToken = async (raw: string): Promise<HashedValue> => {
-  const subtle = globalThis.crypto?.subtle
-  if (!subtle) {
-    throw new Error('WebCrypto not available')
-  }
-  const digest = await subtle.digest('SHA-256', new TextEncoder().encode(raw))
-  let hex = ''
-  for (const byte of new Uint8Array(digest)) {
-    hex += byte.toString(16).padStart(2, '0')
-  }
-  return hex as HashedValue
-}
-
-/**
- * Assert that a string already in storage is ciphertext of the given form.
- *
- * The brands exist so that new writes must come from a real encrypt/hash call,
- * but three paths legitimately hold such a value as a bare `string`: a
- * migration backfilling rows written before the column declared its form, a
- * test fixture, and a value arriving over the wire from a service that sealed
- * it elsewhere. Each of those is a promise the caller is making, not something
- * the type system can check — which is why these are named to be greppable and
- * why there is no non-`unsafe` spelling. If one of these appears in ordinary
- * request-handling code, that is the bug.
- */
-export const unsafeAsWrapped = (stored: string): WrappedValue =>
-  stored as WrappedValue
-
-/** See `unsafeAsWrapped`. */
-export const unsafeAsSealed = (stored: string): SealedValue =>
-  stored as SealedValue
-
-/** See `unsafeAsWrapped`. */
-export const unsafeAsHashed = (stored: string): HashedValue =>
-  stored as HashedValue

package/src/classification/data-classification.ts

@@ -1,73 +0,0 @@
-// knowledge: decisions/internals/core-data-classification-brand-is-an-optional-property.md
-export type Private<T> = T & { readonly __classification__?: 'private' }
-export type Pii<T> = T & { readonly __classification__?: 'pii' }
-export type Secret<T> = T & { readonly __classification__?: 'secret' }
-
-export type Classification = 'public' | 'private' | 'pii' | 'secret'
-export type AnonymizeStrategy =
-  'fake:email' | 'fake:name' | 'hash' | 'keep' | null
-
-// knowledge: decisions/internals/core-column-form-is-an-axis-of-its-own.md
-
-/**
- * How a column's bytes are represented at rest, as distinct from how sensitive
- * the value is (`Classification`). The two are independent: a token hash is
- * `secret` + `hashed` and must never be encrypted, because the hash *is* the
- * lookup key; a live bearer token is `secret` + `plain` today and should not be.
- *
- * `wrapped` and `sealed` are siblings rather than one being "encrypted": both
- * are ciphertext, and what separates them is who can read it back. Wrapped is
- * symmetric and the application holds the key. Sealed is asymmetric and the
- * application holds only the public half, so it can write the value and never
- * read it. Storing one where the other is expected is silent, permanent data
- * loss, which is why they are not collapsed into a single `encrypted`.
- */
-export type ColumnForm = 'plain' | 'hashed' | 'wrapped' | 'sealed'
-
-declare const wrappedBrand: unique symbol
-declare const sealedBrand: unique symbol
-declare const hashedBrand: unique symbol
-
-/**
- * Ciphertext under a symmetric key the application holds — the output of
- * `envelopeEncrypt`, `wrapDEK` or `envelopeRewrap`.
- *
- * Unlike `Secret<T>` the brand is REQUIRED, so a plain `string` is not
- * assignable and a column declared `form: 'wrapped'` cannot be written with
- * anything but genuine ciphertext. It stays assignable *to* `string`, so it
- * still works as a query operand and serializes normally — the constraint is on
- * construction, not on use.
- */
-export type WrappedValue = string & { readonly [wrappedBrand]: true }
-
-/** Ciphertext under a public key whose private half the application does not
- *  hold. Deliberately not assignable to `WrappedValue`: writing one where the
- *  other belongs produces a row nobody can ever open. */
-export type SealedValue = string & { readonly [sealedBrand]: true }
-
-/** A one-way digest of a secret input. The brand's job is narrow — stop a *raw*
- *  credential being written into the column that should hold its hash. */
-export type HashedValue = string & { readonly [hashedBrand]: true }
-
-export interface ColumnClassification {
-  classification: Classification
-  anonymize_strategy: AnonymizeStrategy
-  /** At-rest representation. Absent means `plain`. */
-  form?: ColumnForm
-  /**
-   * Which key protects this column, for a `wrapped` or `sealed` form. Absent
-   * means the deployment's default key.
-   *
-   * It is a purpose, not a tenant: naming one here says "these columns open
-   * together and separately from the rest", so the key that opens notes need
-   * not open credentials. The id is stored in the value, so a column that
-   * changes key is a rewrap rather than a migration.
-   */
-  keyId?: string
-  description?: string
-}
-
-export type ClassificationManifest = {
-  version: 1
-  tables: Record<string, Record<string, ColumnClassification>>
-}

package/src/classification/index.ts

@@ -1,40 +0,0 @@
-/**
- * What a value is, and how it must be handled: the classification brands a
- * column carries, the stored forms those brands map to, and the wrapper that
- * keeps a secret out of a log.
- *
- * These arrived as three entry points — one for the types, one for the
- * runtime helpers, one for `SecretValue` — which is the same subject behind
- * three doors, split by whether a name happens to be a type or a value.
- */
-export type {
-  Private,
-  Pii,
-  Secret,
-  Classification,
-  AnonymizeStrategy,
-  ColumnForm,
-  WrappedValue,
-  SealedValue,
-  HashedValue,
-  ColumnClassification,
-  ClassificationManifest,
-} from './data-classification.js'
-
-export {
-  hashToken,
-  unsafeAsWrapped,
-  unsafeAsSealed,
-  unsafeAsHashed,
-} from './column-form.js'
-
-export {
-  REDACTED,
-  SecretCoercionError,
-  SecretValue,
-  createSecretValue,
-  isSecretValue,
-} from './secret-value.js'
-export type { Safe } from './secret-value.js'
-
-export { DEFAULT_KEY_ID } from './key-ids.js'

package/src/classification/key-ids.ts

@@ -1,2 +0,0 @@
-/** The key a column protects itself with when it names none. */
-export const DEFAULT_KEY_ID = 'default'