@pikku/core 0.12.72 → 0.12.77

package/src/services/scope-service.ts

@@ -1,49 +1,62 @@
 import type { FlatScope } from '../wirings/scope/scope.types.js'
+import type { SystemRole } from '../wirings/role/role.types.js'
 
-/** A role: a named, admin-composed bag of scopes. */
 export interface Role {
   name: string
   description?: string
   scopes: string[]
+  /**
+   * True when the role was declared in code with `defineSystemRole` rather
+   * than composed by an admin. System roles may be granted, but not renamed,
+   * re-scoped or deleted — see {@link ScopeService.syncSystemRoles}.
+   */
+  system?: boolean
+  /**
+   * False when a system role's declaration has been removed from code but its
+   * row survives: still held by whoever holds it, no longer offered for new
+   * grants, awaiting `pikku roles prune`.
+   */
+  declared?: boolean
 }
 
-/**
- * Resolves and administers the scopes granted to a user.
- *
- * Implementations are called at the **session boundary** — e.g. better-auth's
- * `mapSession` — never by the function runner. The runner reads
- * `session.scopes` and never performs I/O, which keeps it viable on Workers
- * and Lambda. Because the session is rebuilt per request, a scope change takes
- * effect on the next call with nothing cached and nothing to invalidate.
- *
- * `syncScopes` is deliberately additive: scopes are declared in code, so a
- * removed declaration leaves an inert row rather than silently revoking a
- * grant mid-deploy. Removal is an explicit operation (`pikku scopes prune`).
- */
+// knowledge: decisions/security/scope-resolution-happens-at-the-session-boundary-and-sync-never-deletes.md
 export interface ScopeService {
-  /**
-   * Registers the declared scope set. Additive — never deletes.
-   * Called once during startup with the generated scope list.
-   */
   syncScopes(scopes: FlatScope[]): Promise<void>
 
+  /** The union of role-derived scopes and scopes granted directly. */
+  resolveScopes(userId: string): Promise<string[]>
+
   /**
-   * Every scope a user holds: the union of their role-derived scopes and any
-   * scopes granted to them directly.
+   * The whole vocabulary a role can be composed from. `declared: false` marks a
+   * scope still in the store but no longer declared in code: inert, since no
+   * function can require it, and awaiting `pikku scopes prune`.
    */
-  resolveScopes(userId: string): Promise<string[]>
+  listScopes(): Promise<Array<FlatScope & { declared: boolean }>>
 
   /**
-   * The scope vocabulary in the store: everything a role can be composed from.
+   * Registers the roles declared with `defineSystemRole`. Additive on the same
+   * terms as {@link syncScopes}: a removed declaration leaves the row in place,
+   * marked `declared: false`, rather than revoking everyone's grant on deploy.
+   *
+   * A role's scope set *is* re-synced, because that is the declaration's whole
+   * content — editing `defineSystemRole` is how you change what a system role
+   * means, and the deploy is when it takes effect.
    *
-   * `declared: false` marks a scope that is still present but no longer
-   * declared in code — inert (no function can require it) and awaiting
-   * `pikku scopes prune`.
+   * Called once during startup with the generated role list.
    */
-  listScopes(): Promise<Array<FlatScope & { declared: boolean }>>
+  syncSystemRoles(roles: SystemRole[]): Promise<void>
 
+  /**
+   * Creates an admin-composed role.
+   *
+   * Must throw {@link SystemRoleShadowedError} when `role.name` matches a
+   * declared system role. Two rows answering to one name make "does this user
+   * hold `buyer`?" depend on which the store returns first.
+   */
   createRole(role: Role): Promise<void>
+  /** Must throw {@link SystemRoleImmutableError} for a system role. */
   deleteRole(name: string): Promise<void>
+  /** Must throw {@link SystemRoleImmutableError} for a system role. */
   setRoleScopes(name: string, scopes: string[]): Promise<void>
   listRoles(): Promise<Role[]>
 
@@ -51,10 +64,7 @@ export interface ScopeService {
   removeUserFromRole(userId: string, role: string): Promise<void>
   listUserRoles(userId: string): Promise<string[]>
 
-  /**
-   * Grants a scope directly to a user, outside of any role. Additive: the
-   * resolved set is the union of role-derived and directly-granted scopes.
-   */
+  /** Grants outside of any role; additive with the user's role-derived scopes. */
   addScopeToUser(
     userId: string,
     scope: string,
@@ -64,12 +74,18 @@ export interface ScopeService {
   /** Only the scopes granted directly, not those inherited from roles. */
   listUserScopes(userId: string): Promise<string[]>
 
-  /**
-   * Scopes present in the store that are no longer declared in code, with the
-   * roles that would lose them. Powers `pikku scopes audit`.
-   */
+  /** Undeclared scopes with the roles that would lose them; powers `pikku scopes audit`. */
   findStaleScopes(): Promise<Array<{ scope: string; roles: string[] }>>
 
   /** Removes undeclared scopes, cascading them out of roles. */
   pruneScopes(): Promise<string[]>
+
+  /**
+   * System roles in the store whose declaration has gone, with the number of
+   * users still holding each. Powers `pikku roles audit`.
+   */
+  findStaleSystemRoles(): Promise<Array<{ role: string; users: number }>>
+
+  /** Removes undeclared system roles, cascading them out of user grants. */
+  pruneSystemRoles(): Promise<string[]>
 }

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

@@ -1,9 +1,6 @@
-import type { SecretService } from './secret-service.js'
+import type { SecretValue } from '../secret-value.js'
+import type { SecretService, SecretValues } from './secret-service.js'
 
-/**
- * A read-only wrapper around SecretService that restricts access
- * to only a defined set of allowed secret keys.
- */
 export class ScopedSecretService implements SecretService {
   constructor(
     private secrets: SecretService,
@@ -16,7 +13,7 @@ export class ScopedSecretService implements SecretService {
     }
   }
 
-  async getSecret<T = string>(key: string): Promise<T> {
+  async getSecret<T = string>(key: string): Promise<SecretValue<T>> {
     this.assertAllowed(key)
     return this.secrets.getSecret<T>(key)
   }
@@ -36,7 +33,7 @@ export class ScopedSecretService implements SecretService {
 
   async getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(
     keys: (keyof T & string)[]
-  ): Promise<Partial<T>> {
+  ): Promise<Partial<SecretValues<T>>> {
     keys.forEach((k) => this.assertAllowed(k))
     return this.secrets.getSecrets<T>(keys)
   }

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

@@ -0,0 +1,138 @@
+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

@@ -0,0 +1,51 @@
+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,44 +1,21 @@
-/**
- * Interface for retrieving and managing secrets.
- */
+import type { SecretValue } from '../secret-value.js'
+
+/** A record of secrets, each still wrapped. */
+export type SecretValues<T> = { [K in keyof T]: SecretValue<T[K]> }
+
 export interface SecretService {
-  /**
-   * Retrieves a secret by key, typed as T (defaults to string).
-   * @param key - The key of the secret to retrieve.
-   * @returns A promise that resolves to the secret value.
-   * @throws If the secret is not found.
-   */
-  getSecret<T = string>(key: string): Promise<T>
-  /**
-   * Checks if a secret exists without throwing.
-   * @param key - The key of the secret to check.
-   * @returns A promise that resolves to true if the secret exists, false otherwise.
-   */
+  /** Throws if the secret is not found. 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>
-  /**
-   * Stores a secret value.
-   * @param key - The key to store the secret under.
-   * @param value - The value to store.
-   * @returns A promise that resolves when the secret is stored.
-   */
   setSecret(key: string, value: unknown): Promise<void>
-  /**
-   * Deletes a secret by key.
-   * @param key - The key of the secret to delete.
-   * @returns A promise that resolves when the secret is deleted.
-   */
   deleteSecret(key: string): Promise<void>
   /**
-   * Retrieves multiple secrets in a single batch operation.
-   * Returns a map of key → value for successfully fetched secrets; missing
-   * keys are omitted rather than throwing, so the result is typed as
-   * `Partial<T>` and callers must handle keys that may be absent at runtime.
-   *
-   * Pass a shape as `T` to get a typed result without casting, e.g.
-   * `await secrets.getSecrets<{ FOO: string; BAR: { id: string } }>(['FOO', 'BAR'])`.
-   * @param keys - The keys of the secrets to retrieve.
+   * 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<T>>
+  ): Promise<Partial<SecretValues<T>>>
 }

package/src/services/secretless.test.ts

@@ -0,0 +1,54 @@
+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

@@ -0,0 +1,29 @@
+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/stub-tracker.ts

@@ -3,10 +3,9 @@ export type StubCall = { service: string; method: string; args: unknown[] }
 type Call = { method: string; args: unknown[]; verified: boolean }
 
 /**
- * Tracks calls made to stubbed services and enforces strict mode:
- * once a scenario asserts any call on a service, every recorded call on that
- * service must be verified by end of scenario — otherwise the After hook fails.
- * Services never touched by an assertion stay lenient.
+ * Strict per service: once a scenario asserts any call on a service, every
+ * recorded call on it must be verified by the end of the scenario or the After
+ * hook fails. A service no assertion ever touched stays lenient.
  */
 export class StubTracker {
   private readonly calls = new Map<string, Call[]>()
@@ -123,16 +122,11 @@ export class StubTracker {
   }
 }
 
-/**
- * Creates a Proxy suitable for passing as `existingServices` to
- * `createSingletonServices`. Every property returns `tracker.stub(prop)`
- * EXCEPT `schema`, which returns `undefined` so the service factory creates
- * a real schema service. Stubbing the schema makes validation a no-op —
- * required fields pass silently and tests validate nothing.
- */
+/** Pass as `existingServices` to `createSingletonServices`. */
 export function createStubProxy(tracker: StubTracker): Record<string, unknown> {
   return new Proxy({} as Record<string, unknown>, {
     get(_, prop: string) {
+      // knowledge: decisions/internals/the-schema-service-is-never-stubbed.md
       if (prop === 'schema') return undefined
       return tracker.stub(prop)
     },
@@ -141,19 +135,15 @@ export function createStubProxy(tracker: StubTracker): Record<string, unknown> {
 
 const defaultStubTracker = new StubTracker()
 
-/** The process-wide tracker that `stub()`/`spy()` record into — read by the console's getStubCalls/resetStubs RPCs */
+/** The process-wide tracker `stub()`/`spy()` record into; read by the console's getStubCalls/resetStubs RPCs. */
 export const getStubTracker = (): StubTracker => defaultStubTracker
 
-/** True when the server was started by `pikku dev --test` (sets PIKKU_TEST_RUN) */
+/** True when the server was started by `pikku dev --test`, which sets PIKKU_TEST_RUN. */
 export const isTestRun = (): boolean =>
   (globalThis as { process?: { env?: Record<string, string | undefined> } })
     .process?.env?.PIKKU_TEST_RUN === 'true'
 
-/**
- * Creates a recording fake for a service. Methods present on `impl` run and
- * their result is returned; missing methods resolve `undefined`. Every call
- * is recorded so scenarios can assert via workflow.expectService().
- */
+/** Methods on `impl` run and return; every other method resolves `undefined`. */
 export function stub<T = any>(service: string, impl?: Partial<T>): T {
   return new Proxy((impl ?? {}) as object, {
     get(target: any, method: string | symbol) {

package/src/services/system-role-guard.test.ts

@@ -0,0 +1,93 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  assertRoleIsMutable,
+  assertRoleNameAvailable,
+  roleLockReason,
+} from './system-role-guard.js'
+import {
+  SystemRoleImmutableError,
+  SystemRoleShadowedError,
+} from '../errors/errors.js'
+
+const system = (...names: string[]) => (name: string) => names.includes(name)
+
+describe('mutating a role', () => {
+  test('a declared role refuses to be deleted or re-scoped', async () => {
+    await assert.rejects(
+      () => assertRoleIsMutable('buyer', system('buyer'), 'delete role'),
+      SystemRoleImmutableError
+    )
+  })
+
+  test('the refusal says which role and what was attempted', async () => {
+    await assert.rejects(
+      () => assertRoleIsMutable('buyer', system('buyer'), 'set scopes on'),
+      /Cannot set scopes on 'buyer'[\s\S]*defineSystemRole/
+    )
+  })
+
+  test('a custom role is left alone', async () => {
+    await assert.doesNotReject(() =>
+      assertRoleIsMutable('invoicing-clerk', system('buyer'), 'delete role')
+    )
+  })
+
+  test('an async lookup is awaited, not truthy-tested', async () => {
+    await assert.rejects(
+      () => assertRoleIsMutable('buyer', async () => true, 'delete role'),
+      SystemRoleImmutableError
+    )
+    // A promise resolving to false is itself truthy — the guard must await it
+    // rather than treat the promise as the answer.
+    await assert.doesNotReject(() =>
+      assertRoleIsMutable('buyer', async () => false, 'delete role')
+    )
+  })
+})
+
+describe('creating a role', () => {
+  test('shadowing a declared name is refused', async () => {
+    await assert.rejects(
+      () => assertRoleNameAvailable('buyer', system('buyer')),
+      SystemRoleShadowedError
+    )
+  })
+
+  test('an unused name is allowed', async () => {
+    await assert.doesNotReject(() =>
+      assertRoleNameAvailable('invoicing-clerk', system('buyer'))
+    )
+  })
+})
+
+describe('what the console renders', () => {
+  test('a custom role has no lock', () => {
+    assert.equal(roleLockReason({ name: 'clerk', scopes: [] }), null)
+  })
+
+  test('a declared role locks with the reason and the fix', () => {
+    const reason = roleLockReason({
+      name: 'buyer',
+      scopes: [],
+      system: true,
+      declared: true,
+    })
+    assert.match(reason!, /declared in code with defineSystemRole/)
+  })
+
+  // An undeclared system role is still locked, but for a different reason and
+  // with a different fix — saying "edit the declaration" would send someone
+  // looking for a declaration that no longer exists.
+  test('an undeclared system role explains that it is inert', () => {
+    const reason = roleLockReason({
+      name: 'buyer',
+      scopes: [],
+      system: true,
+      declared: false,
+    })
+    assert.match(reason!, /inert/)
+    assert.match(reason!, /pikku roles prune/)
+  })
+})