@pikku/core 0.12.72 → 0.12.74

package/src/function/abort-scope.test.ts

@@ -0,0 +1,97 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  AbandonedError,
+  beginChanges,
+  getAbortScope,
+  runInAbortScope,
+  type AbortScope,
+} from './abort-scope.js'
+
+describe('beginChanges', () => {
+  test('is a no-op outside a scope, so a function need not know how it was called', async () => {
+    await beginChanges()
+    assert.equal(getAbortScope(), undefined)
+  })
+
+  test('lets the mutation proceed while the caller is still there', async () => {
+    let declared = false
+    const scope: AbortScope = {
+      abandoned: false,
+      onBeginChanges: () => {
+        declared = true
+      },
+    }
+
+    let mutated = false
+    await runInAbortScope(scope, async () => {
+      await beginChanges()
+      mutated = true
+    })
+
+    assert.equal(mutated, true)
+    assert.equal(declared, true)
+  })
+
+  test('stops the mutation when the caller has gone, and reports why', async () => {
+    let mutated = false
+    const scope: AbortScope = { abandoned: true, reason: 'speech' }
+
+    await assert.rejects(
+      () =>
+        runInAbortScope(scope, async () => {
+          await beginChanges()
+          mutated = true
+        }),
+      (error: unknown) => {
+        assert.ok(error instanceof AbandonedError)
+        assert.match(error.message, /speech/)
+        return true
+      }
+    )
+
+    // The whole point: the irreversible line never ran.
+    assert.equal(mutated, false)
+  })
+
+  test('survives the await boundaries a real function has', async () => {
+    // AsyncLocalStorage is the reason this works — the checkpoint is usually
+    // several awaits deep inside helpers that never took the scope as an
+    // argument.
+    const scope: AbortScope = { abandoned: true }
+    const nestedHelper = async () => {
+      await new Promise((resolve) => setImmediate(resolve))
+      await beginChanges()
+    }
+
+    await assert.rejects(
+      () =>
+        runInAbortScope(scope, async () => {
+          await new Promise((resolve) => setImmediate(resolve))
+          return nestedHelper()
+        }),
+      AbandonedError
+    )
+  })
+
+  test('reads the scope live, so an interrupt mid-function is still caught', async () => {
+    let aborted = false
+    const scope: AbortScope = {
+      get abandoned() {
+        return aborted
+      },
+    }
+
+    await assert.rejects(
+      () =>
+        runInAbortScope(scope, async () => {
+          // Plenty of interruptible work happens before the checkpoint.
+          await new Promise((resolve) => setImmediate(resolve))
+          aborted = true
+          await beginChanges()
+        }),
+      AbandonedError
+    )
+  })
+})

package/src/function/abort-scope.ts

