criticalAction()

criticalAction<I, R>(def: {
  path: string
  input: (raw: unknown) => I
  fn: (input: I, ctx: CriticalActionCtx) => Promise<R> | R
  // Optional:
  requires?: readonly PermDeclaration[]   // capability gates (perm('op'))
  sameOrigin?: boolean                    // default true for state-changing methods
  maxBodyBytes?: number                   // default 1 MiB
  maxAgeSec?: number                      // default 300 (replay window)
  appCaveatVerifier?: (key, value, ctx) => boolean | Promise<boolean>
}): { call, handler, path, __isCriticalAction: true }

// 1. Add a 32+ byte app secret. Every node in a multi-node deployment
//    derives the same per-session HMAC key from it.

import { app } from '@place/component/server'

app({
  pages: [...],
  secret: process.env.PLACE_SECRET!,   // 32+ bytes, e.g. base64url(crypto.randomBytes(32))
}).run()

// The framework throws at app-config time if any criticalAction() is
// registered without a SessionCap install. Critical actions REQUIRE
// an authenticated session — the envelope binds session.id.

import { criticalAction } from '@place/component/server'
import { shape } from '@place/component'

export const transferFunds = criticalAction({
  path: 'POST /__a/transfer',
  input: shape({ to: 'string', amountCents: 'number' }),
  fn: async (input, { session }) => {
    // session.userId is GUARANTEED non-null — the framework enforces
    // SessionCap before the handler runs. Envelope already verified.
    await ledger.transfer(session.userId, input.to, input.amountCents)
    return { ok: true }
  },
})

// Same registration shape as action() — spread .handler into serve().
import { serve } from '@place/component/server'
import { transferFunds, withdrawFunds } from './actions'

serve({
  routes: {
    ...transferFunds.handler,
    ...withdrawFunds.handler,
    '/': home,
  },
})

import { criticalAction, perm } from '@place/component/server'

export const deleteUser = criticalAction({
  path: 'POST /__a/users/delete',
  input: shape({ userId: 'string' }),
  // The macaroon attached to the request MUST permit admin.users.delete.
  // A macaroon scoped to admin.users.* OR admin.* OR * permits it;
  // a macaroon scoped to admin.posts.* does not.
  requires: [perm('admin.users.delete')],
  fn: async ({ userId }) => {
    await db.users.softDelete(userId)
    return { ok: true }
  },
})

// Multiple perms — ALL must be permitted by the request's macaroon.
export const moveDocument = criticalAction({
  path: 'POST /__a/docs/move',
  input: shape({ docId: 'string', folderId: 'string' }),
  requires: [perm('docs.write'), perm('folders.read')],
  fn: async (input) => { /* … */ return { ok: true } },
})

// Server-side auth flow. After successful login, return BOTH the
// action key (for envelope signing) and a macaroon (for the
// capability check). Apps attenuate the macaroon to match the user's
// actual permissions before issuance.

import {
  provisionActionKey,
  provisionMacaroon,
} from '@place/component/server'
import { attenuate, serializeMacaroon } from '@place/security'

export const login = action({
  path: 'POST /api/login',
  input: shape({ email: 'string', password: 'string' }),
  fn: async ({ email, password }, ctx) => {
    const user = await authenticate(email, password)
    const session = await createSession(user)

    // Action key — for envelope signing on every criticalAction call.
    const action = await provisionActionKey(session.id)

    // Macaroon — the broad root authority. Apps attenuate to match
    // the user's actual capability set.
    const broad = await provisionMacaroon(session.id)
    const scoped = await policy.attenuateForUser(broad.macaroon, user)
    //   ↑ your app's helper. For example:
    //     attenuate(m, `op=${user.role === 'admin' ? '*' : 'comments.*'}`)
    //     then attenuate(m, `app:tenant=${user.tenantId}`)

    setCookieHeader(ctx.req, 'place_sid', session.id, { httpOnly: true, secure: true })
    return {
      action,
      macaroon: { macaroon: serializeMacaroon(scoped), expiresAt: broad.expiresAt },
    }
  },
})

