agentleFS
ice-lfernandesice-lfernandes/claude-spring-architect/.claude/skills/transport-security-setup/SKILL.md

transport-security-setup

Skill11 starsChanged yesterdayApache-2.0View on GitHub

Decides where TLS terminates for a generated or adopted Spring Boot project — at the edge (ingress, load balancer, Caddy) or in the embedded Tomcat, with mutual TLS as a recorded variant — and writes the matching configuration: forwarded headers and trusted proxies, or an SSL bundle with reload and profile-gated TLS; HTTP/2 on; HSTS with exactly one writer; the integration test that proves it on a real server; a local Caddy edge through docker-architect. Use when the request involves HTTPS, TLS, certificates, HTTP/2, h2c, HSTS, X-Forwarded-Proto, "behind a proxy", "configure https", or when project-bootstrap or arch-adopt finds a project whose root CLAUDE.md has no Transport line.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 2 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every rule this skill applies is @.claude/rules/transport-security.md.

    line 23
  2. Very specific:

    No key, certificate or password is written, anywhere: Not in application.yml, not under src/test/resources, not "for local use".

    line 34
  3. Very specific:

    Project directory: When the caller's one-line context names project: <absolute path>, that directory is the project root, not the …

    line 53
  4. Distinctive:

    When a caller already passed an answer in its one-line context, don't ask it again.

    line 78
  5. Very specific:

    Write templates/HstsHeaderFilter.java.example into the blueprint's configuration package plus .web (config.web, infrastructure.config.web).

    line 118
  6. Very specific:

    Add @ActiveProfiles("test") to each file listed.

    line 141
  7. Distinctive:

    A datasource in the context: When the project has a Testcontainers configuration —

    line 144
  8. Very specific:

    Write the matching paragraph of templates/CLAUDE-transport.md.example into the root CLAUDE.md, placeholders filled, right below the Bounded …

    line 174
  9. Very specific:

    When chained by project-bootstrap, skip: its own Verify runs next and covers the test this skill wrote.

    line 180

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Transport Security Setup

Decides once, per project, how a request reaches it over TLS, and writes what that decision needs. One question decides the shape: where does TLS terminate? At the edge → the application holds no key and learns the scheme from the edge's forwarded headers. In the embedded server → the application loads a mounted certificate through an SSL bundle and serves 8443. Every rule this skill applies is @.claude/rules/transport-security.md; every rule about key material is @.claude/rules/secrets.md.

Entry rule: decide once. The root CLAUDE.md already has a **Transport: paragraph → report "already decided", quote it, and stop. Changing topology is a new decision: the user deletes the paragraph and runs /transport-security-setup again, which then rewrites the configuration it owns. When the paragraph is missing but application.yml already holds server.ssl, spring.ssl.bundle or forward-headers-strategy, the project decided by hand: report the lines found, ask which topology they implement, and write only the paragraph — never rewrite a configuration this skill did not write.

No key, certificate or password is written, anywhere. Not in application.yml, not under src/test/resources, not "for local use". The production files are mounted at run time and their paths come from the environment; the test generates its own certificate when it runs.

Why this is a skill (Form 1) and not Form 2

Form 1: project-bootstrap and arch-adopt chain it by name, and a skill with disable-model-invocation: true cannot be called through the Skill tool — the reason sonarqube-setup stays model-invocable. Axis 2 of the interview — two callers, one of which runs inside a project where project-bootstrap does not exist — made it a skill of its own; the closest rejected form was a transport block inside security-architect, a design skill that writes docs only and runs per use case, so a project with no protected endpoint would never decide transport. Record: @.claude/decisions/0122-transport-security-setup-and-secrets.md.

Runs on sonnet with effort: low: one interview with fixed options, then edits per answer (@.claude/decisions/0080-procedural-skills-on-sonnet.md).

Procedure

Project directory. When the caller's one-line context names project: <absolute path>, that directory is the project root, not the session's: read and write every path of this procedure under it, and run every shell command as (cd "<path>" && …). When this skill chains docker-architect, pass project: <path> on in its context.

1 · Detect

