@place-ts/security

// Session capability — typed runtime slot for the authenticated user.
import { SessionCap, requireSession, type Session } from '@place-ts/security'

// Install at the request boundary (typically in a layout's load()):
SessionCap.provide(
  {
    id: sessionId,
    userId: user.id,
    issuedAt: Date.now(),
    expiresAt: null,
    // Optional RBAC predicate; populated from your policy engine.
    can: (action) => policy.evaluate(user, action),
  },
  () => handler(req),
)

// Read inside any handler that requires auth — throws 401 if absent.
const session = requireSession()
const userId = session.userId

// Optional read — returns null if not installed.
const maybe = SessionCap.tryUse()

// <Can do="..."> — render-time RBAC gate (ADR 0044).
// Fails closed: no session, no .can, anything other than strict true.
// Synchronous predicate → SSR-safe, denied content never reaches HTML.
import { Can } from '@place-ts/security/can'
import { Button } from '@place-ts/design'

<Can do="post.delete">
  <Button intent="destructive" onClick={remove}>Delete</Button>
</Can>

<Can do="admin.users.read" otherwise="Access denied">
  <UserTable />
</Can>

// Schema-agnostic validation for action() inputs (ADR 0045).
// Any Standard Schema v1 validator works: Zod 3.24+, Valibot 0.36+,
// ArkType, Effect Schema. Field-level errors land in
// ActionError.payload.fields, narrowed via isValidationFailure.
import { z } from 'zod'
import { action, fromStandard, isValidationFailure } from '@place-ts/component'

export const signup = action({
  path: 'POST /api/signup',
  input: fromStandard(z.object({
    email: z.string().email(),
    age: z.number().int().min(18),
  })),
  fn: async ({ email, age }) => ({ ok: true }),
})

// Client-side:
<Form action={signup} onError={(e) => {
  if (e instanceof ActionError && isValidationFailure(e.payload)) {
    emailErr.set(e.payload.fields.email ?? '')
  }
}}>
  {/* ... */}
</Form>

// HMAC-signed opaque payload. SHA-256, Web Crypto. Optional expiry.
import { signedToken } from '@place-ts/security'

const sessionToken = signedToken<{ userId: string }>(SECRET, {
  expiresInSeconds: 60 * 60 * 24 * 7, // 7 days
})

const token = await sessionToken.sign({ userId: 'u123' })
const payload = await sessionToken.verify(token) // null on bad sig / expired

// Same primitive for any "trust this opaque string came from us
// unmodified" use case: session cookies, share links, magic-link tokens,
// signed download URLs.

// Double-submit CSRF — auto-wired into action() + <Form> when
// security: 'standard' is on (the default). The primitive is exposed
// for apps that need it outside that path.
import { csrfToken } from '@place-ts/security'

const csrf = csrfToken(SECRET)
const token = await csrf.issue(sessionId)
const ok = await csrf.verify(sessionId, submittedToken)

// In-memory token bucket. For multi-instance deployments wrap with
// a shared backend (Redis, KV) behind the same interface.
import { rateLimit } from '@place-ts/security'

const checkLogin = rateLimit({ windowMs: 60_000, max: 5 })

// In a handler:
if (!checkLogin(req.headers.get('x-forwarded-for') ?? 'anon')) {
  return new Response('Too many requests', { status: 429 })
}

// Secure-by-default cookie helpers.
import { parseCookies, setCookieHeader, clearCookieHeader } from '@place-ts/security'

// Parse incoming Cookie header.
const cookies = parseCookies(req.headers.get('cookie'))
const sessionCookie = cookies['place-session']

// Set: HttpOnly + Secure + SameSite=Lax baked in. Path=/ implicit.
const setCookie = setCookieHeader('place-session', token, {
  maxAgeSeconds: 60 * 60 * 24 * 7,
})
return new Response(body, { headers: { 'set-cookie': setCookie } })

// Clear:
const clear = clearCookieHeader('place-session')

// Localhost dev: pass insecure: true to drop the Secure flag.
// **Never in production** — the explicit name keeps the choice visible.

// Strict CSP starter. The serve({ security: 'standard' }) path
// applies this header with a fresh per-request nonce. No 'unsafe-inline'
// anywhere; auto-hash injection covers inline-style attrs (ADR 0014).
import { CSP_DEFAULTS, cspHeader } from '@place-ts/security'

