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

name, description

name	description
security-hardening-and-token-strategy	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.