discovery-media-player

All eight workflows declare permissions: at the top level, so no job ever runs on an unspecified default. release.yml starts from permissions: {} — no scope at all — and grants each job only what it needs: the build job contents: read, the publish job adding id-token: write for OIDC and nothing more. ci.yml is contents: read throughout and scorecard.yml is read-all. A job needing a write scope names it at job level rather than inheriting one.

Each release carries a unique identifier: package.json declares it, npm publishes under that exact version and refuses to republish it, git carries a matching vX.Y.Z tag, and a running instance reports the same string through GET /api/doc?contract=1 so an operator can tell what is serving. The current release is v0.1.128. A release preflight guard refuses a tag whose version does not match what the repository declares, and another refuses a tag pointing at a commit that does not belong to main.

Every release ships notes covering functional and security-relevant changes. CHANGELOG.md carries a dated section per version in Keep a Changelog form — including, by name and date, the findings of the three external assessments of August 2026 and the version that fixed each — and the same content is published as the GitHub Release for that tag. tools/changelog.mjs fails CI when the version being released has no matching section, so a release cannot ship without a log.

npm is the dependency manager, driven exclusively through npm ci; no workflow runs npm install. package-lock.json is committed and carries a Subresource-Integrity hash for every package in the transitive graph, so CI installs the graph the lockfile describes rather than whatever the registry served that morning. Build inputs outside npm are pinned by digest rather than tag — container base images by sha256, GitHub Actions by 40-character commit SHA — each enforced by a CI guard that refuses a floating reference. The policy is written down in docs/DEPENDENCIES.md.

Released assets are signed at build time. The npm package is published with npm publish --provenance under OIDC trusted publishing, producing a Sigstore-signed SLSA provenance attestation that names the tarball's cryptographic digest and binds it to the workflow, repository and commit that built it; a consumer verifies it with npm audit signatures. The container image is built with provenance: mode=max and an SBOM, and pushed to GHCR with build attestations under id-token: write. No long-lived signing credential exists to hold or to leak — the signature is obtained from the platform's identity at the moment of publication.

docs/DEPENDENCIES.md describes selection, acquisition and tracking. Selection: the bar a new dependency must clear, and why it is high for a component that runs beside an operator's commercial documents — the runtime tree is one package, pdfjs-dist, pinned exactly because it is the rendering engine and its upgrade is a decision rather than a bump. Acquisition: npm ci only, against a committed lockfile with integrity hashes, with digest pinning for images and commit-SHA pinning for actions. Tracking: the Dependabot policy — monthly, tooling grouped, an action's major arriving alone so it cannot hide in a batch — including the two upgrades deliberately held back, the reason for each, and why majors are not frozen elsewhere.

CONTRIBUTING.md opens with the build: npm install, npm test, npm run lint, npm run typecheck, npm run build. It states the only prerequisite — Node 22 or later — and adds that there is nothing else to install, because the tests spin the player up in-process against a temporary folder and run offline. The browser bench and its single extra requirement are documented beside it: a Chrome already present on the machine, driven by playwright-core with no browser download, and PLAYER_E2E_CHROME to point at it if it lives somewhere unusual. README.md gives the same path for a fresh clone.

MAINTAINERS.md lists the project members and, in a dedicated table, exactly which sensitive resources each holds: repository admin, merge rights on main, GitHub Actions configuration, npm publishing, the GHCR image, and the security mailbox. There is currently one maintainer and no other account holds write access to the repository, which the file states explicitly rather than leaving to be inferred. It also records that no release credential is stored anywhere — publication authenticates through OIDC at the moment it runs, so there is no secret to hold, rotate, or lose.

MAINTAINERS.md describes the roles and what each answers for. The maintainer: review and merge, what the host contract may promise and when it may break, cutting releases and being answerable for what a published version contains, and triaging vulnerability reports within the timeline SECURITY.md commits to. Contributors: no invitation to wait for, the CLA that a workflow checks on every pull request, and the project's rule on tests. Operators: no access here, but asked to report a boundary the documentation did not predict. A Bus factor section states plainly what one maintainer costs and what it does not.

CONTRIBUTING.md states the requirements for an acceptable contribution. The project's one rule is that a behaviour worth keeping is worth a test that fails without it, and the requirement extends to the test's name: it must say which failure it prevents, not that it tests the happy path, and one that does not will be asked about in review. The same document covers what review looks for, how generated files are handled, commit and branch conventions, the language rule and the CLA; AGENTS.md records which conventions a CI guard enforces and which only review catches.