const header = cspHeader(CSP_DEFAULTS)

// Extend:
const custom = cspHeader({
  ...CSP_DEFAULTS,
  'connect-src': "'self' https://api.example.com",
})

// HMAC envelope — the substrate criticalAction() builds on.
// Signs a canonical metadata blob that binds the action, body hash,
// session, origin, counter, and iat. signEnvelope() returns a single
// wire string; verifyEnvelope() returns ok + typed reason on failure.
//
// Apps don't usually call these directly — criticalAction() does — but
// they're exposed for custom transports (websocket frames, signed
// pub/sub messages, etc.).
import { signEnvelope, verifyEnvelope, sha256Base64url } from '@place-ts/security'

const wire = await signEnvelope(perSessionKey, {
  actionId: 'POST /__a/transfer',
  bodyHash: await sha256Base64url(bodyBytes),
  counter: nextCounter,
  iat: Math.floor(Date.now() / 1000),
  origin: 'https://app.example.com',
  sessionId: session.id,
  keyId: 'b20142',
})

const r = await verifyEnvelope(wire, {
  key: perSessionKey,
  body: bodyBytes,
  expectedActionId: 'POST /__a/transfer',
  expectedOrigin: 'https://app.example.com',
  expectedSessionId: session.id,
  maxAgeSec: 300,
})
if (!r.ok) reject(r.reason)  // bad-tag | stale | replay | wrong-session | …

// Macaroons — HMAC-chained bearer tokens with attenuating caveats.
// criticalAction({ requires }) uses them; the primitives are exposed
// for apps that want capability-based authorization elsewhere.
//
// Stanford / Google macaroons paper. Each caveat NARROWS the token's
// authority — a holder can attenuate without the root key (HMAC over
// existing tag), but cannot widen.
import {
  mintMacaroon,
  attenuate,
  verifyMacaroon,
  serializeMacaroon,
  deserializeMacaroon,
} from '@place-ts/security'

// Mint at the auth boundary.
const root = await mintMacaroon(rootKey, session.id)

// Narrow to the user's actual permissions.
const scoped = await attenuate(root, 'op=comments.*')
const tenanted = await attenuate(scoped, 'app:tenant=acme')
const dated = await attenuate(tenanted, 'expires=2026-06-01T00:00:00Z')

// Send to the browser:
const wire = serializeMacaroon(dated)   // header-safe single-line string

// Verify on receive:
const r = await verifyMacaroon(deserializeMacaroon(wire), rootKey, {
  op: 'comments.create',
  origin: 'https://app.example.com',
  appVerifier: (key, value, ctx) => key === 'tenant' && value === requestTenant(),
})
if (!r.ok) reject(r.reason)
// reason ∈ 'bad-sig' | 'malformed' | 'unknown-caveat' | 'expired'
//        | 'wrong-op' | 'wrong-origin' | 'app-denied'

// Caveat grammar (v0.1, fail-closed on anything else):
//   expires=<ISO-8601 UTC>
//   origin=<URL>
//   op=<name>            // exact
//   op=<prefix>.*        // prefix match
//   op=*                 // wildcard
//   app:<key>=<value>    // requires appVerifier; rejected otherwise
//
// Multiple op= caveats compose by INTERSECTION (order-free).

// Hash-chained tamper-evident audit log. criticalAction() auto-appends
// one entry per invocation (request body hash + result hash bound).
// Apps emit additional entries via ctx.audit() inside the handler.
// Any modification to an existing entry breaks the chain and is caught
// by verify().
import { AuditLogCap, inMemoryAuditLog, useAuditLog } from '@place-ts/security'

// At app boot:
AuditLogCap.install(inMemoryAuditLog({ maxEntries: 10_000 }))
//   ↑ ring-buffered in-memory adapter. Replace with a durable adapter
//     (postgres / S3 / object-store) that conforms to AuditLog.

// Inside any handler (criticalAction sets it up automatically; manual
// use is fine too):
const log = useAuditLog()
await log.append({
  actor: session.userId,
  action: 'admin.role.change',
  payloadHash: await sha256Base64url(payloadBytes),
  resultHash: '',
  keyId: 'b20142',
})

// Verify the chain anywhere:
const { ok, brokenAt } = await log.verify()
if (!ok) reportTampering(brokenAt)