// Browser-side, right after login resolves.
// installActionKey imports the HMAC key as a non-extractable
// WebCrypto CryptoKey + persists to IndexedDB so reloads keep it.
// installMacaroon stores the serialised macaroon alongside.

import { installActionKey, installMacaroon } from '@place/component/client'

const onLoginSuccess = async () => {
  const res = await login.call({ email, password })
  await installActionKey(res.action)
  await installMacaroon(res.macaroon)
  // From this point onward every criticalAction().call() picks them
  // up automatically — envelope is signed, macaroon header attached.
}

// On logout: drop both. Subsequent criticalAction calls 403.
import { clearActionKey, clearMacaroon } from '@place/component/client'
await Promise.all([clearActionKey(), clearMacaroon()])

// Client-side call() is identical to action().call() — no extra
// boilerplate, no manual envelope or macaroon handling. The framework
// signs + sends + verifies + audits.

import { transferFunds } from './actions'

try {
  const result = await transferFunds.call({ to: 'acct_123', amountCents: 5000 })
  //    ^? { ok: boolean }
} catch (e) {
  if (e instanceof ActionError && e.status === 403) {
    // 403 with body "Forbidden" — the server returns no detail on
    // which check failed (no-info-leak oracle). The audit log
    // captures the typed reason server-side.
  }
}

// ctx.audit() — append custom events to the tamper-evident audit log
// from inside a handler. The framework auto-appends ONE entry per
// invocation (on success or failure); audit() adds MORE.

export const escalate = criticalAction({
  path: 'POST /__a/escalate',
  input: shape({ caseId: 'string', tier: 'number' }),
  requires: [perm('cases.escalate')],
  fn: async (input, ctx) => {
    const score = await fraudScore(input.caseId)
    if (score > 0.9) {
      await ctx.audit('fraud_score.high', { caseId: input.caseId, score })
    }
    if (input.tier >= 3) {
      await ctx.audit('kyc.escalated', { caseId: input.caseId })
    }
    await escalateCase(input.caseId, input.tier)
    return { ok: true }
  },
})

// Verification:
import { useAuditLog } from '@place/security'
const log = useAuditLog()
const { ok, brokenAt } = await log.verify()
if (!ok) reportTampering(brokenAt)

// app: caveats — app-defined namespace for tenant scoping etc.
// The verifier is invoked once per app: caveat at verify time.
// Fail-closed: if a macaroon carries app: caveats but no verifier is
// registered, the request is rejected.

export const readRecord = criticalAction({
  path: 'POST /__a/records/read',
  input: shape({ recordId: 'string' }),
  requires: [perm('records.read')],
  appCaveatVerifier: (key, value, { op }) => {
    if (key === 'tenant') {
      // Match the macaroon's tenant claim against the request context.
      return value === currentRequestTenant()
    }
    return false // unknown app: key → fail closed
  },
  fn: async ({ recordId }) => db.records.find(recordId),
})

// At provision time the app attenuates the macaroon with the tenant:
const scoped = await attenuate(
  await attenuate(broad.macaroon, 'op=records.*'),
  `app:tenant=${user.tenantId}`,
)

// action() vs criticalAction() at a glance:

//                         action()              criticalAction()
// CSRF                    auto-token            HMAC envelope (binds body hash)
// Replay                  (none — token reuse)  IPsec sliding window (per session)
// Body integrity          (none)                envelope binds sha256(body)
// Origin binding          same-origin guard     binds origin into envelope tag
// Action binding          path = path           binds action_id into envelope tag
// Session binding         SessionCap (optional) binds session.id into envelope tag
// Capability gate         ctx.session.can(...)  perm('op') verified via macaroon
// Audit                   (app-defined)         hash-chained log + ctx.audit()
// Cost per call           ~200 µs (validate)    ~205-215 µs (envelope + replay + verify)
//
// Use action() for most mutations. Reach for criticalAction() when:
//   - The action moves money, escalates privilege, or modifies records
//     that compliance cares about
//   - You need a tamper-evident audit trail
//   - You need capability-based authorization (per-tenant, per-scope)
//   - You need replay protection across multi-tab / multi-device
//     scenarios (action()'s CSRF token doesn't defend against replays
//     of a valid token from the same browser)