@@ -0,0 +1,80 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+/**
+ * Raised by {@link beginChanges} when the caller has gone away before anything
+ * was changed. Distinct from a failure: nothing happened, so there is nothing
+ * to report, retry or apologise for.
+ */
+export class AbandonedError extends Error {
+  constructor(reason?: string) {
+    super(
+      reason
+        ? `Aborted before making changes: ${reason}`
+        : 'Aborted before making changes'
+    )
+    this.name = 'AbandonedError'
+  }
+}
+
+export interface AbortScope {
+  /** Whether whatever asked for this work has gone away. */
+  readonly abandoned: boolean
+  /** Why, when known — an interrupt reason, a disconnect, a cancellation. */
+  readonly reason?: string
+  /** Called by `beginChanges()` once a function commits to mutating. */
+  onBeginChanges?: () => void
+}
+
+/**
+ * The ambient "is my caller still there?" signal.
+ *
+ * Ambient rather than a parameter because the question is the same one for
+ * every wiring — an agent run that was interrupted, an HTTP request whose
+ * client disconnected, a cancelled workflow — and threading it through every
+ * signature would mean changing every function that merely sits between the
+ * wiring and the mutation.
+ */
+const scopeStorage = new AsyncLocalStorage<AbortScope>()
+
+/** Run `fn` with an abort scope that `beginChanges()` will observe. */
+export const runInAbortScope = <T>(scope: AbortScope, fn: () => T): T =>
+  scopeStorage.run(scope, fn)
+
+/** The current scope, if the caller is running inside one. */
+export const getAbortScope = (): AbortScope | undefined =>
+  scopeStorage.getStore()
+
+/**
+ * Declare that everything after this line changes something.
+ *
+ * ```ts
+ * const plan = await computePlan(input)   // interruptible, costs nothing to redo
+ * await beginChanges()
+ * await db.deleteProject(input.projectId) // past the point of no return
+ * ```
+ *
+ * Two things happen here. If the caller has already gone away it throws, so the
+ * mutation never runs and the interrupt is clean — nothing happened, and the
+ * user is told nothing because there is nothing to tell. If the caller is still
+ * there it marks this call as mutating, so an interrupt landing *after* this
+ * point produces an `undelivered` note on the thread rather than silently
+ * discarding work that did happen.
+ *
+ * It throws rather than returning a boolean on purpose: `if (await ...)` invites
+ * ignoring the answer, and the failure mode of ignoring it is a mutation nobody
+ * asked for.
+ *
+ * Entirely cooperative, and safe to call anywhere — outside a scope it is a
+ * no-op, so a function does not need to know how it was invoked. A function
+ * that never calls it keeps the conservative default: if it is not marked
+ * `readonly`, an interrupt assumes it changed something and says so. The tool
+ * that forgot to call this is exactly the one that cannot be assumed harmless.
+ */
+export const beginChanges = async (): Promise<void> => {
+  const scope = scopeStorage.getStore()
+  if (!scope) return
+  if (scope.abandoned) {
+    throw new AbandonedError(scope.reason)
+  }
+  scope.onBeginChanges?.()
+}

package/src/function/function-runner.test.ts

@@ -19,7 +19,6 @@ beforeEach(() => {
   resetPikkuState()
 })
 
