mirror of
https://github.com/therootcompany/golib.git
synced 2026-11-04 06:55:00 +00:00
82 lines
2.4 KiB
Markdown
82 lines
2.4 KiB
Markdown
# expresscookie
|
|
|
|
A general-purpose package for signing and verifying secure cookies in all web applications. Its format is also compatible with the Node.js npm package [`cookie-signature`](https://www.npmjs.com/package/cookie-signature), as used by Express session middleware.
|
|
|
|
Standard HMAC-SHA256 signature:
|
|
|
|
```
|
|
secret: example-secret-16
|
|
string: Hello, World!
|
|
payload: SGVsbG8sIFdvcmxkIQ==
|
|
signed value: s:SGVsbG8sIFdvcmxkIQ==.F/bW1t2GXhUIqykISYbB+FMA3lLquegPU4jYjVLsnXs
|
|
cookie value: s%3ASGVsbG8sIFdvcmxkIQ%3D%3D.F%2FbW1t2GXhUIqykISYbB%2BFMA3lLquegPU4jYjVLsnXs
|
|
```
|
|
|
|
## Usage
|
|
|
|
```sh
|
|
go get github.com/therootcompany/golib/auth/expresscookie@latest
|
|
```
|
|
|
|
Initialize the secret once during application setup:
|
|
|
|
```go
|
|
secret, err := expresscookie.NewSecret([]byte(os.Getenv("COOKIE_SECRET")))
|
|
```
|
|
|
|
> **Payload:** Encode payloads before signing (e.g., base64, JSON). The
|
|
> package signs raw bytes as supplied, but the behavior of non-encoded plain
|
|
> strings is undefined — in particular, raw payloads containing characters
|
|
> such as spaces may not interoperate with Node.js, which uses
|
|
> `encodeURIComponent` rather than query-string escaping. With zero-valued
|
|
> options, the cookie has zero-valued HTTP attributes except for the security
|
|
> defaults applied by `Sign`. These convenience defaults may change.
|
|
|
|
```go
|
|
http.HandleFunc("GET /", func(w http.ResponseWriter, r *http.Request) {
|
|
cookie, err := r.Cookie("session")
|
|
if err != nil {
|
|
return
|
|
}
|
|
signed, err := expresscookie.Parse(cookie.Value)
|
|
if err != nil {
|
|
return
|
|
}
|
|
payload, err := signed.Verify(secret)
|
|
if err != nil {
|
|
http.Error(w, "invalid session", http.StatusUnauthorized)
|
|
return
|
|
}
|
|
_, _ = w.Write(payload)
|
|
})
|
|
```
|
|
|
|
Sign and send a cookie:
|
|
|
|
```go
|
|
payload := base64.StdEncoding.AppendEncode(nil, []byte(`{"user":"123"}`))
|
|
cookie, err := expresscookie.New("session", payload, http.Cookie{
|
|
Expires: time.Now().Add(time.Hour),
|
|
})
|
|
if err != nil {
|
|
return
|
|
}
|
|
signed := cookie.Sign(secret)
|
|
http.SetCookie(w, &signed.Cookie)
|
|
```
|
|
|
|
`DecodeHexSecret` decodes and validates an `APP_SECRET`-style hexadecimal key.
|
|
|
|
## License
|
|
|
|
Authored in 2026 by AJ ONeal.
|
|
|
|
expresscookie is made available under the terms of any of the following
|
|
licenses, at your option:
|
|
|
|
1. [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/)
|
|
2. [MIT License](https://opensource.org/license/mit/)
|
|
3. [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)
|
|
|
|
SPDX-License-Identifier: CC0-1.0 OR MIT OR Apache-2.0
|