✨ feat: enhance project setup and architecture documentation
- Updated `tibi-project-setup` skill to clarify project initialization goals and steps. - Improved `tibi-ssr-caching` skill to detail SSR architecture, responsibilities, and caching mechanisms. - Introduced `website-solution-architecture` skill for translating website requirements into coherent solutions. - Refined `AGENTS.md` to provide a structured roadmap for project development phases. - Added `ADMIN_ASSET_VERSION` to `api/config.yml.env` for asset versioning. - Updated SSR request flow and cache invalidation logic in `api/hooks/ssr/AGENTS.md`. - Removed obsolete `esbuild.config.admin.js` and integrated asset versioning into the main `esbuild.config.js`. - Adjusted `api/collections/content.yml` to utilize asset versioning for admin scripts.
This commit is contained in:
@@ -0,0 +1,183 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user