Every code contributor asserts their legal right to contribute through the CLA in CLA.md, and the assertion is enforced rather than assumed: .github/workflows/cla.yml checks it on every pull request, posts and updates a comment when a signature is missing, and records signatures on a dedicated branch. An unsigned pull request does not merge, and because branch protection makes pull requests the only route into main, no contribution reaches released code without the assertion having been made and recorded. The OSPS recommendation for this control names a CLA as satisfying it.

main is protected and its status checks must pass before a pull request can merge. The required set covers lint, typecheck and the full 1515-test suite on Node 22 and 24, CodeQL, and the repository's own guards: every GitHub Action pinned to a commit SHA, the version comment beside each SHA telling the truth, container base images pinned to a digest, the committed browser bundles still matching their TypeScript sources, the published tarball shipping compiled JavaScript rather than raw TypeScript, and no plaintext credential in any tracked file. Direct pushes, which would bypass all of it, are refused.

ci.yml runs on every pull request and every push to main, executing the full vitest suite — 1515 tests across 144 files — on Node 22 and 24, alongside lint and typecheck. Three further benches run in the same workflow rather than on a schedule: a browser bench driving a real Chromium including an axe-core accessibility pass, a bench against a real PostgREST and Postgres instead of a stub, and a cost bench that asserts on the number of database round trips per gesture, so a performance regression fails the build instead of surfacing on an invoice.

docs/ARCHITECTURE.md includes an Actors and actions section: a table of every actor — link recipient, internal reader, presenter, live attendee, host application, operator, maintainer — giving the actions each may perform and, in the column that matters most, where the decision is actually made. A second table covers the three non-human systems the design turns on: the file source and the SSRF guard that confines it to allow-listed origins, the database reached only from the server with no anonymous read policy on any table, and the host route behind PLAYER_HOST_FETCH_SECRET. The rest of the document explains the seam that makes those the only decision points.

docs/API.md is the English reference for what a host can call and what it must implement. docs/HOST-CONTRACT.md is the binding version of the same surface, carrying a dated journal of every boundary change, and it ships inside the published package — resolvable by a consumer as discovery-media-player/contrat. TypeScript declarations in types/ describe the interface to a compiler, and src/bridge.ts is the MIT-licensed postMessage contract a host application imports to talk to the player. A CI guard compares the declared public surface against what the package actually exports, so the documentation cannot drift from the code.

SECURITY.md is the assessment. It names the file proxy as the highest-value target in the codebase, precisely because it takes a URL from a caller and fetches it server-side, and enumerates the outcomes treated as vulnerabilities: reaching a file outside an allow-listed storage origin, reading a document without the right link through slug guessing or a revoked link that still opens, taking a live presentation without its control token, escalating across the host boundary or leaking PLAYER_HOST_FETCH_SECRET into a URL or a log, and XSS against a nonce-based CSP. It also states what is out of scope and why. Three external assessments were carried out in August 2026 and are published unedited in docs/, with a follow-up ledger recording what was fixed, what was decided against, and the reason.

SECURITY.md publishes the coordinated disclosure policy with explicit timeframes: acknowledgement within 72 hours, an assessment within 7 days, then a disclosure date agreed with the reporter, and credit in the changelog unless the reporter would rather not be named. It states which versions are supported, what is and is not treated as a vulnerability, and the design notes a tester needs before starting. .github/ISSUE_TEMPLATE/config.yml links the policy from the issue chooser, so a reporter meets it before opening a public issue.

Private reporting is the required channel rather than an option, and there are two: GitHub private vulnerability reporting and security@3d-discovery.fr. SECURITY.md directs reporters to them instead of opening an issue, and the issue-template configuration puts the private form first, with the reason written: instances of this player serve commercial documents, and a public report would expose every operator before a fix exists. https://github.com/Juli1artha/discovery-media-player/blob/main/SECURITY.md

Discovered issues are published in a predictable public channel. CHANGELOG.md carries a dated section per version naming security-relevant fixes and the version carrying each, so a consumer can tell from a version number whether they are affected and what to upgrade to; the same content is published as the GitHub Release for that tag. The findings of the three external assessments of August 2026 are published in full in docs/, kept in the state they were received because an assessment rewritten afterwards is no longer a trace, alongside a ledger of what was fixed and what was deliberately not. SECURITY.md commits to crediting reporters there. No CVE has been assigned to date; that changelog section is where one would appear.