-// Helper function to add function with metadata for tests
 const addTestFunction = (funcName: string, funcConfig: any) => {
   addFunction(funcName, funcConfig)
   // Convert tags to middleware metadata (tags are organizational only; they no
@@ -62,7 +61,6 @@ describe('runPikkuFunc - Integration Tests', () => {
     addTagMiddleware('wiringTag', [createMiddleware('wiringTag')])
     addTagMiddleware('funcTag', [createMiddleware('funcTag')])
 
-    // Register function with middleware and tags
     addTestFunction('testFunc', {
       func: async () => {
         executionOrder.push('main')
@@ -235,7 +233,6 @@ describe('runPikkuFunc - Integration Tests', () => {
       await next()
     }
 
-    // Add same middleware to tag and directly
     addTagMiddleware('testTag', [duplicatedMiddleware])
 
     addTestFunction('testFunc', {
@@ -252,7 +249,6 @@ describe('runPikkuFunc - Integration Tests', () => {
       wire: {},
     })
 
-    // Should only execute once due to deduplication
     assert.equal(executionCount, 1)
   })
 
@@ -402,7 +398,6 @@ describe('runPikkuFunc - Integration Tests', () => {
     )
 
     assert.equal(result, 'success')
-    // Permissions run after middleware (middleware can set/modify session)
     assert.deepEqual(executionOrder, [
       'funcMiddleware',
       'funcPermission',
@@ -435,7 +430,6 @@ describe('runPikkuFunc - Integration Tests', () => {
 
     assert.deepEqual(receivedServices, mockServices)
     assert.equal(receivedData, testData)
-    // Check that wire has rpc service and session
     assert.ok(receivedWire.rpc)
     assert.equal(receivedWire.session, undefined)
   })
@@ -452,7 +446,6 @@ describe('runPikkuFunc - Integration Tests', () => {
     })
 
     const asyncCreateWireServices = async () => {
-      // Simulate async service creation
       await new Promise((resolve) => setTimeout(resolve, 1))
       return wireServices
     }

package/src/function/function-runner.ts

@@ -1,9 +1,11 @@
+import { beginChanges } from './abort-scope.js'
 import { runMiddleware, combineMiddleware } from '../middleware-runner.js'
 import {
   combineChannelMiddleware,
   wrapChannelWithMiddleware,
 } from '../wirings/channel/channel-middleware-runner.js'
 import { runPermissions } from '../permissions.js'
+import { withoutSecrets } from '../services/secretless.js'
 import { pikkuState } from '../pikku-state.js'
 import {
   applyDefaultsFromSchema,
@@ -39,6 +41,11 @@ import {
 } from '../services/audit-service.js'
 import { rpcService } from '../wirings/rpc/rpc-runner.js'
 import { getOrCreatePackageSingletonServices } from '../wirings/rpc/addon-runner.js'
+import {
+  resolveAddonAuth,
+  resolveAddonScopes,
+  resolveAddonTagMiddleware,
+} from '../wirings/rpc/wire-addon.js'
 import type { AddonInstance } from '../wirings/rpc/addon-runner.js'
 import { closeWireServices } from '../utils.js'
 
@@ -170,7 +177,8 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
   const resolvedFunctionId = funcMeta.pikkuFuncId ?? funcName
 
-  // For addon packages, get or create their singleton services
+  const keepsSecrets = funcMeta.secretBroker === true
+
   const resolvedSingletonServices = packageName
     ? await getOrCreatePackageSingletonServices(
         packageName,
@@ -179,7 +187,6 @@ export const runPikkuFunc = async <In = any, Out = any>(
       )
     : singletonServices
 
-  // Get the package's createWireServices if available
   let resolvedCreateWireServices = createWireServices
   if (packageName) {
     const factories = pikkuState(packageName, 'package', 'factories')
@@ -203,11 +210,9 @@ export const runPikkuFunc = async <In = any, Out = any>(
         )
       : wire
 
-  // Set up credential wire service early so middleware can use setCredential.
-  // An addon instance with credentialOverrides always gets a fresh alias-aware
-  // service so its logical credential names resolve to instance-specific ones,
-  // even when a parent credential service is already present on the wire.
-  // Otherwise skip if already set up (e.g. addon functions reuse the parent wire).
+  // Set up early so middleware can use setCredential. An addon instance with
+  // credentialOverrides always gets a fresh alias-aware service, even when a
+  // parent credential service is already present on the wire.
   if (addonInstance?.credentialOverrides) {
     // Credentials belong to the consuming project, so resolve them via the
     // project's credentialService (the addon's own singletons may not carry it).
@@ -251,7 +256,6 @@ export const runPikkuFunc = async <In = any, Out = any>(
     invocationWire.addonNamespace = addonInstance.namespace
   }
 
-  // Helper function to run permissions and execute the function
   const executeFunction = async () => {
     await resolveSession(
       invocationWire,
@@ -270,7 +274,11 @@ export const runPikkuFunc = async <In = any, Out = any>(
     const session = invocationWire.session
 
     if (funcMeta.sessionless) {
-      if (wiringAuth === true || funcConfig.auth === true) {
+      if (
+        wiringAuth === true ||
+        funcConfig.auth === true ||
+        resolveAddonAuth(packageName, addonInstance?.namespace)
+      ) {
         if (!session) {
           throw new ForbiddenError('Authentication required')
         }
@@ -290,32 +298,38 @@ export const runPikkuFunc = async <In = any, Out = any>(
       throw new ReadonlySessionError()
     }
 
-    // Scopes gate before the data is evaluated: they depend only on the
-    // session, so a denied request never pays to parse or validate its body.
-    // Scopes are an AND gate and stay separate from runPermissions, which
-    // evaluates the function's own OR-groups against request data.
-    verifyScopes(funcConfig.scopes ?? funcMeta.scopes, session)
+    // Only mutating functions get a checkpoint. A read has nothing to declare,
+    // and offering it there would invite the contradiction of a `readonly`
+    // function announcing where its changes begin.
+    if (!funcMeta.readonly) {
+      invocationWire.beginChanges = beginChanges
+    }
+
+    // knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
+    const addonScopes = resolveAddonScopes(
+      packageName,
+      addonInstance?.namespace
+    )
+    const functionScopes = funcConfig.scopes ?? funcMeta.scopes
+    verifyScopes(
+      addonScopes.length > 0
+        ? [...addonScopes, ...(functionScopes ?? [])]
+        : functionScopes,
+      session
+    )
 
-    // Evaluate the data from the lazy function
     let actualData = await data()
 
-    // Validate and coerce data if schema is defined
     const inputSchemaName = funcMeta.inputSchemaName
     if (inputSchemaName) {
-      // Fill in schema defaults before anything reads the data. Unconditional:
-      // a default belongs to the schema, not to the transport the call arrived
-      // on. Runs before coercion so a defaulted value and a supplied one are
-      // treated identically from here on.
       actualData = applyDefaultsFromSchema(
         inputSchemaName,
         actualData,
         packageName
       )
-      // Coerce (top level) data types before validation (e.g. string→array, string→date)
       if (coerceDataFromSchema) {
         coerceTopLevelDataFromSchema(inputSchemaName, actualData, packageName)
       }
-      // Validate request data against the defined schema, if any
       await validateSchema(
         resolvedSingletonServices.logger,
         resolvedSingletonServices.schema,
@@ -327,7 +341,12 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
     await runPermissions({
       funcPermissions: funcConfig.permissions,
-      services: resolvedSingletonServices,
+      services: keepsSecrets
+        ? resolvedSingletonServices
+        : (withoutSecrets(
+            resolvedSingletonServices,
+            'a permission'
+          ) as CoreSingletonServices),
       wire: invocationWire as any,
       data: actualData,
       packageName,
@@ -344,13 +363,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
         wireServices && Object.keys(wireServices).length > 0
           ? { ...resolvedSingletonServices, ...wireServices }
           : resolvedSingletonServices
-      // The audit gate is per-function, but the auditLog wire service is
-      // created per-transport-invocation — a nested/exposed-RPC call would
-      // otherwise inherit an auditLog constructed while the OUTER wire's
-      // audit was unset (e.g. the generated rpcCaller has no audit config),
-      // silently dropping every write. Re-gate here: if this function
-      // declares audit and the inherited auditLog wasn't built for this
-      // invocation (config identity check), bind a fresh one to this wire.
+      // knowledge: decisions/internals/core-function-runner-restores-the-wire-fields-it-overwrites.md
       if (
         resolvedAuditConfig &&
         resolvedSingletonServices.audit &&
@@ -383,7 +396,11 @@ export const runPikkuFunc = async <In = any, Out = any>(
         configurable: true,
         enumerable: true,
       })
-      return await funcConfig.func(services, actualData, invocationWire)
+      return await funcConfig.func(
+        keepsSecrets ? services : withoutSecrets(services, 'a pikku function'),
+        actualData,
+        invocationWire
+      )
     } finally {
       // Flush the runner-installed audit buffer before wire services close.
       await invocationAuditLog?.close()
@@ -393,9 +410,17 @@ export const runPikkuFunc = async <In = any, Out = any>(
     }
   }
 
+  const addonTagMiddleware = resolveAddonTagMiddleware(
+    packageName,
+    addonInstance?.namespace
+  )
+
   const allMiddleware = combineMiddleware(wireType, wireId, {
     wireInheritedMiddleware: inheritedMiddleware,
-    wireMiddleware,
+    wireMiddleware:
+      addonTagMiddleware.length > 0
+        ? [...addonTagMiddleware, ...(wireMiddleware ?? [])]
+        : wireMiddleware,
     funcInheritedMiddleware: funcMeta.middleware,
     funcMiddleware: funcConfig.middleware,
     packageName,
@@ -447,5 +472,10 @@ export const runPikkuFunc = async <In = any, Out = any>(
     } else {
       invocationWire.audit = previousAudit
     }
+    if (previousAddonNamespace === undefined) {
+      delete (invocationWire as any).addonNamespace
+    } else {
+      invocationWire.addonNamespace = previousAddonNamespace
+    }
   }
 }