pubface 1.1.2 → 1.1.4

package/.github/codeql/codeql-config.yml

@@ -0,0 +1,10 @@
+name: 'pubface CodeQL config'
+
+# Exclude code that is not part of the production runtime from analysis.
+# The test suite intentionally feeds malformed input and disables TLS
+# verification in fixtures, which generates only false-positive noise, and
+# ee-dist holds the prebuilt binaries, not source we maintain.
+paths-ignore:
+    - test
+    - '**/test/**'
+    - ee-dist

package/.github/workflows/codeql.yml

@@ -0,0 +1,50 @@
+# CodeQL static analysis for code quality and security.
+# See https://docs.github.com/en/code-security/code-scanning
+name: 'CodeQL Advanced'
+
+on:
+    push:
+        branches: ['master']
+    pull_request:
+        branches: ['master']
+    schedule:
+        - cron: '40 17 * * 6'
+
+jobs:
+    analyze:
+        name: Analyze (${{ matrix.language }})
+        runs-on: ubuntu-latest
+        permissions:
+            # required for all workflows
+            security-events: write
+
+            # required to fetch internal or private CodeQL packs
+            packages: read
+
+            # only required for workflows in private repositories
+            actions: read
+            contents: read
+
+        strategy:
+            fail-fast: false
+            matrix:
+                include:
+                    - language: actions
+                      build-mode: none
+                    - language: javascript-typescript
+                      build-mode: none
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v6
+
+            - name: Initialize CodeQL
+              uses: github/codeql-action/init@v4
+              with:
+                  languages: ${{ matrix.language }}
+                  build-mode: ${{ matrix.build-mode }}
+                  config-file: ./.github/codeql/codeql-config.yml
+
+            - name: Perform CodeQL Analysis
+              uses: github/codeql-action/analyze@v4
+              with:
+                  category: '/language:${{matrix.language}}'

package/.github/workflows/release.yaml

@@ -27,8 +27,8 @@ jobs:
             contents: read
             id-token: write
         steps:
-            - uses: actions/checkout@v4
-            - uses: actions/setup-node@v4
+            - uses: actions/checkout@v6
+            - uses: actions/setup-node@v6
               with:
                   node-version: 24
                   registry-url: 'https://registry.npmjs.org'

package/.github/workflows/stale.yml

@@ -3,11 +3,16 @@ on:
     schedule:
         - cron: '30 1 * * *'
 
+permissions:
+    contents: read
+    issues: write
+    pull-requests: write
+
 jobs:
     stale:
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/stale@v8
+            - uses: actions/stale@v9
               with:
                   stale-issue-message: 'This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.'
                   stale-pr-message: 'This PR is stale because it has been open 45 days with no activity. Remove stale label or comment or this will be closed in 10 days.'

package/.github/workflows/test.yaml

@@ -7,16 +7,27 @@ on:
             - master
 
 name: test
+
+permissions:
+    contents: read
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
 jobs:
     test:
         runs-on: ubuntu-latest
+        timeout-minutes: 10
         strategy:
             matrix:
                 node-version: [22, 24]
         steps:
-            - uses: actions/checkout@v4
-            - uses: actions/setup-node@v4
+            - uses: actions/checkout@v6
+            - uses: actions/setup-node@v6
               with:
                   node-version: ${{ matrix.node-version }}
+                  cache: npm
             - run: npm ci
+            - run: npm run lint
             - run: npm test

package/.ncurc.js

