@pikku/core 0.12.64 → 0.12.67

package/src/permissions.ts

@@ -1,7 +1,6 @@
 import type {
   CoreServices,
   CoreUserSession,
-  PermissionMetadata,
   PikkuWire,
 } from './types/core.types.js'
 import type {
@@ -60,29 +59,6 @@ const verifyPermissions = async (
   return false
 }
 
-/**
- * Retrieves a registered permission function by its name.
- *
- * This function looks up permissions that was registered with registerPermission.
- * It's used internally by the framework to resolve permission references in metadata.
- *
- * @param {string} name - The unique name (pikkuFuncId) of the permission function.
- * @param {string | null} packageName - Optional package namespace.
- * @returns {CorePikkuPermission | undefined} The permission function, or undefined if not found.
- *
- * @internal
- */
-const getPermissionByName = (
-  name: string,
-  packageName: string | null = null
-): CorePikkuPermission | undefined => {
-  const permissionStore = pikkuState(packageName, 'misc', 'permissions')
-  const permission = permissionStore[name]
-  if (Array.isArray(permission) && permission.length === 1) {
-    return permission[0]
-  }
-  return undefined
-}
 
 const globalPermissionsCache: Record<
   string,
@@ -190,12 +166,15 @@ export const runPermissions = async ({
   wire,
   data,
   packageName = null,
+  label = 'function',
 }: {
   funcPermissions?: CorePermissionGroup | CorePikkuPermission[]
   services: CoreServices
   wire: PikkuWire<any, never, any, CoreUserSession, never, never, never>
   data: any
   packageName?: string | null
+  /** What the non-global gate is called in debug logs, e.g. 'function', 'agent'. */
+  label?: string
 }) => {
   const globals = resolveGlobalPermissions(packageName)
   for (const entry of globals) {
@@ -211,7 +190,7 @@ export const runPermissions = async ({
       : funcPermissions
     if (group && Object.keys(group).length > 0) {
       if (!(await verifyPermissions(group, services, data, wire))) {
-        services.logger.debug('Permission denied - function permission')
+        services.logger.debug(`Permission denied - ${label} permission`)
         throw new ForbiddenError('Permission denied')
       }
     }
@@ -224,14 +203,20 @@ export const runPermissions = async ({
  * request data which isn't available at filter time. Global auth requirements
  * are included so a filtered list honours app-wide auth.
  *
- * @param funcPermissions - The PermissionMetadata[] from function or agent metadata
+ * `funcPermissions` is the live {@link CorePermissionGroup} from the function or
+ * agent config, not the metadata form: the `pikkuAuth` brand only survives on
+ * the actual predicate objects, and the by-name registry those metadata entries
+ * would resolve against is never populated. Passing metadata here would silently
+ * collect nothing and let every gated tool through.
+ *
+ * @param funcPermissions - The live permission group from the func/agent config
  * @param session - The user's session
  * @param services - Singleton services
  * @param packageName - Optional package namespace
  * @returns true if the session passes the auth checks (or no auth checks exist)
  */
 export const checkAuthPermissions = async (
-  funcPermissions: PermissionMetadata[] | undefined,
+  funcPermissions: CorePermissionGroup | undefined,
   session: CoreUserSession,
   services: CoreServices,
   packageName: string | null = null
@@ -271,15 +256,8 @@ export const checkAuthPermissions = async (
     collect(entry)
   }
 
-  if (funcPermissions?.length) {
-    for (const meta of funcPermissions) {
-      if (meta.type === 'wire') {
-        const permission = getPermissionByName(meta.name, packageName)
-        if (permission) {
-          collect(permission)
-        }
-      }
-    }
+  if (funcPermissions) {
+    collect(funcPermissions)
   }
 
   // No auth permissions = allowed (only data-dependent permissions exist)

package/src/scopes.test.ts

@@ -1,6 +1,6 @@
 import { describe, test } from 'node:test'
 import * as assert from 'node:assert'
-import { verifyScopes } from './scopes.js'
+import { hasScopes, verifyScopes } from './scopes.js'
 import { MissingScopeError } from './errors/errors.js'
 import type { CoreUserSession } from './types/core.types.js'
 
@@ -165,3 +165,39 @@ describe('verifyScopes', () => {
     )
   })
 })
+
+describe('hasScopes', () => {
+  test('true on an exact match', () => {
+    assert.equal(hasScopes(['invoices:create'], ['invoices:create']), true)
+  })
+
+  test('false when the grant is unrelated', () => {
+    assert.equal(hasScopes(['invoices:create'], ['billing:read']), false)
+  })
+
+  test('shares the hierarchy rules with verifyScopes', () => {
+    assert.equal(hasScopes(['admin:impersonate'], ['admin']), true)
+    assert.equal(hasScopes(['admin:impersonate'], ['admin:*']), true)
+    assert.equal(hasScopes(['admin:impersonate'], ['*']), true)
+    assert.equal(hasScopes(['admin'], ['admin:impersonate']), false)
+  })
+
+  test('AND semantics: every required scope must be satisfied', () => {
+    assert.equal(hasScopes(['a:read', 'a:write'], ['a:read']), false)
+    assert.equal(hasScopes(['a:read', 'a:write'], ['a']), true)
+  })
+
+  test('fails closed on absent or empty grants', () => {
+    assert.equal(hasScopes(['invoices:create'], undefined), false)
+    assert.equal(hasScopes(['invoices:create'], []), false)
+  })
+
+  test('an empty requirement is satisfied by anything', () => {
+    assert.equal(hasScopes([], undefined), true)
+    assert.equal(hasScopes(undefined, undefined), true)
+  })
+
+  test('accepts a Set of held grants', () => {
+    assert.equal(hasScopes(['admin:impersonate'], new Set(['admin'])), true)
+  })
+})

package/src/scopes.ts

@@ -37,6 +37,51 @@ const satisfyingGrants = (scope: string): string[] => {
 const holds = (held: ReadonlySet<string>, scope: string): boolean =>
   satisfyingGrants(scope).some((grant) => held.has(grant))
 
+/**
+ * The first required scope a set of held grants does not satisfy, or `null`
+ * when every one is satisfied.
+ *
+ * Scopes are an AND gate: every entry in `required` must be satisfied. This is
+ * deliberately distinct from `permissions`, which OR together — a scope can
+ * only ever narrow access, so adding one to a function can never widen it.
+ *
+ * Fails closed: an absent `held` satisfies nothing.
+ */
+const firstUnsatisfied = (
+  required: readonly string[] | undefined,
+  held: Iterable<string> | undefined
+): string | null => {
+  if (!required || required.length === 0) {
+    return null
+  }
+
+  const grants = new Set(held ?? [])
+  for (const scope of required) {
+    if (!holds(grants, scope)) {
+      return scope
+    }
+  }
+  return null
+}
+
+/**
+ * Whether a set of held grants satisfies every required scope.
+ *
+ * The non-throwing counterpart to {@link verifyScopes}, for deciding rather
+ * than enforcing — an authorization gate that falls back to another check when
+ * it is not satisfied, rather than rejecting the request outright.
+ *
+ * Fails closed: an absent or empty `held` satisfies nothing. An empty
+ * `required` is satisfied by anything.
+ *
+ * @param required - Scopes to check for. Empty means no gate.
+ * @param held - The grants held, e.g. `session.scopes`. May be undefined.
+ */
+export const hasScopes = (
+  required: readonly string[] | undefined,
+  held: Iterable<string> | undefined
+): boolean => firstUnsatisfied(required, held) === null
+
 /**
  * Verifies that a session holds every required scope, throwing on the first
  * one it does not.
@@ -56,14 +101,8 @@ export const verifyScopes = (
   required: readonly string[] | undefined,
   session: CoreUserSession | undefined
 ): void => {
-  if (!required || required.length === 0) {
-    return
-  }
-
-  const held = new Set(session?.scopes ?? [])
-  for (const scope of required) {
-    if (!holds(held, scope)) {
-      throw new MissingScopeError(scope)
-    }
+  const missing = firstUnsatisfied(required, session?.scopes)
+  if (missing !== null) {
+    throw new MissingScopeError(missing)
   }
 }

package/src/testing/service-tests.ts

@@ -1086,6 +1086,55 @@ export function defineServiceTests(config: ServiceTestConfig): void {
         assert.ok(Array.isArray(threads))
       })
 
+      if (services.aiStorageService) {
+        const storageFactory = services.aiStorageService
+
+        // The `owners` constraint is what keeps the generated thread-management
+        // functions from leaking across tenants: a caller may only list threads
+        // owned by one of their session principals, matching the
+        // `principal:sub-partition` composition resolveOwnerResourceId writes.
+        test('listThreads scopes to the given owners, including sub-partitions', async () => {
+          const storage = await storageFactory()
+          await storage.createThread('owner-alice')
+          await storage.createThread('owner-alice:project-1')
+          await storage.createThread('owner-bob:secret')
+
+          const threads = await agentService.listThreads({
+            owners: ['owner-alice'],
+          })
+          const ids = threads.map((t) => t.resourceId)
+
+          assert.ok(ids.includes('owner-alice'))
+          assert.ok(ids.includes('owner-alice:project-1'))
+          assert.ok(
+            !ids.some((id) => id.startsWith('owner-bob')),
+            "another owner's threads must not be listed"
+          )
+        })
+
+        test('listThreads with an owner does not match a lookalike prefix', async () => {
+          const storage = await storageFactory()
+          await storage.createThread('owner-al')
+          await storage.createThread('owner-alice-evil:p')
+
+          const threads = await agentService.listThreads({
+            owners: ['owner-al'],
+          })
+          const ids = threads.map((t) => t.resourceId)
+
+          assert.ok(ids.includes('owner-al'))
+          assert.ok(!ids.includes('owner-alice-evil:p'))
+        })
+
+        test('listThreads with an empty owners list returns nothing', async () => {
+          const storage = await storageFactory()
+          await storage.createThread('owner-empty-check')
+
+          const threads = await agentService.listThreads({ owners: [] })
+          assert.deepEqual(threads, [])
+        })
+      }
+
       test('getThread returns null for missing', async () => {
         const thread = await agentService.getThread('missing-thread')
         assert.equal(thread, null)

package/src/types/core.types.ts

@@ -269,6 +269,22 @@ export interface CoreUserSession {
   scopes?: string[]
 }
 
+/**
+ * The shape pikku needs from whatever auth library a project wires: something
+ * that can answer an HTTP request and expose its own endpoints as callable
+ * methods. Kept structural so core stays independent of any one auth package —
+ * `@pikku/better-auth`'s `BetterAuthInstance` is this type.
+ */
+export interface AuthInstance {
+  handler: (request: Request) => Promise<Response>
+  api: Record<string, any>
+  /**
+   * The auth library's resolved context. Optional because a hand-built instance
+   * may omit it.
+   */
+  $context?: Promise<any>
+}
+
 /**
  * Interface for core singleton services provided by Pikku.
  */
@@ -341,6 +357,13 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
    * better-auth's `mapSession`), never by the function runner.
    */
   scopeService?: ScopeService
+  /**
+   * The project's resolved auth instance, built once by the factory an auth
+   * package registers (e.g. `pikkuBetterAuth`) and injected by the generated
+   * `pikkuServices` wrapper — which is why service factories are forbidden from
+   * returning it themselves. Absent when the project wires no auth.
+   */
+  auth?: () => Promise<AuthInstance>
 }
 
 /**

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

@@ -0,0 +1,204 @@
+import { beforeEach, describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  resetPikkuState,
+  pikkuState,
+  setSingletonServices,
+} from '../../pikku-state.js'
+import { assertAgentAuthorized } from './ai-agent-prepare.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
+
+beforeEach(() => {
+  resetPikkuState()
+  clearPermissionsCache()
+  setSingletonServices({ logger } as any)
+})
+
+const addAgent = (
+  agentName: string,
+  overrides: Partial<CoreAIAgent> = {}
+): CoreAIAgent => {
+  const agent: CoreAIAgent = {
+    name: agentName,
+    description: `${agentName} description`,
+    goal: `${agentName} goal`,
+    instructions: `${agentName} instructions`,
+    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
+
+describe('assertAgentAuthorized', () => {
+  test('resolves when the agent declares no authorization and a session exists', async () => {
+    const agent = addAgent('open')
+    await assertAgentAuthorized(
+      agent,
+      { sessionService: sessionService({ userId: 'u1' }) },
+      null
+    )
+  })
+
+  test('does not require a session unless auth is explicitly true', async () => {
+    const agent = addAgent('sessionless')
+    await assertAgentAuthorized(
+      agent,
+      { sessionService: sessionService(undefined) },
+      null
+    )
+  })
+
+  test('resolves with no sessionService at all (cron / queue invocation)', async () => {
+    const agent = addAgent('no-session-service')
+    await assertAgentAuthorized(agent, {}, null)
+  })
+
+  test('throws ForbiddenError when auth is explicitly true and no session exists', async () => {
+    const agent = addAgent('needs-session', { auth: true })
+    await assert.rejects(
+      () =>
+        assertAgentAuthorized(
+          agent,
+          { sessionService: sessionService(undefined) },
+          null
+        ),
+      ForbiddenError
+    )
+  })
+
+  test('enforces scopes even when auth is not required', async () => {
+    const agent = addAgent('scoped-sessionless', { scopes: ['reports:read'] })
+    await assert.rejects(
+      () => assertAgentAuthorized(agent, {}, null),
+      MissingScopeError
+    )
+  })
+
+  test('throws ForbiddenError when the permission group denies', async () => {
+    const agent = addAgent('guarded', {
+      permissions: { admin: async () => false },
+    })
+    await assert.rejects(
+      () =>
+        assertAgentAuthorized(
+          agent,
+          { sessionService: sessionService({ userId: 'u1' }) },
+          null
+        ),
+      ForbiddenError
+    )
+  })
+
+  test('resolves when at least one permission branch passes', async () => {
+    const agent = addAgent('or-group', {
+      permissions: {
+        admin: async () => false,
+        owner: async () => true,
+      },
+    })
+    await assertAgentAuthorized(
+      agent,
+      { sessionService: sessionService({ userId: 'u1' }) },
+      null
+    )
+  })
+
+  test('passes the session through to permission functions', async () => {
+    let seen: CoreUserSession | undefined
+    const agent = addAgent('sees-session', {
+      permissions: {
+        admin: async (_services: any, _data: any, wire: any) => {
+          seen = wire.session
+          return true
+        },
+      },
+    })
+    await assertAgentAuthorized(
+      agent,
+      { sessionService: sessionService({ userId: 'u1' }) },
+      null
+    )
+    assert.equal(seen?.userId, 'u1')
+  })
+
+  test('throws MissingScopeError when a required scope is not held', async () => {
+    const agent = addAgent('scoped', { scopes: ['reports:read'] })
+    await assert.rejects(
+      () =>
+        assertAgentAuthorized(
+          agent,
+          { sessionService: sessionService({ userId: 'u1', scopes: [] }) },
+          null
+        ),
+      MissingScopeError
+    )
+  })
+
+  test('resolves when the session holds the required scope', async () => {
+    const agent = addAgent('scoped-ok', { scopes: ['reports:read'] })
+    await assertAgentAuthorized(
+      agent,
+      {
+        sessionService: sessionService({
+          userId: 'u1',
+          scopes: ['reports:read'],
+        }),
+      },
+      null
+    )
+  })
+
+  test('resolves when an ancestor scope grant covers the requirement', async () => {
+    const agent = addAgent('scoped-parent', { scopes: ['reports:read'] })
+    await assertAgentAuthorized(
+      agent,
+      {
+        sessionService: sessionService({ userId: 'u1', scopes: ['reports'] }),
+      },
+      null
+    )
+  })
+
+  test('checks scopes before permissions', async () => {
+    let permissionRan = false
+    const agent = addAgent('scope-first', {
+      scopes: ['reports:read'],
+      permissions: {
+        admin: async () => {
+          permissionRan = true
+          return true
+        },
+      },
+    })
+    await assert.rejects(
+      () =>
+        assertAgentAuthorized(
+          agent,
+          { sessionService: sessionService({ userId: 'u1', scopes: [] }) },
+          null
+        ),
+      MissingScopeError
+    )
+    assert.equal(permissionRan, false)
+  })
+})