tibi-svelte-starter/.agents/skills/security-hardening-and-token-strategy/SKILL.md

---
name: security-hardening-and-token-strategy
description: Apply current tibi-server security practices to website projects. Covers secret handling, token strategies, bulk-permission safety, cookie settings, SSRF/exec risks in hooks, and secure operator decisions for this stack.
---

# security-hardening-and-token-strategy

## When to use this skill

Use this skill when:

- Setting up or reviewing authentication and token use on this stack
- Deciding how admin tokens, JWT auth, and token permissions should be used
- Hardening hooks, actions, and project config against obvious security mistakes
- Reviewing bulk permissions, secrets, cookie settings, or risky server-side capabilities

## Goal

The goal is to keep projects on this starter aligned with the current tibi-server security model and known risk areas.

This skill is not a generic web security guide. It is about the concrete operator and implementation choices this stack exposes.

## Source of truth

Use these sources when implementing or reviewing security-related decisions:

- `tibi-server/docs/05-authentication.md`
- `tibi-server/docs/14-security.md`
- relevant collection/action permissions in `api/`
- project environment/config files

## Authentication surfaces

This stack exposes multiple auth mechanisms:

- JWT user auth
- refresh token cookie flow
- admin tokens
- token-based permissions for API-style access

Do not mix them casually. Each one has a different operational purpose.

## Recommended token strategy

Use:

- **JWT user auth** for real users in admin or authenticated workflows
- **refresh cookies** for session continuation where appropriate
- **admin tokens** only for server/admin/ops scenarios that truly need that level of access
- **token permissions** for narrow integration access or machine clients

Avoid using broad admin tokens where a narrow project or collection-level token permission is enough.

## Secrets handling

Do not keep production secrets as plain literals in committed config.

Prefer environment-variable substitution for:

- JWT secrets
- SMTP credentials
- LLM API keys
- external API tokens
- admin token values

If a project ships real secrets in config, treat that as a structural problem, not a cosmetic cleanup.

## Bulk permission safety

Bulk mutations are explicitly more dangerous than single-document mutations.

Important rule:

- boolean `post: true` / `put: true` / `delete: true` does not imply bulk access
- bulk requires object-form permissions with `bulk: true`

Do not enable bulk operations casually in website projects. Most editor workflows do not need them.

## Cookie and session hardening

For refresh-token flows, ensure the deployment matches secure cookie expectations.

Important considerations:

- secure cookies should stay enabled in HTTPS environments
- local non-HTTPS development may need explicit relaxation
- do not debug production cookie issues by weakening production defaults globally

## Hook risk surfaces

Current tibi-server exposes powerful server-side capabilities. Some of them require explicit restraint.

Particularly important:

- `http.fetch` / `http.fetchStream` can create SSRF risk
- `exec.command` can create command-execution risk
- broad filesystem/network access in hooks should not be treated as harmless

If a feature can be implemented without shell execution or arbitrary internal fetches, prefer the safer path.

## Query-parameter token risk

Token permissions may be passed through query parameters for specific cases, but this is a documented risk surface.

Prefer header-based token transport when possible.

If query tokens are unavoidable:

- avoid logging full URLs with sensitive query strings
- understand proxy/referrer/history exposure
- scope the token as narrowly as possible

## Permission boundaries

Security on this stack is layered.

Think in terms of:

- project visibility
- collection method permissions
- field-level restrictions
- token scope
- public vs authenticated action access

Do not rely on frontend hiding or convention where server-side permissions should be explicit.

## Secure implementation patterns

### Public form endpoint

Recommended shape:

- public action with narrow allowed methods
- server-side validation
- no broad admin tokens in the browser
- no unnecessary collection write permissions exposed publicly

### Integration token

Recommended shape:

- dedicated narrow token permission set
- minimal collection/action scope
- header-based transport preferred

### Hook that calls external services

Recommended shape:

- fixed or validated destination URLs
- no arbitrary user-controlled internal target fetching
- minimal capability needed for the feature

## Anti-patterns

- Hardcoded production secrets in committed config
- Using admin tokens for routine frontend or integration traffic
- Enabling bulk write permissions without a strong operational reason
- Treating hook `http.fetch` and `exec.command` as risk-free utilities
- Solving access control in the UI instead of on the server

## Verification checklist

After security-relevant changes, verify all of these:

1. Secrets are sourced appropriately.
2. Token type matches the intended actor and scope.
3. Bulk permissions are not broader than necessary.
4. Public endpoints expose only the required methods.
5. Risky hook capabilities are constrained by design.
6. `yarn validate` stays clean.

## What an LLM should inspect first

When asked to harden or design secure access on this starter, inspect in this order:

1. `tibi-server/docs/05-authentication.md`
2. `tibi-server/docs/14-security.md`
3. the relevant collection/action permission sets
4. secret sourcing in config/env
5. whether hooks use risky capabilities like outbound fetch or exec

This prevents “working” implementations that quietly widen the attack surface.