Skip to content
Merged
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
40 changes: 40 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
name: Bug report
about: Report a reproducible defect in the resolver or its documentation
title: ""
labels: ""
assignees: ""
---

## Summary

<!-- Describe the smallest problem in one or two sentences. -->

## Expected behavior

<!-- What should happen? Include the relevant contract or documentation link if known. -->

## Actual behavior

<!-- What happened instead? Include the complete error, status code, or assertion. -->

## Reproduction

<!-- Include a minimal reproducer, fixture shape, command, or test name. -->

```text

```

## Environment

- Version or commit:
- Operating system and architecture:
- Compiler and version:
- CMake version:
- Build/test preset or command:
- OpenUSD/OpenStrata version, if applicable:

## Additional context

<!-- Add logs, metrics, or links that are safe to publish. Remove credentials and private URLs. -->
8 changes: 8 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
blank_issues_enabled: false
contact_links:
- name: Report a security vulnerability
url: https://github.com/animu-sphere/usd-http-resolver/security/advisories/new
about: Use GitHub Private Vulnerability Reporting. Do not disclose vulnerabilities in a public issue.
- name: Read the contributor guide
url: https://github.com/animu-sphere/usd-http-resolver/blob/main/CONTRIBUTING.md
about: Check build, test, documentation, and review requirements before opening an issue or pull request.
27 changes: 27 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
---
name: Feature request
about: Propose a change to the resolver, its contracts, or its documentation
title: ""
labels: ""
assignees: ""
---

## Problem

<!-- What user or consumer problem would this solve? -->

## Proposed behavior

<!-- Describe the smallest useful contract. Include examples where they clarify the request. -->

## Boundaries and trade-offs

<!-- How does this fit the module boundaries, security policy, compatibility matrix, or performance goals? -->

## Alternatives considered

<!-- What other approaches did you consider, and why are they insufficient? -->

## Acceptance criteria

<!-- List observable behavior or tests that would show the proposal is complete. -->
30 changes: 30 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
## Summary

<!-- What changed, and why? Link the issue or design record when one exists. -->

## Scope and risk

<!-- Note affected modules, public contracts, compatibility, security, and performance implications. -->

## Validation

- [ ] I ran the narrowest relevant test while iterating.
- [ ] I ran the complete core suite, or explained why it was not possible.
- [ ] I ran sanitizer tests when the change affects memory, arithmetic, or concurrency.
- [ ] I recorded the exact commands and any platform limitations below.

```text
# Commands and relevant results
```

## Documentation and tests

- [ ] Tests cover the changed behavior, including a fixed regression case where appropriate.
- [ ] The owning documentation is updated, or no documentation change is needed.
- [ ] Measured I/O behavior and its baseline are updated when the change affects requests or bytes transferred.

## Review checklist

- [ ] This change preserves the core boundary and does not add format knowledge to the resolver.
- [ ] No credentials, private URLs, customer data, or generated build output are included.
- [ ] I have read the [contribution guide](../CONTRIBUTING.md) and [Code of Conduct](../CODE_OF_CONDUCT.md).
8 changes: 6 additions & 2 deletions .github/workflows/plugin-windows-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -92,8 +92,12 @@ jobs:
mkdir -p .ost-ci/bootstrap-bin
asset="ost-cli-x86_64-pc-windows-msvc.zip"
base="https://github.com/$OST_REPOSITORY/releases/download/v$OST_VERSION"
curl -fsSLo "$asset" "$base/$asset"
curl -fsSLo "$asset.sha256" "$base/$asset.sha256"
curl -fsSL --retry 5 --retry-all-errors --retry-delay 2 \
--retry-max-time 120 --connect-timeout 20 --max-time 300 \
-o "$asset" "$base/$asset"
curl -fsSL --retry 5 --retry-all-errors --retry-delay 2 \
--retry-max-time 120 --connect-timeout 20 --max-time 300 \
-o "$asset.sha256" "$base/$asset.sha256"
actual="$( (command -v sha256sum > /dev/null && sha256sum "$asset" || shasum -a 256 "$asset") | cut -d' ' -f1 )"
published="$(cut -d' ' -f1 "$asset.sha256")"
if [ "$actual" != "$published" ]; then
Expand Down
40 changes: 40 additions & 0 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Code of Conduct