grep -n "^\*\*Transport:" CLAUDE.md 2>/dev/null
grep -rnE "server\.ssl|ssl:|bundle:|forward-headers-strategy" --include='application*.yml' --include='application*.properties' . 2>/dev/null | grep -v /target/
grep -nE "spring-boot-starter-(security|jetty)" pom.xml build.gradle */pom.xml */build.gradle 2>/dev/null
  • **Transport: found → entry rule: report and stop.
  • pom.xml at the root → maven; build.gradle → gradle. The main module is the one with contains_main: true in the active blueprint; its src/main/resources/application.yml is the file this skill merges into.
  • spring-boot-starter-security present → the security filter chain owns HSTS, and step 4 is skipped. Absent → step 4 writes the filter.
  • spring-boot-starter-jetty present → topology B and C are not offered: Jetty does not reload a bundle, and the certificate would expire with the application running. Say so in the question.

2 · Interview — two AskUserQuestion calls

When a caller already passed an answer in its one-line context, don't ask it again.

First call — the topology, with one line of what each costs:

OptionMeans
A · Edge (Recommended)An ingress, load balancer or reverse proxy terminates TLS and renews the certificate; the application holds no key and trusts X-Forwarded-* from the edge's network only
B · DirectThe embedded Tomcat terminates TLS on 8443 with a certificate mounted at run time and reloaded on renewal; the application owns the key
C · Mutual TLSB, and every caller presents a client certificate from a private CA; a missing one fails the handshake, never a 401
C′ · Service meshThe mesh sidecar terminates TLS; the application is configured as in A

Second call, depending on the first:

  • A or C′ — local edge: "Run a local Caddy edge in docker-compose, so HTTPS, HTTP/2 and HSTS behave on the developer's machine as behind the production edge?" — Yes (Recommended) / No — local runs plain HTTP.
  • B or C — two questions in the same call:
    1. Local profile: "Should the local profile skip HTTPS?" — Yes — local and docker run plain HTTP on 8080 (Recommended) / No — local needs a certificate too (mkcert).
    2. Reason for not terminating at the edge, recorded in the paragraph — No proxy in front / Compliance requires TLS up to the process / Clients reach the process directly. Topology C also records that the client-certificate authentication mechanism is designed later, by security-architect, when a use case's access rule names a machine caller with a certificate.

3 · Write the configuration

Merge into the main module's application.yml — into its existing roots, never a second server: or spring: key in the same document:

TopologyExemplarAdjust
A, C′templates/application-tls-edge.yml.examplenothing
Btemplates/application-tls-direct.yml.examplethe first block into the existing roots, the --- document appended at the end. Local profile No → the expression becomes `"!docker & (!testtls)"`
Csame as Balso uncomment the bundle's truststore and server.ssl.client-auth: need

server.http2.enabled: true goes in for every topology.

4 · HSTS — only when step 1 found no Spring Security

Write templates/HstsHeaderFilter.java.example into the blueprint's configuration package plus .web (config.web, infrastructure.config.web); in a blueprint with no configuration package (hexagonal, onion, custom), into a web subpackage of the inbound REST adapter. Base package and package names come from the blueprint's packages.map, never from the exemplar.

With Spring Security present, nothing is written: its default header writer already sends the same value, and the filter would only override it.

5 · The test

TopologyExemplarWhere
A, C′templates/ForwardedHeadersIT.java.examplesrc/test/java/<base package>/ of the main module
B, Ctemplates/TransportSecurityIT.java.examplesame

For B and C, every @SpringBootTest must run with the test profile, or its context now starts with TLS on and fails reading /etc/tls (@.claude/rules/testing.md § Slices and context requires it anyway):

grep -rL '@ActiveProfiles("test")' $(grep -rl "@SpringBootTest" --include='*.java' src/test/ 2>/dev/null) 2>/dev/null

Add @ActiveProfiles("test") to each file listed. The generator's own *ApplicationTests is usually the only one.

A datasource in the context. When the project has a Testcontainers configuration —

grep -rl "class TestcontainersConfiguration" --include='*.java' src/test/ */src/test/ 2>/dev/null

