HarperFast / HarperFast/harper-pro

add_certificate's hosts parameter is validated, documented and stored but never read — certificate scoping silently does nothing

Open
#850 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
3
Forks
0
Avg merge
1d 21h
Merged PRs (30d)
80

Description

## Summary

`add_certificate` accepts a `hosts` parameter, validates it, documents it as the hostnames a certificate is valid for, and persists it on the certificate record — but **nothing ever reads it back**. Certificate selection is driven entirely by the certificate's own SANs (or a separate `hostnames` value from the file-based TLS config), so `hosts` has no effect on anything.

## Mechanism

v5 (`harper-pro`), `security/certificate.ts`:

```ts
// :241 (JSDoc)
* @param req.hosts - Optional list of hostnames this certificate is valid for.

// :256 (validated)
hosts: Joi.array(),

// :320 (persisted)
hosts: req.hosts,
```

Those three are the only occurrences of `hosts` on this path — there is no corresponding read. Host matching for certificate selection comes from the certificate's SANs.

Same shape in v4 at tag `release_4.5.36`, `security/keys.js`:

```js
// :1031 (JSDoc) @param req.hosts - array of allowable hosts
// :1042 (validated) hosts: Joi.array(),
// :1099 (persisted) hosts: req.hosts,
```

The `config.hostname ?? config.hostnames ?? config.host ?? config.hosts` expression at `keys.js:194` looks like the read, but it is not — that reads the file-based `tls:` config block, a different source from the record written at `:1099`.

## Impact

The documented contract is not kept. An operator who adds a certificate with `hosts` set — reasonably expecting to scope which hostnames that certificate will be served for — gets silent acceptance and no scoping. Because the parameter is validated and stored, it survives a round-trip through `list_certificates`, which makes it look like it took effect.

This matters most when several certificates are present and the intent is to constrain which one is presented for a given name: `hosts` reads as the obvious lever for that and does nothing.

## Expected

Either honour `hosts` in certificate selection (matching the documented meaning), or remove it from the schema and JSDoc so the API stops advertising a capability it does not have. If it is retained for forward compatibility, it should at minimum be documented as currently unused.

## Versions

Present in **v5** (`harper-pro` `main`, `security/certificate.ts`) and in **v4** (verified at tag `release_4.5.36`, `security/keys.js`).

Contributor guide

Open the contributing guide

Research direction

Start in v5 security/certificate.ts at the documented, validated, and persisted hosts field, then compare certificate selection with the file-based TLS config path. Check the corresponding v4 implementation in security/keys.js at the cited lines. Done means either hosts affects certificate selection as documented, or the parameter is removed or explicitly documented as unused in both versions.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
security
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.