@@ -0,0 +1,11 @@
+module.exports = {
+    upgrade: true,
+    // pubface is bundled into standalone binaries with @yao-pkg/pkg, which only
+    // supports CommonJS. Any dependency that ships as pure ESM (no CommonJS
+    // entry point) breaks the pkg build, so such upgrades must be rejected here
+    // and the dependency kept on its last CommonJS-compatible release.
+    reject: [
+        // Add pure-ESM upgrades here as they appear, e.g.:
+        // 'some-package'
+    ]
+};

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.1.2"
+    ".": "1.1.4"
 }

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.1.4](https://github.com/postalsys/pubface/compare/v1.1.3...v1.1.4) (2026-06-19)
+
+
+### Bug Fixes
+
+* bump nodemailer to 9.0.1 ([ec61b8f](https://github.com/postalsys/pubface/commit/ec61b8f4fca81c8776c4dd9e8e15de7e64ffabe3))
+
+## [1.1.3](https://github.com/postalsys/pubface/compare/v1.1.2...v1.1.3) (2026-06-15)
+
+
+### Bug Fixes
+
+* update dependencies ([6950a03](https://github.com/postalsys/pubface/commit/6950a03f4e4c3995367ed409fdafb5d4a2aa1753))
+
 ## [1.1.2](https://github.com/postalsys/pubface/compare/v1.1.1...v1.1.2) (2026-05-29)
 
 

package/CLAUDE.md

@@ -0,0 +1,138 @@
+# Claude Development Guidelines
+
+## Project Overview
+
+pubface resolves the public-facing network interfaces of the current machine.
+For each non-internal local interface it makes an outbound HTTPS request (bound
+to that local address) to a resolver service - by default
+`https://api.nodemailer.com/` - to learn the public IP address the outside world
+sees, then performs a reverse-DNS (PTR) lookup on that IP. It returns an array of
+`{ localAddress, ip, name, family, defaultInterface }` entries.
+
+It ships in two forms:
+
+- A CommonJS module exposing `resolvePublicInterfaces()`.
+- A `pubface` CLI that prints the resolved interfaces as JSON, also distributed
+  as prebuilt standalone binaries.
+
+pubface is a dependency of EmailEngine (`../emailengine`).
+
+## Project Structure
+
+- `index.js` - Main module. Public interface detection, DNS/PTR resolution, the
+  outbound HTTPS resolver request, and result sorting. Exports
+  `resolvePublicInterfaces` plus an `_internal` object used only by the tests.
+- `bin/pubface.js` - CLI entry point (calls `resolvePublicInterfaces` and prints
+  JSON).
+- `test/index.test.js` - Test suite (Node.js native test runner).
+- `eslint.config.mjs` - Flat ESLint config.
+- `package.json` - Also holds the `pkg` build configuration (binary targets).
+
+## Technology Stack
+
+- **Runtime**: Node.js (CommonJS, no build step for the library itself)
+- **Dependencies**: `ipaddr.js` (IP parsing), `nodemailer` (the `nodemailer/lib/fetch`
+  helper is used for the bound outbound HTTPS request)
+- **License**: MIT No Attribution (MIT-0)
+
+## Development Commands
+
+```
+npm test           # Run the test suite (node --test 'test/**/*.test.js')
+npm run lint       # Lint with ESLint
+npm run format     # Format code with Prettier
+npm run update     # Refresh dependencies (see Dependency Management)
+npm run licenses   # Regenerate licenses.txt from production dependencies
+npm run build-source   # Reinstall production-only deps for a binary build
+npm run build-dist     # Build standalone binaries with @yao-pkg/pkg (Brotli compressed)
+npm run build-dist-fast  # Build binaries without compression (faster, for debugging)
+```
+
+## Testing
+
+- Uses the Node.js native test runner (`node:test`) with `node:assert/strict`.
+- Tests live in `test/` and are matched by the `test/**/*.test.js` glob.
+- Tests are hermetic: network, DNS, and `os.networkInterfaces()` are mocked via
+  `node:test` mocks, so no live network access is required. Keep them that way -
+  new tests must not depend on real DNS or the live resolver service.
+- Helper functions are exported through `module.exports._internal` purely so the
+  tests can exercise them; this object is not part of the public API.
+
+## Packaging (@yao-pkg/pkg)
+
+We package pubface into standalone executables with
+[`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg) (the maintained fork of the now
+unmaintained `vercel/pkg`). The build configuration and target list live under
+the `pkg` key in `package.json`; binaries target Node 24 for Linux x64, macOS
+x64, macOS arm64, and Windows x64 and are written to `ee-dist/`.
+
+**`@yao-pkg/pkg` only supports CommonJS.** Every runtime dependency - and the
+project's own code - must be requireable as CommonJS. Do not add pure-ESM
+dependencies (packages that ship only an ESM entry point with no CommonJS
+fallback); they break the binary build even when they work fine under plain
+`node`. When evaluating or upgrading a dependency, confirm it still exposes a
+CommonJS entry point.
+
+## Dependency Management
+
+- `npm run update` removes `node_modules` and `package-lock.json`, runs
+  `ncu -u` (npm-check-updates) to bump every dependency to its latest allowed
+  version, then reinstalls.
+- `.ncurc.js` controls which upgrades `ncu` is allowed to take. Add any package
+  whose newer releases are pure ESM (or otherwise break the `@yao-pkg/pkg` build
+  or our supported Node range) to its `reject` list, with a comment explaining
+  why, so it stays pinned to its last compatible release.
+- After updating dependencies, run `npm run lint` and `npm test`, and remember
+  that production dependency changes are user-facing - commit them with a `fix:`
+  prefix so a release is cut (see Commit Conventions).
+
+## Releases
+
+- Releases are managed by `release-please` (config in `release-please-config.json`
+  and `.release-please-manifest.json`), driven by Conventional Commit messages on
+  `master`.
+- On a release, the `release` workflow publishes to npm with provenance
+  (`npm publish --provenance --access public`).
+- Prebuilt CLI binaries are built locally with `npm run build-dist` and attached
+  to the GitHub release.
+
+## Code Style Rules
+
+- Never use emojis in code or documentation, only printable ASCII characters.
+- Use a single hyphen-minus (`-`) as a dash in UI copy and user-facing strings.
+  Never use double hyphens (`--`), em dashes, or en dashes.
+- The codebase is CommonJS (`require`/`module.exports`, `'use strict'`). Keep new
+  code CommonJS; do not introduce ESM syntax in files that are bundled by
+  `@yao-pkg/pkg`.
+
+## Commit Conventions
+
+- Use [Conventional Commits](https://www.conventionalcommits.org/) - `feat:`,
+  `fix:`, `chore:`, `docs:`, etc. `release-please` relies on these prefixes to
+  decide version bumps and changelog entries.
+- When composing git commit messages, do not include Claude as a co-contributor.
+- For commits that do not change runtime behavior (docs, comments, CI/workflow
+  tweaks, formatting), append `[skip ci]` to the commit message to avoid
+  triggering the GitHub Actions workflows. Exception: do not add `[skip ci]` to
+  commits using a `fix:` or `feat:` prefix - those must run so the release action
+  is triggered.
+
+## After Making Code Changes
+
+1. Run `npm run format` and `npm run lint`.
+2. Run `npm test` and make sure the suite passes.
+3. Consider `/simplify` to review changed code and `/security-review` to check
+   for security issues before committing.
+4. After pushing, check the GitHub Actions runs for the push (for example
+   `gh run list --branch <branch>`) and report their status, including CodeQL. If
+   a run fails for a strange or unrelated reason (for example a checkout step
+   reporting "account suspended", HTTP 403, or other auth/infrastructure errors
+   that have nothing to do with the change), check <https://www.githubstatus.com/>
+   for an active GitHub incident before assuming the failure is caused by the
+   change.
+
+## Related Projects
+
+- **EmailEngine** (`../emailengine`): The primary consumer of pubface and the
+  source of these maintenance conventions. Keep the package-management and
+  release rules here aligned with EmailEngine's.

package/SECURITY.md

@@ -0,0 +1,76 @@
+# Security Policy
+
+pubface is a small library and CLI that resolves the public-facing network
+interfaces of the current machine. For each local interface it makes an outbound
+HTTPS request to a resolver service to learn the public IP address the outside
+world sees, then performs a reverse-DNS (PTR) lookup. It does not store
+credentials or accept inbound connections, but because it is embedded in other
+applications (for example EmailEngine) we take security reports seriously and
+aim to respond quickly.
+
+## Supported Versions
+
+Security fixes are released only against the latest version. We do not backport
+patches to older releases - upgrading to the current release line is the
+supported way to receive security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x     | :white_check_mark: |
+| < 1.0   | :x:                |
+
+If you are on an older version, please upgrade. See the release notes at
+<https://github.com/postalsys/pubface/releases> before updating.
+
+## Reporting a Vulnerability
+
+**Please do not report security vulnerabilities through public GitHub issues,
+pull requests, or discussions.**
+
+Report privately through one of the following channels:
+
+1. **GitHub Security Advisories (preferred).** Open a private report at
+   <https://github.com/postalsys/pubface/security/advisories/new>. This keeps the
+   discussion private until a fix is published and lets us credit you.
+2. **Email.** Send details to **andris@postalsys.com** (the contact listed in
+   [`SECURITY.txt`](SECURITY.txt)). Encrypt sensitive details if possible.
+
+When reporting, please include as much of the following as you can:
+
+- The affected version(s) and environment (pubface version, Node.js version, OS,
+  whether used as a library, the `pubface` CLI, or a prebuilt binary).
+- A clear description of the issue and its impact (e.g. SSRF, injection,
+  information disclosure, denial of service, remote code execution).
+- A minimal proof of concept or reproduction steps.
+- Any suggested remediation, if you have one.
+
+We are a small team, so there is no guaranteed response time - sometimes reports
+are handled within hours, sometimes they take longer. Accepted issues are fixed
+in a new release and coordinated through a GitHub Security Advisory, and
+reporters who wish to be named are credited.
+
+## CVEs
+
+We track and disclose vulnerabilities through GitHub Security Advisories. We do
+not request or manage CVE identifiers ourselves. If you need a CVE assigned for a
+reported issue, please request one yourself - for example, through GitHub's own
+CVE request flow on the published advisory, or another CNA.
+
+## Scope
+
+In scope: the pubface source in this repository - the public-interface
+resolution logic, the DNS/PTR handling, the outbound HTTPS request handling, and
+the `pubface` CLI.
+
+Out of scope:
+
+- Vulnerabilities in your own application code that integrates with pubface.
+- The remote resolver service that pubface queries (by default
+  `https://api.nodemailer.com/`) and any DNS infrastructure it relies on.
+- Misconfiguration of your environment - for example, pointing `RESOLV_URL` at an
+  untrusted resolver endpoint.
+- Issues that require an already-compromised host.
+- Vulnerabilities in third-party dependencies that are already publicly known and
+  have no pubface-specific impact (report those upstream).
+
+Thank you for helping keep pubface and its users safe.

package/SECURITY.txt

@@ -0,0 +1,27 @@
+-----BEGIN PGP SIGNED MESSAGE-----
+Hash: SHA256
+
+Contact: https://github.com/postalsys/pubface/security/advisories/new
+Contact: mailto:andris@postalsys.com
+Expires: 2027-06-01T00:00:00.000Z
+Encryption: https://keys.openpgp.org/vks/v1/by-fingerprint/5D952A46E1D8C931F6364E01DC6C83F4D584D364
+Preferred-Languages: en, et
+Canonical: https://github.com/postalsys/pubface/blob/master/SECURITY.txt
+Policy: https://github.com/postalsys/pubface/blob/master/SECURITY.md
+-----BEGIN PGP SIGNATURE-----
+
+iQJPBAEBCAA5FiEEXZUqRuHYyTH2Nk4B3GyD9NWE02QFAmowLdMbFIAAAAAABAAO
+bWFudTIsMi41KzEuMTIsMCwzAAoJENxsg/TVhNNk9VkP+gLaYxcYWcUOfpLKq7+F
+PvJ5ImuwDYCXTv0ufp+bOZWO+dJHBa77z6rGqGzY47PFzhbDi+CspwiEAe/Njiu2
+UVctz864tu+kjG3ddRHj0CRNAuHds1qIz+wqeECJwiHcRCQ2BD5ZZjo5POYfwumJ
+tkiSE6YnECw0T8HYlYUPQpuO+OU1fLbTEZvhnkD7ekyEzjOxHdwJp2s6X4SB97IQ
+0w0P0gmySiY4oOq1a7Y1H7Gnqzn14slqprAf2o6nHnprdpa+XXx5ypPVRf35UyNU
+1iEjkFebk/IojGuy07rQ6Q6KnxtCQVgeKFKmF0/cw837cWO/gcoeJFg8RTu0+ap2
+0JI2+3f58/fC4f1XHNjDKz+A1vvkP12TehDj4N65t0FXgfe2qfp4L1BfI9KSYnz0
+Zclg2uk3qkStWx4s1sLo0/OHZdozSGgrUWAmN0FS5C8bDUhumzAkdLHe4QC/55Pm
+5sGQAIvKzlMxFQlM4ctbAc1SzqTSy4X1sFSmFXO9DrnnB0thicII5Qv/IxikvNh7
+CQi7ZfKyLq4r/xkit8Ma3kl+ooL3WudFd6VbiqLYlbd0g0XltONt80S7FddwHtsz
+E+Y6RFT2ikGhqjP14mTqKcefp6VHUgEcM+RP1BSbjri3OEt0n78Dkhyn0n9genHC
+Rwrr997ja0xt/OdvTK4fGWS1
+=FLnW
+-----END PGP SIGNATURE-----

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pubface",
-    "version": "1.1.2",
+    "version": "1.1.4",
     "description": "Resolve public network interfaces for current machine",
     "main": "index.js",
     "scripts": {
@@ -29,14 +29,14 @@
     },
     "dependencies": {
         "ipaddr.js": "2.4.0",
-        "nodemailer": "8.0.10"
+        "nodemailer": "9.0.1"
     },
     "devDependencies": {
         "@eslint/js": "^10.0.1",
-        "eslint": "^10.4.0",
+        "@yao-pkg/pkg": "6.20.0",
+        "eslint": "^10.5.0",
         "license-report": "6.8.5",
-        "pkg": "5.8.1",
-        "prettier": "^3.8.3"
+        "prettier": "^3.8.4"
     },
     "pkg": {
         "assets": [
@@ -44,10 +44,10 @@
             "licenses.txt"
         ],
         "targets": [
-            "node18-linux-x64",
-            "node18-macos-x64",
-            "node18-macos-arm64",
-            "node18-win-x64"
+            "node24-linux-x64",
+            "node24-macos-x64",
+            "node24-macos-arm64",
+            "node24-win-x64"
         ],
         "outputPath": "ee-dist"
     }