Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Text assets have byte-exact HTTP lengths and content identities on every host.
* text=auto eol=lf
1 change: 1 addition & 0 deletions .github/FUNDING.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
ko_fi: execsoftware
26 changes: 23 additions & 3 deletions .github/workflows/audit.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,12 +29,32 @@ jobs:
--output scanner.tar.gz
printf '%s scanner.tar.gz\n' 551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb | sha256sum --check -
tar -xzf scanner.tar.gz gitleaks
printf '[extend]\nuseDefault = true\n' > default.toml
: > empty.ignore
- name: Scan the working tree and the fetched history
shell: bash
run: |
set -euo pipefail
"$RUNNER_TEMP/source-scanner/gitleaks" dir . --no-banner --redact
"$RUNNER_TEMP/source-scanner/gitleaks" git . --no-banner --redact
flags=(--no-banner --redact=100 --ignore-gitleaks-allow
--config "$RUNNER_TEMP/source-scanner/default.toml"
--gitleaks-ignore-path "$RUNNER_TEMP/source-scanner/empty.ignore"
--max-archive-depth=2 --max-decode-depth=2 --timeout=120)
"$RUNNER_TEMP/source-scanner/gitleaks" dir . "${flags[@]}"
# Git mode already scans all fetched refs; checkout fetched full history.
"$RUNNER_TEMP/source-scanner/gitleaks" git . "${flags[@]}"
- name: Verify path-audit detection and safe diagnostics
run: python3 -B tests/test_audit_paths.py
- name: Verify wire closure and deadline test oracles
run: |
python3 -B - <<'PY'
import json, os, runpy, tempfile
from pathlib import Path
driver = runpy.run_path('scripts/test-platform.py')
env = dict(os.environ, PYTHONDONTWRITEBYTECODE='1', PYTHONUTF8='1')
with tempfile.TemporaryDirectory(prefix='nilweb-wire-oracle-') as output:
result = driver['run_wire_oracle'](env=env, evidence=Path(output))
print(json.dumps(dict(checks=result['checks'], cleanup_verified=result['cleanup_verified'])))
PY
- name: Refuse absolute paths, routable addresses and contact details
shell: bash
run: |
Expand All @@ -44,6 +64,6 @@ jobs:
# Loopback, the unspecified address and the RFC 5737/3849
# documentation ranges are allowed, because a server has to name an
# address it binds. See scripts/audit-paths.py for the reasoning.
python3 scripts/audit-paths.py --root .
python3 -B scripts/audit-paths.py --root .
# Scan reports are not uploaded. Even redacted findings can expose
# filenames, commit messages and surrounding source context.
123 changes: 123 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
name: Web platform checks

"on":
push:
branches: [master]
pull_request:
workflow_dispatch:

permissions:
contents: read

concurrency:
group: web-platform-${{ github.ref }}
cancel-in-progress: true

# Build the interpreter and host file boundary from this exact public revision.
# These jobs qualify source consumers, not a packaged SDK or native networking.
env:
NIL_FRAMEWORK_REVISION: 93515c3d4c2b6e0e7c3b870eb283fce26392d613
PYTHONDONTWRITEBYTECODE: '1'
PYTHONUTF8: '1'
HOMEBREW_NO_AUTO_UPDATE: '1'