## Our standard

This project is maintained for people who build, use, test, and document
software. We expect participants to:

- be respectful and assume good faith while discussing technical disagreement;
- make space for different experience levels, backgrounds, and perspectives;
- focus criticism on the work and its evidence, not on a person;
- state uncertainty clearly and change course when new evidence warrants it; and
- keep project discussions relevant, constructive, and safe to participate in.

Unacceptable behavior includes harassment, discrimination, threats, personal
attacks, sexualized attention, doxxing, deliberate disruption, and publishing
private information without permission. The same standard applies to issues,
pull requests, reviews, commits, chat, and any other forum used for this
project.

## Enforcement

Project maintainers may edit, hide, close, or remove contributions and may
temporarily or permanently restrict participation when behavior violates this
standard. Enforcement decisions will be proportionate to the behavior and
will prioritize the safety of people involved.

## Reporting

Do not report a conduct concern in a public issue. Use a private GitHub contact
channel to reach a maintainer and ask for the appropriate reporting route. If
the concern involves a security or privacy vulnerability, use the private
reporting channel in [SECURITY.md](SECURITY.md). Please include links or
context that help maintainers investigate, and avoid sharing sensitive personal
information unnecessarily.

Retaliation against someone who makes a good-faith report is not acceptable.

This code of conduct is part of the project contribution process. By
participating, you agree to follow it and to cooperate with maintainers who
apply it.
96 changes: 96 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# Contributing

Thanks for helping improve `usd-http-resolver`. Contributions should preserve
the project's central boundary: it resolves remote assets and serves bytes;
it does not learn what those bytes mean.

Before opening an issue or pull request, read the
[Code of Conduct](CODE_OF_CONDUCT.md) and check the existing documentation in
[`docs/`](docs/README.md). For architecture or policy changes, the canonical
documents in `docs/design/` and `docs/architecture/` are part of the change,
not background reading.

## Start with an issue

Use the repository's issue templates for bugs and feature proposals. A useful
bug report includes the smallest reproduction, the expected and actual result,
the platform and compiler, the CMake preset or command used, and the complete
failure output. A proposal should explain the problem, the proposed contract,
and how it fits the existing module boundaries.

Do not put credentials, private URLs, customer data, or vulnerability details
in an issue. Follow [SECURITY.md](SECURITY.md) for security reports.

## Local setup

The normal contributor path builds the core without OpenUSD:

```sh
cmake --preset core
cmake --build --preset core
ctest --preset core
```

On Windows outside a Visual Studio developer prompt, use the generator that
matches CI:

```sh
cmake --preset core-msvc
cmake --build --preset core-msvc
ctest --preset core-msvc
```

Requirements and the OpenStrata workflow are documented in
[docs/guides/BUILDING.md](docs/guides/BUILDING.md).

## Tests and evidence

Run the narrowest relevant test while iterating, then run the complete core
suite before requesting review. Changes to a backend must pass the shared
[boundary suite](docs/contributing/BOUNDARY_SUITE.md) unchanged. Changes to
HTTP behavior should also cover the hostile-server corpus; changes to cache or
I/O behavior should update the relevant baseline or measurement record.

For changes that affect concurrency, offset arithmetic, or buffer handling,
run the sanitizer lanes when the local toolchain supports them:

```sh
cmake --preset core-asan
cmake --build --preset core-asan
ctest --preset core-asan

cmake --preset core-tsan
cmake --build --preset core-tsan
ctest --preset core-tsan
```

