Skip to content

Building 70 Projects ranging from beginner to advanced so anyone can — learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company 👇

feat(canary): docx generator (zip-patch INCLUDEPICTURE)

CarterPerez-dev82bb3a9f14c6
diff --git a/PROJECTS/beginner/canary-token-generator/backend/cmd/builddocxtemplate/main.go b/PROJECTS/beginner/canary-token-generator/backend/cmd/builddocxtemplate/main.go
index 5bfbba1d..23aa207b 100644
--- a/PROJECTS/beginner/canary-token-generator/backend/cmd/builddocxtemplate/main.go
+++ b/PROJECTS/beginner/canary-token-generator/backend/cmd/builddocxtemplate/main.go
@@ -98,16 +98,25 @@ func main() {
fmt.Printf("wrote %s\n", *out)
}
-func buildTemplate(out string) error {
- if err := os.MkdirAll(filepath.Dir(out), dirPerm); err != nil {
- return fmt.Errorf("mkdir parent: %w", err)
+func buildTemplate(out string) (err error) {
+ cleaned := filepath.Clean(out)
+ if mkErr := os.MkdirAll(filepath.Dir(cleaned), dirPerm); mkErr != nil {
+ return fmt.Errorf("mkdir parent: %w", mkErr)
}
- f, err := os.OpenFile(out, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, filePerm)
- if err != nil {
- return fmt.Errorf("open output: %w", err)
+ f, oErr := os.OpenFile(
+ cleaned,
+ os.O_CREATE|os.O_TRUNC|os.O_WRONLY,
+ filePerm,
+ )
+ if oErr != nil {
+ return fmt.Errorf("open output: %w", oErr)
}
- defer f.Close()
+ defer func() {
+ if cerr := f.Close(); cerr != nil && err == nil {
+ err = fmt.Errorf("close output: %w", cerr)
+ }
+ }()
w := zip.NewWriter(f)
for _, e := range entries() {
@@ -120,8 +129,8 @@ func buildTemplate(out string) error {
return fmt.Errorf("write %s: %w", e.name, wErr)
}
}
- if err := w.Close(); err != nil {
- return fmt.Errorf("close zip writer: %w", err)
+ if zErr := w.Close(); zErr != nil {
+ return fmt.Errorf("close zip writer: %w", zErr)
}
return nil
}
diff --git a/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/docx/generator.go b/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/docx/generator.go
new file mode 100644
index 00000000..c8c1575e
--- /dev/null
+++ b/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/docx/generator.go
@@ -0,0 +1,192 @@
+// ©AngelaMos | 2026
+// generator.go
+
+package docx
+
+import (
+ "archive/zip"
+ "bytes"
+ "context"
+ _ "embed"
+ "fmt"
+ "io"
+ "net"
+ "net/http"
+ "strings"
+
+ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/event"
+ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/token"
+ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/token/generators"
+ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/token/generators/pixel"
+)
+
+const (
+ headerCFConnectingIP = "CF-Connecting-IP"
+ headerXForwardedFor = "X-Forwarded-For"
+ headerXRealIP = "X-Real-IP"
+ headerReferer = "Referer"
+ headerCacheControl = "Cache-Control"
+ headerPragma = "Pragma"
+
+ cacheControlNoStore = "no-store, no-cache, must-revalidate, max-age=0"
+ pragmaNoCache = "no-cache"
+
+ triggerPathPrefix = "/c/"
+
+ placeholder = "HONEY_TRACK_URL"
+ footerEntry = "word/footer2.xml"
+
+ contentType = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+ defaultFilename = "Document.docx"
+)
+
+//go:embed template/template.docx
+var docxTemplate []byte
+
+type Generator struct{}
+
+func New() *Generator { return &Generator{} }
+
+func (g *Generator) Type() token.Type { return token.TypeDocx }
+
+func (g *Generator) Generate(
+ _ context.Context,
+ t *token.Token,
+ baseURL string,
+) (generators.Artifact, error) {
+ triggerURL := strings.TrimRight(baseURL, "/") + triggerPathPrefix + t.ID
+
+ patched, err := patchTemplate(docxTemplate, triggerURL)
+ if err != nil {
+ return generators.Artifact{}, err
+ }
+
+ return generators.Artifact{
+ Kind: generators.KindFile,
+ Filename: resolveFilename(t.Filename),
+ Content: patched,
+ ContentType: contentType,
+ }, nil
+}
+
+func (g *Generator) Trigger(
+ _ context.Context,
+ t *token.Token,
+ r *http.Request,
+) (*event.Event, *generators.TriggerResponse, error) {
+ resp := &generators.TriggerResponse{
+ StatusCode: http.StatusOK,
+ ContentType: pixel.ContentType,
+ Body: pixel.Clone(),
+ ExtraHeaders: map[string]string{
+ headerCacheControl: cacheControlNoStore,
+ headerPragma: pragmaNoCache,
+ },
+ }
+
+ if t == nil {
+ return nil, resp, nil
+ }
+
+ evt := &event.Event{
+ TokenID: t.ID,
+ SourceIP: realIP(r),
+ UserAgent: optionalHeader(r.UserAgent()),
+ Referer: optionalHeader(r.Header.Get(headerReferer)),
+ }
+ return evt, resp, nil
+}
+
+func resolveFilename(name *string) string {
+ if name == nil {
+ return defaultFilename
+ }
+ trimmed := strings.TrimSpace(*name)
+ if trimmed == "" {
+ return defaultFilename
+ }
+ return trimmed
+}
+
+func patchTemplate(template []byte, triggerURL string) ([]byte, error) {
+ in, err := zip.NewReader(bytes.NewReader(template), int64(len(template)))
+ if err != nil {
+ return nil, fmt.Errorf("docx: parse template: %w", err)
+ }
+
+ var out bytes.Buffer
+ w := zip.NewWriter(&out)
+ for _, f := range in.File {
+ rc, oErr := f.Open()
+ if oErr != nil {
+ return nil, fmt.Errorf("docx: open %s: %w", f.Name, oErr)
+ }
+ body, rErr := io.ReadAll(rc)
+ cErr := rc.Close()
+ if rErr != nil {
+ return nil, fmt.Errorf("docx: read %s: %w", f.Name, rErr)
+ }
+ if cErr != nil {
+ return nil, fmt.Errorf("docx: close %s: %w", f.Name, cErr)
+ }
+
+ if f.Name == footerEntry {
+ body = bytes.Replace(
+ body,
+ []byte(placeholder),
+ []byte(triggerURL),
+ 1,
+ )
+ }
+
+ hdr := &zip.FileHeader{Name: f.Name, Method: f.Method}
+ fw, cErr := w.CreateHeader(hdr)
+ if cErr != nil {
+ return nil, fmt.Errorf("docx: create %s: %w", f.Name, cErr)
+ }
+ if _, wErr := fw.Write(body); wErr != nil {
+ return nil, fmt.Errorf("docx: write %s: %w", f.Name, wErr)
+ }
+ }
+ if err := w.Close(); err != nil {
+ return nil, fmt.Errorf("docx: close zip writer: %w", err)
+ }
+ return out.Bytes(), nil
+}
+
+func optionalHeader(v string) *string {
+ v = strings.TrimSpace(v)
+ if v == "" {
+ return nil
+ }
+ return &v
+}
+
+func realIP(r *http.Request) string {
+ if v := strings.TrimSpace(r.Header.Get(headerCFConnectingIP)); v != "" {
+ return v
+ }
+ if v := lastNonEmptyXFF(r.Header.Get(headerXForwardedFor)); v != "" {
+ return v
+ }
+ if v := strings.TrimSpace(r.Header.Get(headerXRealIP)); v != "" {
+ return v
+ }
+ if host, _, err := net.SplitHostPort(r.RemoteAddr); err == nil {
+ return host
+ }
+ return r.RemoteAddr
+}
+
+func lastNonEmptyXFF(header string) string {
+ if header == "" {
+ return ""
+ }
+ parts := strings.Split(header, ",")
+ for i := len(parts) - 1; i >= 0; i-- {
+ if v := strings.TrimSpace(parts[i]); v != "" {
+ return v
+ }
+ }
+ return ""
+}
diff --git a/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/docx/generator_test.go b/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/docx/generator_test.go
new file mode 100644
index 00000000..3dd5135a
--- /dev/null
+++ b/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/docx/generator_test.go
@@ -0,0 +1,577 @@
+// ©AngelaMos | 2026
+// generator_test.go
+
+package docx_test
+
+import (
+ "archive/zip"
+ "bytes"
+ "context"
+ _ "embed"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+
+ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/token"
+ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/token/generators"
+ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/token/generators/docx"
+ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/token/generators/pixel"
+)
+
+//go:embed template/template.docx
+var rawTemplate []byte
+
+const (
+ testBaseURL = "https://canary.example.com"
+ placeholderLiteral = "HONEY_TRACK_URL"
+ footerEntryName = "word/footer2.xml"
+ docxContentTypeMIME = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+ defaultFilename = "Document.docx"
+ cacheControlNoStoreValue = "no-store, no-cache, must-revalidate, max-age=0"
+ pragmaNoCacheValue = "no-cache"
+ gifByteLength = 43
+)
+
+func newDocxToken(id string) *token.Token {
+ return &token.Token{
+ ID: id,
+ ManageID: "manage-" + id,
+ Type: token.TypeDocx,
+ Memo: "unit test docx",
+ AlertChannel: token.ChannelWebhook,
+ Enabled: true,
+ }
+}
+
+func newDocxTokenWithFilename(id, filename string) *token.Token {
+ tok := newDocxToken(id)
+ tok.Filename = &filename
+ return tok
+}
+
+func readFooterXML(t *testing.T, archive []byte) []byte {
+ t.Helper()
+ r, err := zip.NewReader(
+ bytes.NewReader(archive),
+ int64(len(archive)),
+ )
+ require.NoError(t, err)
+ for _, f := range r.File {
+ if f.Name != footerEntryName {
+ continue
+ }
+ rc, oErr := f.Open()
+ require.NoError(t, oErr)
+ body, rErr := io.ReadAll(rc)
+ require.NoError(t, rc.Close())
+ require.NoError(t, rErr)
+ return body
+ }
+ t.Fatalf("entry %q not found in zip", footerEntryName)
+ return nil
+}
+
+func zipEntryBodies(t *testing.T, archive []byte) map[string][]byte {
+ t.Helper()
+ r, err := zip.NewReader(
+ bytes.NewReader(archive),
+ int64(len(archive)),
+ )
+ require.NoError(t, err)
+ out := make(map[string][]byte, len(r.File))
+ for _, f := range r.File {
+ rc, oErr := f.Open()
+ require.NoError(t, oErr)
+ body, rErr := io.ReadAll(rc)
+ require.NoError(t, rc.Close())
+ require.NoError(t, rErr)
+ out[f.Name] = body
+ }
+ return out
+}
+
+func zipEntryMethods(t *testing.T, archive []byte) map[string]uint16 {
+ t.Helper()
+ r, err := zip.NewReader(
+ bytes.NewReader(archive),
+ int64(len(archive)),
+ )
+ require.NoError(t, err)
+ out := make(map[string]uint16, len(r.File))
+ for _, f := range r.File {
+ out[f.Name] = f.Method
+ }
+ return out
+}
+
+func TestGenerator_TypeIsDocx(t *testing.T) {
+ g := docx.New()
+ require.Equal(t, token.TypeDocx, g.Type())
+}
+
+func TestGenerate_ArtifactKindIsFile(t *testing.T) {
+ g := docx.New()
+ art, err := g.Generate(
+ context.Background(),
+ newDocxToken("abc"),
+ testBaseURL,
+ )
+ require.NoError(t, err)
+ require.Equal(t, generators.KindFile, art.Kind)
+}
+
+func TestGenerate_ContentTypeIsDocxMIME(t *testing.T) {
+ g := docx.New()
+ art, err := g.Generate(
+ context.Background(),
+ newDocxToken("abc"),
+ testBaseURL,
+ )
+ require.NoError(t, err)
+ require.Equal(t, docxContentTypeMIME, art.ContentType)
+}
+
+func TestGenerate_Filename(t *testing.T) {
+ g := docx.New()
+
+ t.Run("nil Filename defaults to Document.docx", func(t *testing.T) {
+ art, err := g.Generate(
+ context.Background(),
+ newDocxToken("abc"),
+ testBaseURL,
+ )
+ require.NoError(t, err)
+ require.Equal(t, defaultFilename, art.Filename)
+ })
+
+ t.Run(
+ "empty Filename pointer defaults to Document.docx",
+ func(t *testing.T) {
+ art, err := g.Generate(
+ context.Background(),
+ newDocxTokenWithFilename("abc", ""),
+ testBaseURL,
+ )
+ require.NoError(t, err)
+ require.Equal(t, defaultFilename, art.Filename)
+ },
+ )
+
+ t.Run(
+ "whitespace-only Filename defaults to Document.docx",
+ func(t *testing.T) {
+ art, err := g.Generate(
+ context.Background(),
+ newDocxTokenWithFilename("abc", " "),
+ testBaseURL,
+ )
+ require.NoError(t, err)
+ require.Equal(t, defaultFilename, art.Filename)
+ },
+ )
+
+ t.Run("set Filename is preserved (trimmed)", func(t *testing.T) {
+ art, err := g.Generate(
+ context.Background(),
+ newDocxTokenWithFilename("abc", " Q4-Plan.docx "),
+ testBaseURL,
+ )
+ require.NoError(t, err)
+ require.Equal(t, "Q4-Plan.docx", art.Filename)
+ })
+}
+
+func TestGenerate_TriggerURL(t *testing.T) {
+ g := docx.New()
+
+ t.Run("base URL trailing slash trimmed", func(t *testing.T) {
+ artA, err := g.Generate(
+ context.Background(),
+ newDocxToken("tk1"),
+ "https://canary.example.com",
+ )
+ require.NoError(t, err)
+ artB, err := g.Generate(
+ context.Background(),
+ newDocxToken("tk1"),
+ "https://canary.example.com/",
+ )
+ require.NoError(t, err)
+
+ bodyA := readFooterXML(t, artA.Content)
+ bodyB := readFooterXML(t, artB.Content)
+ require.Contains(t, string(bodyA), "https://canary.example.com/c/tk1")
+ require.Contains(t, string(bodyB), "https://canary.example.com/c/tk1")
+ })
+
+ t.Run("base URL subpath preserved", func(t *testing.T) {
+ art, err := g.Generate(
+ context.Background(),
+ newDocxToken("tk2"),
+ "https://example.com/canary",
+ )
+ require.NoError(t, err)
+ body := readFooterXML(t, art.Content)
+ require.Contains(t, string(body), "https://example.com/canary/c/tk2")
+ })
+
+ t.Run("different token ids produce distinct outputs", func(t *testing.T) {
+ artA, err := g.Generate(
+ context.Background(),
+ newDocxToken("aaa"),
+ testBaseURL,
+ )
+ require.NoError(t, err)
+ artB, err := g.Generate(
+ context.Background(),
+ newDocxToken("bbb"),
+ testBaseURL,
+ )
+ require.NoError(t, err)
+ require.NotEqual(t, artA.Content, artB.Content)
+ })
+}
+
+func TestGenerate_OutputIsValidZip(t *testing.T) {
+ g := docx.New()
+ art, err := g.Generate(
+ context.Background(),
+ newDocxToken("abc"),
+ testBaseURL,
+ )
+ require.NoError(t, err)
+
+ r, zErr := zip.NewReader(
+ bytes.NewReader(art.Content),
+ int64(len(art.Content)),
+ )
+ require.NoError(t, zErr, "generated docx must parse as a zip archive")
+ require.NotEmpty(t, r.File, "zip must contain at least one entry")
+}
+
+func TestGenerate_FooterContainsTriggerURL(t *testing.T) {
+ g := docx.New()
+ art, err := g.Generate(
+ context.Background(),
+ newDocxToken("token42"),
+ testBaseURL,
+ )
+ require.NoError(t, err)
+
+ body := readFooterXML(t, art.Content)
+ require.Contains(
+ t,
+ string(body),
+ "https://canary.example.com/c/token42",
+ "footer must reference the canary trigger URL after substitution",
+ )
+}
+
+func TestGenerate_FooterDoesNotContainPlaceholder(t *testing.T) {
+ g := docx.New()
+ art, err := g.Generate(
+ context.Background(),
+ newDocxToken("xyz"),
+ testBaseURL,
+ )
+ require.NoError(t, err)
+
+ body := readFooterXML(t, art.Content)
+ require.NotContains(
+ t,
+ string(body),
+ placeholderLiteral,
+ "placeholder must be fully substituted in footer2.xml",
+ )
+}
+
+func TestGenerate_OtherEntriesUnchanged(t *testing.T) {
+ g := docx.New()
+ art, err := g.Generate(
+ context.Background(),
+ newDocxToken("abc"),
+ testBaseURL,
+ )
+ require.NoError(t, err)
+
+ templateBodies := zipEntryBodies(t, rawTemplate)
+ outputBodies := zipEntryBodies(t, art.Content)
+ require.Len(
+ t,
+ outputBodies,
+ len(templateBodies),
+ "output must have the same entry count as the template",
+ )
+
+ for name, tmplBody := range templateBodies {
+ outBody, ok := outputBodies[name]
+ require.True(t, ok, "output missing template entry %q", name)
+ if name == footerEntryName {
+ require.NotEqual(
+ t,
+ tmplBody,
+ outBody,
+ "footer2.xml must change after substitution",
+ )
+ continue
+ }
+ require.Equal(
+ t,
+ tmplBody,
+ outBody,
+ "non-footer entry %q must be byte-identical to template",
+ name,
+ )
+ }
+}
+
+func TestGenerate_PreservesCompressionMethods(t *testing.T) {
+ g := docx.New()
+ art, err := g.Generate(
+ context.Background(),
+ newDocxToken("abc"),
+ testBaseURL,
+ )
+ require.NoError(t, err)
+
+ templateMethods := zipEntryMethods(t, rawTemplate)
+ outputMethods := zipEntryMethods(t, art.Content)
+
+ hasStore, hasDeflate := false, false
+ for _, m := range templateMethods {
+ switch m {
+ case zip.Store:
+ hasStore = true
+ case zip.Deflate:
+ hasDeflate = true
+ }
+ }
+ require.True(
+ t,
+ hasStore && hasDeflate,
+ "template must mix STORE and DEFLATE for this test to be a real regression guard",
+ )
+
+ for name, tmplMethod := range templateMethods {
+ outMethod, ok := outputMethods[name]
+ require.True(t, ok, "output missing template entry %q", name)
+ require.Equal(
+ t,
+ tmplMethod,
+ outMethod,
+ "entry %q method mismatch (template=%d, output=%d)",
+ name,
+ tmplMethod,
+ outMethod,
+ )
+ }
+}
+
+func TestTrigger_ReturnsGIFLikeWebbug(t *testing.T) {
+ g := docx.New()
+ tok := newDocxToken("abc")
+ r := httptest.NewRequest(http.MethodGet, "/c/abc", nil)
+
+ _, resp, err := g.Trigger(context.Background(), tok, r)
+ require.NoError(t, err)
+ require.NotNil(t, resp)
+ require.Equal(t, http.StatusOK, resp.StatusCode)
+ require.Equal(t, pixel.ContentType, resp.ContentType)
+ require.Len(t, resp.Body, gifByteLength)
+ require.Equal(t, pixel.Clone(), resp.Body)
+ require.Equal(
+ t,
+ cacheControlNoStoreValue,
+ resp.ExtraHeaders["Cache-Control"],
+ )
+ require.Equal(t, pragmaNoCacheValue, resp.ExtraHeaders["Pragma"])
+}
+
+func TestTrigger_RecordsEventWithRequestMetadata(t *testing.T) {
+ g := docx.New()
+ tok := newDocxToken("token1")
+
+ t.Run(
+ "captures token id, source ip, user agent, referer",
+ func(t *testing.T) {
+ r := httptest.NewRequest(http.MethodGet, "/c/token1", nil)
+ r.Header.Set("CF-Connecting-IP", "203.0.113.50")
+ r.Header.Set("User-Agent", "LibreOffice/24.2")
+ r.Header.Set("Referer", "https://victim.example.com/inbox")
+
+ evt, _, err := g.Trigger(context.Background(), tok, r)
+ require.NoError(t, err)
+ require.NotNil(t, evt)
+ require.Equal(t, "token1", evt.TokenID)
+ require.Equal(t, "203.0.113.50", evt.SourceIP)
+ require.NotNil(t, evt.UserAgent)
+ require.Equal(t, "LibreOffice/24.2", *evt.UserAgent)
+ require.NotNil(t, evt.Referer)
+ require.Equal(t, "https://victim.example.com/inbox", *evt.Referer)
+ },
+ )
+
+ t.Run("source ip precedence", func(t *testing.T) {
+ cases := []struct {
+ name string
+ headers map[string]string
+ remote string
+ wantIP string
+ }{
+ {
+ name: "CF wins over XFF and XRI",
+ headers: map[string]string{
+ "CF-Connecting-IP": "203.0.113.10",
+ "X-Forwarded-For": "198.51.100.1, 198.51.100.2",
+ "X-Real-IP": "192.0.2.99",
+ },
+ remote: "127.0.0.1:9999",
+ wantIP: "203.0.113.10",
+ },
+ {
+ name: "XFF rightmost wins over XRI when no CF",
+ headers: map[string]string{
+ "X-Forwarded-For": "198.51.100.1, 198.51.100.7",
+ "X-Real-IP": "192.0.2.99",
+ },
+ remote: "127.0.0.1:9999",
+ wantIP: "198.51.100.7",
+ },
+ {
+ name: "XFF trailing-comma falls through to last non-empty",
+ headers: map[string]string{
+ "X-Forwarded-For": "198.51.100.1, ",
+ "X-Real-IP": "192.0.2.99",
+ },
+ remote: "127.0.0.1:9999",
+ wantIP: "198.51.100.1",
+ },
+ {
+ name: "XFF entirely empty entries fall through to XRI",
+ headers: map[string]string{
+ "X-Forwarded-For": ", ,",
+ "X-Real-IP": "192.0.2.99",
+ },
+ remote: "127.0.0.1:9999",
+ wantIP: "192.0.2.99",
+ },
+ {
+ name: "XRI when no CF or XFF",
+ headers: map[string]string{
+ "X-Real-IP": "192.0.2.99",
+ },
+ remote: "127.0.0.1:9999",
+ wantIP: "192.0.2.99",
+ },
+ {
+ name: "RemoteAddr IPv4 strips port",
+ headers: nil,
+ remote: "127.0.0.1:9999",
+ wantIP: "127.0.0.1",
+ },
+ {
+ name: "RemoteAddr IPv6 strips brackets and port",
+ headers: nil,
+ remote: "[2001:db8::1]:54321",
+ wantIP: "2001:db8::1",
+ },
+ {
+ name: "RemoteAddr without port falls back to raw value",
+ headers: nil,
+ remote: "127.0.0.1",
+ wantIP: "127.0.0.1",
+ },
+ {
+ name: "CF value is trimmed of whitespace",
+ headers: map[string]string{
+ "CF-Connecting-IP": " 203.0.113.10 ",
+ },
+ remote: "127.0.0.1:9999",
+ wantIP: "203.0.113.10",
+ },
+ }
+ for _, tc := range cases {
+ tc := tc
+ t.Run(tc.name, func(t *testing.T) {
+ r := httptest.NewRequest(http.MethodGet, "/c/token1", nil)
+ for k, v := range tc.headers {
+ r.Header.Set(k, v)
+ }
+ r.RemoteAddr = tc.remote
+ evt, _, err := g.Trigger(context.Background(), tok, r)
+ require.NoError(t, err)
+ require.NotNil(t, evt)
+ require.Equal(t, tc.wantIP, evt.SourceIP)
+ })
+ }
+ })
+
+ t.Run(
+ "missing user agent and referer record as nil pointers",
+ func(t *testing.T) {
+ r := httptest.NewRequest(http.MethodGet, "/c/token1", nil)
+ r.Header.Del("User-Agent")
+ r.Header.Del("Referer")
+ r.Header.Set("CF-Connecting-IP", "203.0.113.5")
+
+ evt, _, err := g.Trigger(context.Background(), tok, r)
+ require.NoError(t, err)
+ require.NotNil(t, evt)
+ require.Nil(
+ t,
+ evt.UserAgent,
+ "absent user agent must map to nil, not empty string",
+ )
+ require.Nil(
+ t,
+ evt.Referer,
+ "absent referer must map to nil, not empty string",
+ )
+ },
+ )
+}
+
+func TestTrigger_ResponseBodyIsIndependentCopyPerCall(t *testing.T) {
+ g := docx.New()
+ tok := newDocxToken("abc")
+ r := httptest.NewRequest(http.MethodGet, "/c/abc", nil)
+
+ _, resp1, err := g.Trigger(context.Background(), tok, r)
+ require.NoError(t, err)
+ _, resp2, err := g.Trigger(context.Background(), tok, r)
+ require.NoError(t, err)
+
+ resp1.Body[0] = 0x00
+ require.Equal(
+ t,
+ byte(0x47),
+ resp2.Body[0],
+ "each Trigger call must produce an independent body slice",
+ )
+}
+
+func TestTrigger_TokenNotFound_StillReturnsGIF(t *testing.T) {
+ g := docx.New()
+ r := httptest.NewRequest(http.MethodGet, "/c/does-not-exist", nil)
+ r.Header.Set("CF-Connecting-IP", "203.0.113.100")
+ r.Header.Set("User-Agent", "curl/8.0.0")
+
+ evt, resp, err := g.Trigger(context.Background(), nil, r)
+ require.NoError(
+ t,
+ err,
+ "nil-token path must not error (spec §8.5 defense-in-depth)",
+ )
+ require.NotNil(t, resp, "nil-token path must still return GIF response")
+ require.Equal(t, http.StatusOK, resp.StatusCode)
+ require.Equal(t, pixel.ContentType, resp.ContentType)
+ require.Equal(t, pixel.Clone(), resp.Body)
+ require.Nil(
+ t,
+ evt,
+ "nil-token path returns nil event so the handler cannot persist a row with empty TokenID (FK violation)",
+ )
+}