— every @SpringBootTest class of the test you write carries @Import(TestcontainersConfiguration.class). In ForwardedHeadersIT that means each nested class: @NestedTestConfiguration(OVERRIDE) drops the enclosing class's configuration, an import included. Without it, a project with JPA or Flyway starts the context against localhost:5432 — connection refused on a clean machine, or another project's database where one is running (lessons-learned-020 § 2). The exemplars don't carry the import: they are compiled in CI against a project with no datasource, where the class does not exist.

6 · Container — through docker-architect

Invoke docker-architect through the Skill tool with a one-line context, and only in these two cases. It owns every service block and the Dockerfile; don't write either here, not even when it looks like a copy.

  • A or C′ with a local edge → "service edge (Caddy) and docker/caddy/Caddyfile, chained from transport-security-setup — no engine question".
  • B or C → "Dockerfile: the image also listens on 8443 (EXPOSE 8080 8443), chained from transport-security-setup — no service to add".

No docker-compose.yml or Dockerfile at the root → docker-architect stops on its own entry rule; say so in the report.

7 · Record the decision

Write the matching paragraph of templates/CLAUDE-transport.md.example into the root CLAUDE.md, placeholders filled, right below the **Bounded context: paragraph (or below the first heading when there is none). That template owns the wording.

8 · Verify

When chained by project-bootstrap, skip: its own Verify runs next and covers the test this skill wrote. Otherwise run the project's full build — ./mvnw -B verify or ./gradlew build. A red test is reported with its first failing assertion, never "fixed" by loosening the configuration.

Report

✅ Transport decided — topology <A edge | B direct | C mutual TLS | C′ mesh>

Configuration . <application.yml path> — <forwarded headers + trusted proxies | SSL bundle `webserver`, reload, 8443, TLS on except <profiles>> · HTTP/2 on
HSTS .......... <Spring Security's default writer | HstsHeaderFilter in <package>>
Test .......... <ForwardedHeadersIT | TransportSecurityIT> — <green in the build | runs in project-bootstrap's Verify> · @ActiveProfiles("test") added to <n files | none needed>
Container ..... <edge (Caddy) added by docker-architect | Dockerfile EXPOSE 8443 by docker-architect | not touched — <reason>>
CLAUDE.md ..... Transport paragraph written

Then the lines the person needs on day one, by topology:

  • A / C′ — in each environment, set TRUSTED_PROXIES to the edge's addresses (CIDR list); the default trusts every private range. With the local edge: docker compose up -d edge, then docker compose exec edge caddy trust once, and open https://localhost:8443.
  • B / C — mount the certificate and key (PEM, PKCS#8) as files and set TLS_CERTIFICATE and TLS_PRIVATE_KEY to their file: paths; renew them with an ACME client or the platform, never by hand. A Kubernetes secret is mounted as a directory, never with subPath. Probes read /actuator/health/readiness and /liveness. Local profile No → generate a local pair with mkcert localhost outside the repository and point the two variables at it.
  • C — the bundle's truststore holds only the private CA that issues client certificates, from TLS_CLIENT_CA.

Contract

Class: build — the territory is skill_classes.build's override for this skill in @.claude/schemas/extensions.json: the main module's application*.yml, the HstsHeaderFilter.java file, src/test/** (the IT, and the test profile on existing @SpringBootTest classes), and the root CLAUDE.md. ArchHook.java guard enforces it. docker-compose.yml, docker/** and the Dockerfile are deliberately outside it.

Reads the root CLAUDE.md, the build file, the active blueprint's packages.map, and the main module's application*.yml.

Writes the transport configuration, the HSTS filter when no security chain exists, one transport IT, and the **Transport: paragraph — the project fact security-architect, http-client-architect and docker-architect read.

Never writes a certificate, a key, a keystore or a password, in any file.

Delegates the edge service, the Caddyfile and the Dockerfile port to docker-architect, the single owner of both files. Outbound TLS — a client certificate or a private CA for a call this service makes — is http-client-architect's, never this skill's. The client-certificate authentication mechanism of topology C is security-architect's, designed with the first use case that needs it.

Chained by project-bootstrap (step 7.5, before Verify) and arch-adopt (step 7.5), and invocable by hand. Travels into the generated project (export.skills.include): arch-adopt runs inside the project, where project-bootstrap does not exist, and needs this skill there.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.