@pikku/core 0.12.64 → 0.12.67

package/src/wirings/ai-agent/ai-agent-prepare.test.ts

@@ -5,14 +5,19 @@ import { resetPikkuState, pikkuState } from '../../pikku-state.js'
 import {
   agentSessionScope,
   assertResourceOwner,
+  canAccessThread,
   buildInstructions,
   buildToolDefs,
   createScopedChannel,
   getAddonCredentialRequirements,
+  isOwnedByPrincipal,
   resolveAgent,
   resolveOwnerResourceId,
+  sessionPrincipals,
+  threadOwnerConstraint,
 } from './ai-agent-prepare.js'
 import { ForbiddenError } from '../../errors/errors.js'
+import { pikkuAuth } from '../../function/functions.types.js'
 import type {
   AIStreamChannel,
   AIStreamEvent,
@@ -128,6 +133,33 @@ describe('ai-agent-prepare', () => {
     assert.match(instructions, /When calling a sub-agent/)
   })
 
+  test('buildInstructions joins role, personality and goal in order, blank-line separated', async () => {
+    addAgent('scribe', {
+      role: 'ROLE',
+      personality: 'PERSONALITY',
+      goal: 'GOAL',
+    })
+
+    const instructions = await buildInstructions('scribe', null)
+    assert.equal(instructions, 'ROLE\n\nPERSONALITY\n\nGOAL')
+  })
+
+  test('buildInstructions omits missing sections rather than leaving blank gaps', async () => {
+    addAgent('terse', { role: 'ROLE', goal: 'GOAL' })
+
+    const instructions = await buildInstructions('terse', null)
+    assert.equal(instructions, 'ROLE\n\nGOAL')
+  })
+
+  test('buildInstructions adds no tool or sub-agent guidance when none are configured', async () => {
+    addAgent('bare', { role: 'ROLE', goal: undefined })
+
+    const instructions = await buildInstructions('bare', null)
+    assert.equal(instructions, 'ROLE')
+    assert.doesNotMatch(instructions, /Tool usage rules:/)
+    assert.doesNotMatch(instructions, /When calling a sub-agent/)
+  })
+
   test('createScopedChannel forwards stream events, captures approvals, and suppresses done', () => {
     const events: AIStreamEvent[] = []
     const channel = createScopedChannel(
@@ -398,6 +430,71 @@ describe('ai-agent-prepare', () => {
     })
   })
 
+  /**
+   * The permission's `pikkuAuth` brand survives only on the live objects in the
+   * function config, not on the metadata. Reading the metadata's by-name
+   * reference resolves against a registry nothing populates, so it collects no
+   * predicate and lets every gated tool through — this pins that the live config
+   * is what gets evaluated.
+   */
+  const addFilterAgent = (allow: boolean) => {
+    addAgent('gatekeeper', { tools: ['gated'] })
+    pikkuState(null, 'agent', 'agentsMeta').gatekeeper = {
+      ...pikkuState(null, 'agent', 'agentsMeta').gatekeeper,
+      tools: ['gated'],
+    } as any
+    pikkuState(null, 'rpc', 'meta').gated = 'gated'
+    pikkuState(null, 'function', 'meta').gated = {
+      description: 'Gated tool',
+      permissions: [{ type: 'wire', name: 'mayUse' }],
+      inputSchemaName: 'GatedInput',
+      sessionless: true,
+    } as any
+    pikkuState(null, 'misc', 'schemas').set('GatedInput', {
+      type: 'object',
+      properties: {},
+    })
+    pikkuState(null, 'function', 'functions').set('gated', {
+      func: async () => ({ ok: true }),
+      permissions: { mayUse: pikkuAuth(async () => allow) },
+    } as any)
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: { warn: () => {}, debug: () => {} },
+    } as any)
+  }
+
+  const sessionParams = () =>
+    ({
+      sessionService: { get: async () => ({ userId: 'u1' }) },
+    }) as any
+
+  test('buildToolDefs offers a tool whose live auth predicate passes', async () => {
+    addFilterAgent(true)
+    const { tools } = await buildToolDefs(
+      sessionParams(),
+      new Map<string, string>(),
+      'resource-1',
+      'gatekeeper',
+      null
+    )
+    assert.deepEqual(
+      tools.map((t) => t.name),
+      ['gated']
+    )
+  })
+
+  test('buildToolDefs filters out a tool whose live auth predicate fails', async () => {
+    addFilterAgent(false)
+    const { tools } = await buildToolDefs(
+      sessionParams(),
+      new Map<string, string>(),
+      'resource-1',
+      'gatekeeper',
+      null
+    )
+    assert.deepEqual(tools, [])
+  })
+
   test('buildToolDefs adds a workflow tool that runs the workflow and returns its output', async () => {
     addAgent('planner', { workflows: ['buildReport'] } as any)
     pikkuState(null, 'agent', 'agentsMeta').planner = {
@@ -572,6 +669,84 @@ describe('C2 thread/run ownership + sessionScope', () => {
       assertResourceOwner('user-a:d', 'user-a:d', 'run')
     )
   })
+})
+
+describe('thread-read ownership (session principals)', () => {
+  test('a principal owns its own bare key and any sub-partition of it', () => {
+    assert.equal(isOwnedByPrincipal('alice', 'alice'), true)
+    assert.equal(isOwnedByPrincipal('alice:project-1', 'alice'), true)
+  })
+
+  test('a principal does not own a lookalike prefix', () => {
+    assert.equal(isOwnedByPrincipal('alice-evil:p', 'alice'), false)
+    assert.equal(isOwnedByPrincipal('bob:alice:secret', 'alice'), false)
+  })
+
+  test('the caller may read a thread owned by their userId', () => {
+    assert.equal(canAccessThread('alice:default', { userId: 'alice' }), true)
+  })
+
+  test('the caller may read a thread owned by their orgId', () => {
+    assert.equal(
+      canAccessThread('org-x:default', { userId: 'alice', orgId: 'org-x' }),
+      true
+    )
+  })
+
+  test('cross-user thread reads are refused', () => {
+    assert.equal(canAccessThread('bob:secret', { userId: 'alice' }), false)
+  })
+
+  test('cross-org thread reads are refused', () => {
+    assert.equal(
+      canAccessThread('org-y:d', { userId: 'alice', orgId: 'org-x' }),
+      false
+    )
+  })
+
+  test('a forged owner prefix in the stored id cannot grant access', () => {
+    assert.equal(
+      canAccessThread('bob:alice:secret', { userId: 'alice' }),
+      false
+    )
+  })
+
+  // A deployment with no session has explicitly opted out of authorization
+  // (agent `no-auth`), so there is no ownership model to enforce — matching
+  // resolveOwnerResourceId's own sessionless fallback to a bare resourceId.
+  test('a sessionless deployment has no ownership model and is not gated', () => {
+    assert.equal(canAccessThread('anything', undefined), true)
+    assert.equal(canAccessThread('anything', {}), true)
+  })
+
+  test('sessionPrincipals lists the userId and orgId a caller can read as', () => {
+    assert.deepEqual(sessionPrincipals({ userId: 'alice', orgId: 'org-x' }), [
+      'alice',
+      'org-x',
+    ])
+    assert.deepEqual(sessionPrincipals({ userId: 'alice' }), ['alice'])
+    assert.deepEqual(sessionPrincipals(undefined), [])
+  })
+
+  test('threadOwnerConstraint scopes a session to its principals', () => {
+    assert.deepEqual(
+      threadOwnerConstraint({ userId: 'alice', orgId: 'org-x' }),
+      ['alice', 'org-x']
+    )
+  })
+
+  // undefined, not [] — [] means "match nothing", which would hide every thread
+  // from a no-auth deployment that never had an ownership model to begin with.
+  test('threadOwnerConstraint is undefined for a sessionless caller', () => {
+    assert.equal(threadOwnerConstraint(undefined), undefined)
+    assert.equal(threadOwnerConstraint({}), undefined)
+  })
+})
+
+describe('C2 sessionScope + resume ownership', () => {
+  const params = (session?: Record<string, unknown>) => ({
+    sessionService: { get: () => session } as never,
+  })
 
   test('agentSessionScope reads the declared scope and defaults to user', () => {
     addAgent('scoped-user')

package/src/wirings/ai-agent/ai-agent-prepare.ts

@@ -12,9 +12,10 @@ import type {
 } from './ai-agent.types.js'
 import type { AIAgentRunnerParams } from '../../services/ai-agent-runner-service.js'
 import { PikkuError } from '../../errors/error-handler.js'
-import { checkAuthPermissions } from '../../permissions.js'
+import { checkAuthPermissions, runPermissions } from '../../permissions.js'
 import { AIProviderNotConfiguredError } from '../../errors/errors.js'
 import { ForbiddenError } from '../../errors/errors.js'
+import { verifyScopes } from '../../scopes.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js'
 import type { SessionService } from '../../services/user-session-service.js'
@@ -104,6 +105,72 @@ export function assertResourceOwner(
   }
 }
 
+/** A session's trusted principals, in the order they may be read as. */
+export function sessionPrincipals(
+  session: { userId?: string; orgId?: string } | undefined
+): string[] {
+  return [session?.userId, session?.orgId].filter(
+    (principal): principal is string => Boolean(principal)
+  )
+}
+
+/**
+ * Whether `storedResourceId` belongs to `principal` under the composition
+ * {@link resolveOwnerResourceId} performs — either the bare principal or one of
+ * its `principal:` sub-partitions. The `:` is required so that `alice` does not
+ * match a `alice-evil:…` lookalike.
+ */
+export function isOwnedByPrincipal(
+  storedResourceId: string,
+  principal: string
+): boolean {
+  return (
+    storedResourceId === principal ||
+    storedResourceId.startsWith(`${principal}:`)
+  )
+}
+
+/**
+ * The `owners` constraint to pass to `AgentRunService.listThreads` for a caller.
+ *
+ * Returns `undefined` — not `[]` — for a session with no principal, because an
+ * empty list means "match nothing" whereas a sessionless deployment (agent
+ * `no-auth`) has no ownership model to constrain by. Keeping that carve-out here
+ * rather than at each call site stops it from being re-derived inconsistently.
+ */
+export function threadOwnerConstraint(
+  session: { userId?: string; orgId?: string } | undefined
+): string[] | undefined {
+  const principals = sessionPrincipals(session)
+  return principals.length > 0 ? principals : undefined
+}
+
+/**
+ * Whether a stored thread/run may be read by the caller. Shaped as a predicate
+ * so it can back a `pikkuPermission` — authorization belongs in a function's
+ * `permissions` field, never in its body.
+ *
+ * Unlike {@link assertResourceOwner}, which compares against a single composed
+ * owner key on the run path, this guards the thread-management reads where the
+ * caller supplies only a `threadId` — so ownership has to be derived from the
+ * session rather than from the request.
+ *
+ * A session with no principal means the deployment opted out of authorization
+ * (agent `no-auth`), so there is no ownership model to enforce and access is not
+ * gated — mirroring {@link resolveOwnerResourceId}'s sessionless fallback to a
+ * bare resourceId.
+ */
+export function canAccessThread(
+  storedResourceId: string,
+  session: { userId?: string; orgId?: string } | undefined
+): boolean {
+  const principals = sessionPrincipals(session)
+  if (principals.length === 0) return true
+  return principals.some((principal) =>
+    isOwnedByPrincipal(storedResourceId, principal)
+  )
+}
+
 export type StreamAIAgentOptions = {
   requiresToolApproval?: 'all' | 'explicit' | false
   /**
@@ -266,6 +333,56 @@ export const resolveAgent = (
   throw new Error(`AI agent not found: ${agentName}`)
 }
 
+/**
+ * Enforces an agent's own authorization before it runs: session presence
+ * (`auth`), then `scopes`, then `permissions`.
+ *
+ * The ordering mirrors the function runner — scopes are an AND gate checked
+ * first, so they can only ever narrow access, and a missing scope short-circuits
+ * before any permission function does I/O.
+ *
+ * `auth` follows `pikkuSessionlessFunc` rather than `pikkuFunc`: a session is
+ * required only when `auth: true` is set explicitly. An agent is normally
+ * reached from a function that has already enforced its own auth, and agents are
+ * also run from genuinely sessionless contexts (crons, queue workers), so
+ * requiring a session by default would reject those without adding a meaningful
+ * gate. `scopes` and `permissions` are always enforced when declared.
+ *
+ * Globals are evaluated here too (via {@link runPermissions}) rather than being
+ * assumed to have already run: an agent is reachable from entry points that do
+ * not go through the function runner, and re-evaluating an AND gate of
+ * side-effect-free predicates is idempotent.
+ */
+export async function assertAgentAuthorized(
+  agent: CoreAIAgent,
+  params: RunAIAgentParams,
+  packageName: string | null
+): Promise<void> {
+  const session = params.sessionService
+    ? await params.sessionService.get()
+    : undefined
+
+  if (agent.auth === true && !session) {
+    throw new ForbiddenError('Authentication required')
+  }
+
+  verifyScopes(agent.scopes, session)
+
+  const singletonServices = getSingletonServices()
+  const wire = params.sessionService
+    ? createMiddlewareSessionWireProps(params.sessionService)
+    : { session: undefined }
+
+  await runPermissions({
+    funcPermissions: agent.permissions,
+    services: singletonServices as any,
+    wire: wire as any,
+    data: {},
+    packageName,
+    label: 'agent',
+  })
+}
+
 export async function buildInstructions(
   agentName: string,
   packageName: string | null
@@ -419,11 +536,17 @@ export async function buildToolDefs(
         continue
       }
 
-      // Filter out tools the user doesn't have auth for
+      // Filter out tools the user doesn't have auth for. The `pikkuAuth` brand
+      // only survives on the live permission objects in the function config, so
+      // the check reads those rather than the metadata (whose by-name registry
+      // is never populated, which would let every gated tool through).
       if (fnMeta.permissions?.length) {
         if (!session) continue
+        const funcConfig = pikkuFuncId
+          ? pikkuState(resolvedPkg, 'function', 'functions').get(pikkuFuncId)
+          : undefined
         const allowed = await checkAuthPermissions(
-          fnMeta.permissions,
+          funcConfig?.permissions,
           session,
           singletonServices,
           resolvedPkg
@@ -519,11 +642,13 @@ export async function buildToolDefs(
         continue
       }
 
-      // Filter out sub-agents the user doesn't have auth for
+      // Filter out sub-agents the user doesn't have auth for, reading the live
+      // agent config for the same reason the tool path does.
       if (subMeta.permissions?.length) {
         if (!session) continue
+        const subAgent = pikkuState(null, 'agent', 'agents').get(subAgentName)
         const allowed = await checkAuthPermissions(
-          subMeta.permissions,
+          subAgent?.permissions,
           session,
           singletonServices
         )
@@ -796,6 +921,8 @@ export async function prepareAgentRun(
   const singletonServices = getSingletonServices()
   const { agent, packageName, resolvedName } = resolveAgent(agentName)
 
+  await assertAgentAuthorized(agent, params, packageName)
+
   let agentRunner = singletonServices.aiAgentRunner
   if (!agentRunner) {
     throw new AIProviderNotConfiguredError()

package/src/wirings/ai-agent/ai-agent-resume-authorization.test.ts

@@ -0,0 +1,207 @@
+import { beforeEach, describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  resetPikkuState,
+  pikkuState,
+  setSingletonServices,
+} from '../../pikku-state.js'
+import { resumeAIAgentSync } from './ai-agent-runner.js'
+import { resumeAIAgent } from './ai-agent-stream.js'
+import { clearPermissionsCache } from '../../permissions.js'
+import { ForbiddenError, MissingScopeError } from '../../errors/errors.js'
+import type { CoreAIAgent } from './ai-agent.types.js'
+import type { CoreUserSession } from '../../types/core.types.js'
+
+const logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+} as any
+
+const RUN_ID = 'run-1'
+const TOOL_CALL_ID = 'tc-1'
+
+const suspendedRun = (agentName: string, resourceId: string) => ({
+  id: RUN_ID,
+  agentName,
+  resourceId,
+  threadId: 'thread-1',
+  status: 'suspended',
+  pendingApprovals: [
+    { toolCallId: TOOL_CALL_ID, toolName: 'refund', args: {}, runId: RUN_ID },
+  ],
+  messages: [],
+})
+
+const setup = (agentName: string, resourceId = 'u1') => {
+  const resolved: string[] = []
+  setSingletonServices({
+    logger,
+    aiRunState: {
+      getRun: async () => suspendedRun(agentName, resourceId),
+      resolveApproval: async (toolCallId: string) => {
+        resolved.push(toolCallId)
+      },
+    },
+  } as any)
+  return resolved
+}
+
+const addAgent = (
+  agentName: string,
+  overrides: Partial<CoreAIAgent> = {}
+): CoreAIAgent => {
+  const agent: CoreAIAgent = {
+    name: agentName,
+    description: `${agentName} description`,
+    goal: `${agentName} goal`,
+    model: 'test/test-model',
+    ...overrides,
+  } as CoreAIAgent
+
+  pikkuState(null, 'agent', 'agents').set(agentName, agent)
+  return agent
+}
+
+const sessionService = (session: CoreUserSession | undefined) =>
+  ({
+    get: () => session,
+    setInitial: () => {},
+    sessionChanged: false,
+  }) as any
+
+beforeEach(() => {
+  resetPikkuState()
+  clearPermissionsCache()
+})
+
+describe('resumeAIAgentSync authorization', () => {
+  test('rejects when the agent permissions deny', async () => {
+    const resolved = setup('denied-agent')
+    addAgent('denied-agent', {
+      permissions: { denied: async () => false },
+    } as Partial<CoreAIAgent>)
+
+    await assert.rejects(
+      () =>
+        resumeAIAgentSync(
+          RUN_ID,
+          [{ toolCallId: TOOL_CALL_ID, approved: true }],
+          { sessionService: sessionService({ userId: 'u1' }) } as any
+        ),
+      ForbiddenError
+    )
+    assert.deepEqual(
+      resolved,
+      [],
+      'approvals must not be resolved when authorization fails'
+    )
+  })
+
+  test('rejects when a required scope is no longer held', async () => {
+    const resolved = setup('scoped-agent')
+    addAgent('scoped-agent', { scopes: ['admin:refund'] })
+
+    await assert.rejects(
+      () =>
+        resumeAIAgentSync(
+          RUN_ID,
+          [{ toolCallId: TOOL_CALL_ID, approved: true }],
+          {
+            sessionService: sessionService({
+              userId: 'u1',
+              scopes: ['support'],
+            }),
+          } as any
+        ),
+      MissingScopeError
+    )
+    assert.deepEqual(resolved, [], 'a revoked scope must block resumption')
+  })
+
+  test('passes the gate when the session still holds the scope', async () => {
+    setup('scoped-agent-ok')
+    addAgent('scoped-agent-ok', { scopes: ['admin:refund'] })
+
+    // Gets past authorization and fails later on the unconfigured provider,
+    // which is how we know the gate admitted it.
+    await assert.rejects(
+      () =>
+        resumeAIAgentSync(
+          RUN_ID,
+          [{ toolCallId: TOOL_CALL_ID, approved: true }],
+          {
+            sessionService: sessionService({
+              userId: 'u1',
+              scopes: ['admin:refund'],
+            }),
+          } as any
+        ),
+      (error: Error) =>
+        !(error instanceof ForbiddenError) &&
+        !(error instanceof MissingScopeError)
+    )
+  })
+
+  test('rejects when auth is required and the session is gone', async () => {
+    setup('auth-agent')
+    addAgent('auth-agent', { auth: true })
+
+    await assert.rejects(
+      () =>
+        resumeAIAgentSync(
+          RUN_ID,
+          [{ toolCallId: TOOL_CALL_ID, approved: true }],
+          { sessionService: sessionService(undefined) } as any
+        ),
+      ForbiddenError
+    )
+  })
+})
+
+describe('resumeAIAgent (streaming) authorization', () => {
+  const channel = {
+    send: async () => {},
+    close: async () => {},
+  } as any
+
+  test('rejects when the agent permissions deny', async () => {
+    const resolved = setup('stream-denied')
+    addAgent('stream-denied', {
+      permissions: { denied: async () => false },
+    } as Partial<CoreAIAgent>)
+
+    await assert.rejects(
+      () =>
+        resumeAIAgent(
+          { runId: RUN_ID, toolCallId: TOOL_CALL_ID, approved: true },
+          channel,
+          { sessionService: sessionService({ userId: 'u1' }) } as any
+        ),
+      ForbiddenError
+    )
+    assert.deepEqual(resolved, [])
+  })
+
+  test('rejects when a required scope is no longer held', async () => {
+    setup('stream-scoped')
+    addAgent('stream-scoped', { scopes: ['admin:refund'] })
+
+    await assert.rejects(
+      () =>
+        resumeAIAgent(
+          { runId: RUN_ID, toolCallId: TOOL_CALL_ID, approved: true },
+          channel,
+          {
+            sessionService: sessionService({
+              userId: 'u1',
+              scopes: ['support'],
+            }),
+          } as any
+        ),
+      MissingScopeError
+    )
+  })
+})

package/src/wirings/ai-agent/ai-agent-runner.ts

@@ -30,6 +30,7 @@ import {
   resolveOwnerResourceId,
   agentSessionScope,
   assertResourceOwner,
+  assertAgentAuthorized,
   type RunAIAgentParams,
 } from './ai-agent-prepare.js'
 import { checkForApprovals, appendStepMessages } from './ai-agent-stream.js'
@@ -416,6 +417,12 @@ export async function resumeAIAgentSync(
   }
 
   const { agent, packageName, resolvedName } = resolveAgent(run.agentName)
+
+  // Resuming re-runs the agent, so it re-runs the agent's gate. Run ownership
+  // alone is not enough: a grant revoked while the run was suspended must stop
+  // the caller from approving its pending tool calls.
+  await assertAgentAuthorized(agent, params, packageName)
+
   const { storage } = resolveMemoryServices(agent, singletonServices)
   const memoryConfig = agent.memory
   const agentRunner = singletonServices.aiAgentRunner