jobs:
web:
name: web-${{ matrix.host.name }}
runs-on: ${{ matrix.host.runner }}
timeout-minutes: 60
strategy:
fail-fast: false
max-parallel: 4
matrix:
host:
- {name: linux-x86_64, runner: ubuntu-24.04, system: Linux, arch: x86_64, python: python3}
- {name: windows-x86_64, runner: windows-2022, system: Windows, arch: x86_64, python: python}
- {name: macos-x86_64, runner: macos-15-intel, system: Darwin, arch: x86_64, python: python3}
- {name: macos-arm64, runner: macos-15, system: Darwin, arch: arm64, python: python3}
defaults:
run:
shell: bash
env:
NIL_CI_PYTHON: ${{ matrix.host.python }}
NIL_CI_SYSTEM: ${{ matrix.host.system }}
NIL_CI_ARCH: ${{ matrix.host.arch }}
steps:
- name: Check out web
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4, same pin as audit
with:
path: web
persist-credentials: false
- name: Check out pinned public framework
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
repository: exec-software/exec-nil-framework
ref: ${{ env.NIL_FRAMEWORK_REVISION }}
path: framework
persist-credentials: false
- name: Verify framework revision and prepare evidence
timeout-minutes: 2
run: |
"$NIL_CI_PYTHON" - <<'PY'
import json, os, platform, re, subprocess
from pathlib import Path
evidence = Path(os.environ['RUNNER_TEMP']) / 'web-build-evidence'
evidence.mkdir()
expected = os.environ['NIL_FRAMEWORK_REVISION']
assert re.fullmatch('[0-9a-f]{40}', expected), 'Framework must be pinned to a full commit SHA'
actual = subprocess.check_output(['git', '-C', 'framework', 'rev-parse', 'HEAD'], text=True, timeout=15).strip()
assert actual == expected
report = dict(framework_revision=actual, web_revision=subprocess.check_output(
['git', '-C', 'web', 'rev-parse', 'HEAD'], text=True, timeout=15).strip(),
system=platform.system(), machine=platform.machine(), llvm=False, native_database_providers=False)
(evidence/'identity.json').write_text(json.dumps(report, indent=2)+'\n')
PY
- name: Configure focused Release build
timeout-minutes: 8
run: |
set -euo pipefail
nil_python_executable="$("$NIL_CI_PYTHON" -c 'import sys; print(sys.executable)')"
cmake -S framework -B "$RUNNER_TEMP/web-framework-build" \
-DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=ON -DNIL_ENABLE_LLVM=OFF \
-DNIL_BUILD_EXPERIMENTAL_TOOLS=OFF \
-DNILCOMPILER_SQLITE_INCLUDE_DIR=OFF -DNILCOMPILER_POSTGRESQL_INCLUDE_DIR=OFF \
"-DPython3_EXECUTABLE=$nil_python_executable" \
2>&1 | tee "$RUNNER_TEMP/web-build-evidence/configure.log"
- name: Build compiler interpreter and host contract
timeout-minutes: 40
run: |
set -euo pipefail
cmake --build "$RUNNER_TEMP/web-framework-build" --config Release --parallel 2 \
--target nilcompiler nilinterpreter nil_rooted_file_snapshot_tests \
2>&1 | tee "$RUNNER_TEMP/web-build-evidence/build.log"
- name: Run exact web and real loopback contracts
timeout-minutes: 8
run: |
"$NIL_CI_PYTHON" - <<'PY'
import os, subprocess, sys
from pathlib import Path
build = Path(os.environ['RUNNER_TEMP']) / 'web-framework-build'
binary = build / 'bin' / 'Release' if os.name == 'nt' else build / 'bin'
suffix = '.exe' if os.name == 'nt' else ''
command = [sys.executable, '-B', 'web/scripts/test-platform.py',
'--compiler', str(binary / ('nilcompiler' + suffix)),
'--interpreter', str(binary / ('nilinterpreter' + suffix)),
'--host-contract', str(binary / ('nil_rooted_file_snapshot_tests' + suffix)),
'--nilstd', str(Path('framework/nilstd/src').resolve()),
'--framework-root', str(Path('framework').resolve()),
'--framework-revision', os.environ['NIL_FRAMEWORK_REVISION'],
'--expected-system', os.environ['NIL_CI_SYSTEM'],
'--expected-machine', os.environ['NIL_CI_ARCH'],
'--output', str(Path(os.environ['RUNNER_TEMP']) / 'web-platform-results')]
subprocess.run(command, check=True, timeout=450)
PY
- name: Upload complete or partial evidence only
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
with:
name: web-${{ matrix.host.name }}-${{ github.sha }}-${{ github.run_attempt }}
path: |
${{ runner.temp }}/web-build-evidence/
${{ runner.temp }}/web-platform-results/evidence/
if-no-files-found: error
retention-days: 14
72 changes: 72 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# Contributing to nil-web

nil-web is a server-side web framework written in Matrix. Start with the
[README](README.md) for its current capabilities, known gaps, and compatible NIL
Framework build. Keep new library behavior in Matrix where the language supports
it, and report any required framework changes separately.

## Development workflow

1. Use the SDK described in the README. Set `NIL_SDK` to its directory if it is
not available through the sibling framework checkout.
2. Keep changes focused and add a regression case under `tests/` when changing
behavior. Use synthetic requests and data.
3. Run the test suite from the repository root:

```sh
./scripts/test.sh
```

This compiles the Matrix tests and runs them with `nilinterpreter`. Report
the SDK revision, platform, and checks run; an interpreter pass does not
establish native-route or cross-platform support.
4. Update the public documentation when setup, APIs, or observed behavior
changes. Describe remaining gaps and any skipped or blocked checks in the
pull request.

Submit changes through a pull request. The public branch requires an approving
review, resolution of review conversations, the GitHub Actions `secrets` check,
and the four `web-*` platform checks. Do not bypass those checks with a direct
push. The platform workflow builds the exact framework revision recorded in
[its configuration](.github/workflows/test.yml), then checks the unit suite,
real loopback HTTP behavior, filesystem boundaries and process cleanup.

For server changes, also exercise the affected HTTP behavior with bounded
clients against a local instance you own, then stop that instance. Keep
ordinary generated outputs under the ignored `build/` directory. The wire and
platform harnesses require a fresh external `--output` directory so their
fixtures and evidence cannot become tracked source.

## Public source review

Do not commit credentials, private configuration, internal notes, real user
requests or session data, developer-specific paths, or generated artifacts.
Use relative paths, explicit configuration, and synthetic examples. Review
history as well as the current files before publishing changes.

Run the path audit from the repository root after staging the intended files:

```sh
python3 -B tests/test_audit_paths.py
python3 -B scripts/audit-paths.py --root .
```

The path audit checks tracked text. The source-security workflow also scans
the working tree and fetched Git history with checksum-pinned
[Gitleaks 8.30.1](https://github.com/gitleaks/gitleaks/releases/tag/v8.30.1).
With that version installed, basic local scanner commands are:

```sh
gitleaks dir . --no-banner --redact
gitleaks git . --no-banner --redact
```

CI additionally fixes the default rule configuration, rejects inline scanner
suppressions, and bounds archive traversal, decoding and scan time.

Do not publish scanner reports or unreviewed logs: even redacted output can
expose private context. Scanning supplements source review; it does not replace
it. Report vulnerabilities through the process in [SECURITY.md](SECURITY.md).

Contributions to original project materials use the repository's
[MIT License](LICENSE). Preserve existing third-party notices.
Loading
Loading