Record the commands you ran and any platform-specific limitation in the pull
request. A passing test is evidence for the behavior it exercises; it is not a
reason to weaken a contract or silently widen scope.

## Making a change

1. Keep the change focused and preserve existing public APIs unless the issue
requires a contract change.
2. Add or update tests before treating a behavioral change as complete. Prefer
an independent oracle or fixture over duplicating the implementation in a
test.
3. Update the owning documentation when behavior, configuration, compatibility,
security policy, or measured I/O changes.
4. Do not add network access, format knowledge, or OpenUSD dependencies to the
core libraries without documenting the boundary and its consequences.
5. Keep generated workflow files consistent with their source configuration.
The core workflow is intentionally hand-authored; do not replace its
runtime-free or sanitizer lanes with a less specific check.

Pull requests should explain the motivation, the behavior changed, the tests
run, and any compatibility or performance effect. Small, reviewable commits
are helpful, but the project does not require a particular commit-message
format.

## Review and merge

Maintainers may request tests, documentation, design clarification, or a
smaller scope before merging. Review comments are part of the technical record:
resolve them explicitly, or explain why the current behavior is intentional.
CI must be green unless a maintainer has documented an exception.
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,9 @@ each release shipped is in
| What lands, in what order | [docs/roadmap/README.md](docs/roadmap/README.md) |
| How the modules are split | [docs/architecture/WORKSPACE.md](docs/architecture/WORKSPACE.md) |
| How a consumer integrates | [docs/roadmap/consumer-integration.md](docs/roadmap/consumer-integration.md) |
| How to contribute | [CONTRIBUTING.md](CONTRIBUTING.md) |
| Community expectations | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) |
| How to report a vulnerability | [SECURITY.md](SECURITY.md) |
| Everything else | [docs/README.md](docs/README.md) |

## Design commitments
Expand Down
61 changes: 61 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Security Policy

## Supported versions

Security fixes are made against the `main` branch and the latest supported
release line. Older release lines may not receive fixes; upgrade before
reporting a problem that is already fixed on `main`.

| Version | Security support |
| --- | --- |
| `main` | Supported |
| Latest release | Supported |
| Older releases | Not supported |

## Reporting a vulnerability

Please do not open a public issue, pull request, or discussion for a suspected
vulnerability. Report it privately through
[GitHub Private Vulnerability Reporting](https://github.com/animu-sphere/usd-http-resolver/security/advisories/new).
If that channel is unavailable, contact a repository maintainer privately
through GitHub and request a secure reporting route.

Reports are most useful when they include:

- the affected version, commit, component, and build configuration;
- the security impact and an assessment of exploitability;
- exact reproduction steps or a minimal proof of concept;
- the expected and observed behavior;
- relevant platform, compiler, and dependency versions; and
- whether the report is known to be exploited or publicly disclosed.

Remove credentials, access tokens, private asset URLs, customer data, and other
secrets from the report. If a proof of concept needs a private fixture, explain
the required shape instead of attaching sensitive data.

## What to expect

Maintainers will acknowledge a report when they can, reproduce and assess the
impact, and coordinate a fix or mitigation with the reporter. Do not disclose
the issue publicly until a fix or disclosure date has been agreed with the
maintainers. The project may credit reporters in a release note only with their
permission.

## Security-sensitive areas

Reports involving these areas are especially important:

- request-forgery or redirect-policy bypasses, including access to private
networks or disallowed schemes;
- credential exposure through resolved identifiers, logs, diagnostics, or
cache paths;
- unbounded allocation, response handling, retries, redirects, or decompression;
- cache identity or validator bugs that return bytes from the wrong asset
revision; and
- memory safety, data races, or incorrect bounds handling in the C++ libraries.

The project's security and network assumptions are documented in
[DESIGN_POLICY.md](docs/design/DESIGN_POLICY.md#10-security-and-trust). A
documented limitation is not automatically a vulnerability, but a report that
shows the implementation violates the stated policy should use the private
channel above.
Loading