well-known/README.md

# Well-known

A tiny service collecting and aggregating [well-known](https://www.rfc-editor.org/rfc/rfc5785) data from services in the same Kubernetes namespace. The data is merged and exposed as JSON object or plain text.

We support one subdirectory level, which is not according to spec, but required by some applications.


## Usage

Add an annotation to a service:

| annotation                    | directory                        | description  |
|-------------------------------|----------------------------------|--------------|
| `well-known.252.no/[file]`    | `.well-known/[file]`             | filename/key |
| `well-known.252.no/directory` | `.well-known/[directory]/[file]` | subdirectory |
| `well-known.252.no/format`    | -                                | json or text |


## Installation

Find the Helm OCI for Kubernetes in [charts/well-known](https://code.252.no/tommy/-/packages/container/charts%2Fwell-known).

## Examples

### Nostr

```yaml
apiVersion: v1
kind: Service
metadata:
  name: well-known-nostr
  annotations:
    well-known.252.no/nostr.json: |
      {
        "names":  { "${NOSTR_NICK}": "${NOSTR_PUBLIC_KEY_HEX}" },
        "relays": {"${NOSTR_PUBLIC_KEY_HEX}": [ "wss://nostr.${PUBLIC_DOMAIN}" ] }
      }
spec:
  selector:
    app: dummy-app
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
```

### security.txt

```yaml
apiVersion: v1
kind: Service
metadata:
  name: well-known-securitytxt
  annotations:
    well-known.252.no/security.txt: |
      -----BEGIN PGP SIGNED MESSAGE-----
      Hash: SHA512


      Canonical: https://252.no/.well-known/security.txt

      # In case of security issue, please contact:
      Contact: mailto:tommy@252.no
      Encryption: openpgp4fpr:088194F806EBADEE1B48B1CBC0A38C49BB2258E8
      Preferred-Languages: en, no
      # other means of encryption at: https://keyoxide.org/tommy@252.no

      Expires: 2025-09-25T08:00:00.000Z


      -----BEGIN PGP SIGNATURE-----

      iHUEARYKAB0WIQQIgZT4Buut7htIscvAo4xJuyJY6AUCZvOjwQAKCRDAo4xJuyJY
      6JHoAQC2o7ABiFi0EdYtw/2YdFvBvVG9lv6ZK2PYS7GlGGsN/QD9Ee82Fd0/yiCO
      kDSN/3PhZqnWAHIltG3Fnshf/x0NDAg=
      =Meg5
      -----END PGP SIGNATURE-----
spec:
  selector:
    app: dummy-app
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
```

### Matrix Synapse

```yaml
apiVersion: v1
kind: Service
metadata:
  name: well-known-matrix
  annotations:
    well-known.252.no/directory: matrix
    well-known.252.no/format: json
    well-known.252.no/client: |
      {
        "m.homeserver": {
            "base_url": "https://synapse.${PUBLIC_DOMAIN}"
        },
        "org.matrix.msc3575.proxy": {
          "url": "https://slidingsync.${PUBLIC_DOMAIN}"
        },
        "org.matrix.msc2965.authentication": {
          "issuer": "https://auth.matrix.${PUBLIC_DOMAIN}/",
          "account": "https://auth.matrix.${PUBLIC_DOMAIN}/account/"
        }
      }
    well-known.252.no/server: |
      {"m.server":"synapse.${PUBLIC_DOMAIN}:443"}
spec:
  selector:
    app: dummy-app
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: webfinger-oidc
  annotations:
    well-known.252.no/webfinger.json: |
      {
        "subject": "acct:${PUBLIC_EMAIL}",
        "links": [
          {
            "rel": "http://openid.net/specs/connect/1.0/issuer",
            "href": "https://auth.${PUBLIC_DOMAIN}"
          }
        ]
      }
spec:
  selector:
    app: dummy-app
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
```
## Query Example

```
curl https://[ingress]/.well-known/test.json

{
    "example": "value"
}
```

## Gratitude

This version of well-known is based on the work by [Stenic](https://github.com/stenic/well-known/tree/main).