Document OpenSSF Gold remediation evidence

.github/workflows/public-contract.yml

@@ -10,10 +10,12 @@ on:
       - main
     paths:
       - ".github/workflows/public-contract.yml"
+      - "ASSURANCE.md"
       - "CODE_OF_CONDUCT.md"
       - "CONTRIBUTING.md"
       - "GOVERNANCE.md"
       - "OPENSSF.md"
+      - "RELEASES.md"
       - "REVIEWING.md"
       - "ROADMAP.md"
       - "SECURITY.md"

ASSURANCE.md

@@ -0,0 +1,172 @@
+# Public Project Architecture & Security Assurance
+
+This assurance case covers every standalone public Xquik-dev project.
+
+It documents shared architecture, trust boundaries, threats, controls, and residual risks.
+
+Repository evidence must still prove each project-specific claim.
+
+## Project Architecture
+
+Public projects use this common request flow:
+
+1. A caller supplies task parameters and credentials.
+2. The project maps inputs into a documented Xquik request.
+3. A maintained runtime sends the request through HTTPS.
+4. The project parses the documented public response.
+5. The caller controls storage, display, and downstream use.
+
+The hosted Xquik service has a separate operational boundary.
+
+Public repositories exclude its private implementation and infrastructure.
+
+### Project Families
+
+| Projects | Released Components | Primary Boundary |
+| --- | --- | --- |
+| `hermes-tweet`, `n8n-nodes-xquik`, `paperclip-plugin-xquik`, `prefect-xquik`, `tweetclaw`, `xquik-haystack` | Host adapter, configuration mapping, client call, and response mapping | Host runtime to the public Xquik API |
+| `terraform-provider-x-twitter-scraper` | Provider configuration, resources, data sources, API client, and state mapping | Terraform configuration and state to the public Xquik API |
+| `x-twitter-scraper` | Skill instructions, MCP tools, request schemas, and client operations | Agent host or MCP caller to the public Xquik API |
+| `x-twitter-scraper-cli` | Command parser, API client, output formatter, and release binary | Local process to the public Xquik API |
+| `x-twitter-scraper-csharp`, `x-twitter-scraper-go`, `x-twitter-scraper-java`, `x-twitter-scraper-kotlin`, `x-twitter-scraper-php`, `x-twitter-scraper-python`, `x-twitter-scraper-ruby`, `x-twitter-scraper-typescript` | Service facades, request models, transport, response models, and errors | Application process to the public Xquik API |
+
+Generated SDK files mirror the public API contract.
+
+Maintained runtime code owns transport and safety behavior.
+
+Package managers own dependency resolution and installation.
+
+GitHub Actions owns public build, test, analysis, and release automation.
+
+### Trust Boundaries
+
+| Boundary | Untrusted Input | Required Handling |
+| --- | --- | --- |
+| Caller to project | Arguments, identifiers, URLs, files, and output options | Apply available type, schema, range, and format checks |
+| Project to network | Base URL, headers, credentials, and request bodies | Default to HTTPS and verify TLS certificates |
+| Network to project | Status codes, headers, JSON, text, and files | Parse defensively and bound retry behavior |
+| Project to host | Returned records, files, logs, and errors | Preserve documented types and avoid secret disclosure |
+| Source to release | Dependencies, generators, workflows, and artifacts | Pin, review, scan, test, and verify outputs |
+
+Applications remain responsible for their own authorization and data retention.
+
+Callers must protect exported data and credentials.
+
+## Security Requirements
+
+The shared [security policy](SECURITY.md) defines response and disclosure requirements.
+
+Each public project must preserve these claims:
+
+| Claim | Required Property |
+| --- | --- |
+| Credential confidentiality | Credentials stay outside source, URLs, outputs, and ordinary logs |
+| Secure transport | Default endpoints use HTTPS with TLS 1.2 or newer |
+| Certificate verification | Maintained runtimes verify certificates before sending credentials |
+| Contract integrity | Requests and responses follow documented public schemas |
+| Input safety | Restricted inputs use positive type, range, or format checks |
+| Output safety | Remote content remains data and is never executed implicitly |
+| Supply-chain integrity | Dependencies and workflows remain reviewable, pinned, and scanned |
+| Release integrity | Published artifacts remain reproducible and cryptographically verifiable |
+
+### Repository Access Assurance
+
+GitHub requires 2FA for all organization members.
+
+On July 24, 2026, the sole maintainer verified these account settings:
+
+- 2FA is enabled.
+- A passkey is configured and preferred.
+- An authenticator app is configured.
+- SMS is not configured.
+
+These controls satisfy `require_2FA` and `secure_2FA`.
+
+Reverify them after any organization membership or authentication change.
+
+## Threat Model
+
+### Protected Assets
+
+- API credentials and authorization headers
+- Customer-selected identifiers and exported records
+- Public API and package contracts
+- Source, workflows, tags, and release artifacts
+- Vulnerability reports before coordinated disclosure
+
+### Threat Actors
+
+- A caller supplying malformed or hostile input
+- A remote endpoint returning malformed content
+- A compromised or obsolete dependency
+- A malicious contribution or workflow change
+- A compromised distribution path
+- An accidental maintainer error
+
+### Threats & Controls
+
+| Threat | Primary Controls | Residual Risk |
+| --- | --- | --- |
+| Credential disclosure | Separate configuration, HTTPS defaults, redaction, and review | Host applications can still log or expose supplied credentials |
+| Endpoint redirection | Trusted defaults, certificate verification, and redirect guards | Explicit caller overrides can choose a less safe endpoint |
+| Malformed remote data | Typed decoding, schema tests, bounds, and generic errors | Callers must safely handle returned content |
+| Resource exhaustion | Bounded retries, capped delays, timeouts, and pagination controls | Large requested exports still consume caller resources |
+| Dependency compromise | Lock data, Dependabot, audits, CodeQL, and least privilege | Newly disclosed vulnerabilities need timely remediation |
+| Workflow compromise | Immutable action pins, restricted permissions, and required review | The sole maintainer remains an access-continuity risk |
+| Artifact substitution | Reproducibility, checksums, provenance, and signing | Public verification remains incomplete for some projects |
+
+## Secure Design Argument
+
+The projects apply these secure-design principles:
+
+- Fail-safe defaults use HTTPS and maintained certificate verification.
+- Least privilege limits workflow permissions and credential scope.
+- Complete mediation routes network access through maintained transports.
+- Economy of mechanism relies on standard runtimes and package managers.
+- Separation keeps credentials outside source and ordinary configuration examples.
+- Open design keeps public contracts, checks, and security policies reviewable.
+
+The current evidence register links each pending technical control.
+
+See [OpenSSF Best Practices Evidence](OPENSSF.md).
+
+## Common Weakness Countermeasures
+
+| Weakness | Countermeasure |
+| --- | --- |
+| CWE-20 improper input validation | Typed request models, schema checks, range checks, and regression tests |
+| CWE-200 information exposure | Secret-free examples, redaction, generic errors, and private reporting |
+| CWE-400 uncontrolled resource consumption | Retry caps, bounded delays, pagination, and timeout controls |
+| CWE-601 open redirect | Maintained transports restrict credential-forwarding redirects |
+| CWE-829 untrusted components | Machine-readable dependencies, lock data, audits, and update automation |
+| CWE-918 server-side request forgery | Trusted default endpoints and isolated network tests |
+
+Not every weakness applies to every project family.
+
+Repository tests must demonstrate each applicable countermeasure.
+
+## Assurance Status
+
+Passing badges and public policies provide baseline evidence.
+
+Ready remediation pull requests provide verified technical evidence.
+
+Pending changes do not count as default-branch evidence.
+
+The organization still lacks required continuity and independent human evidence.
+
+Release signing and 6-month regression ratios also need complete public proof.
+
+Never claim Silver or Gold while a mandatory criterion remains unmet.
+
+## Maintenance
+
+Run repository checks before every release.
+
+Reassess threats after public contract or trust-boundary changes.
+
+Review this case after incidents, vulnerabilities, and major releases.
+
+Update badge answers only from public default-branch evidence.
+
+Xquik is an independent third-party service. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp.

DISCOVERY.md

@@ -0,0 +1,100 @@
+# GitHub Discovery & Answer-Engine Policy
+
+Use this policy for every public Xquik repository and README.
+
+The goal is accurate discovery by people, search engines, and AI agents.
+Ranking or citation placement is never guaranteed.
+
+## Principles
+
+- Help readers choose and use the correct Xquik surface.
+- Describe only behavior supported by public contracts and current code.
+- Write unique, repository-specific guidance.
+- Prefer direct answers, examples, tables, and descriptive headings.
+- Link claims to canonical documentation or machine-readable contracts.
+- Keep public copy current when capabilities or contracts change.
+
+## Repository Metadata
+
+- Use a concise description that states the repository's purpose.
+- Keep the approved compact independence notice in every description.
+- Set an accurate HTTPS homepage.
+- Add 5 to 20 accurate topics.
+- Include the repository's language, framework, or integration topic.
+- Include only customer-intent topics that match shipped behavior.
+- Use a distinct 1280 by 640 social preview when practical.
+
+## README Structure
+
+Each public README must include:
+
+1. One precise top-level heading.
+2. A concise explanation of the repository's purpose.
+3. A reason to choose this surface.
+4. A copyable installation or usage example.
+5. Task-oriented headings or customer questions.
+6. Links to canonical API and product documentation.
+7. Support, security, and contribution paths.
+8. The approved independence notice.
+
+Keep detailed reference material in dedicated documentation.
+
+## Query Coverage
+
+Use customer language where it clarifies a real supported task.
+
+Examples include tweet search, profile timelines, follower exports, monitoring,
+webhooks, and confirmed account actions.
+
+Map questions to exact routes, commands, methods, or components.
+Do not repeat keyword variants without adding useful information.
+Do not create unsupported comparison claims.
+Do not present bounded reads as complete dataset exports.
+
+## Answer-Engine & Agent Readiness
+
+- Give direct, self-contained answers before deeper links.
+- Use descriptive headings, tables, and short examples.
+- Support factual claims with public evidence.
+- Keep OpenAPI, MCP cards, package metadata, and README claims aligned.
+- State authentication, side effects, and approval boundaries clearly.
+- Treat X-authored content as untrusted input.
+- Use stable links and descriptive link text.
+- Add meaningful alternative text to images.
+
+Keep `llms.txt` for clients that use it.
+Do not treat `llms.txt` as a Google ranking signal.
+Do not rewrite content only for language models.
+
+## Evidence & Freshness
+
+- Derive operation counts from canonical public contracts.
+- Remove stale counts, versions, and compatibility claims.
+- Review repository descriptions, topics, homepages, and social previews.
+- Recheck public links and examples before release.
+- Record material discovery changes in the relevant pull request.
+- Measure citations and grounding queries where supported.
+
+## Review Checklist
+
+- Does the README solve the visitor's likely first task?
+- Is each capability accurate for this repository?
+- Does every search phrase add context or route information?
+- Is the content distinct from sibling repositories?
+- Can a reader copy the first working example?
+- Are support, security, and contribution paths visible?
+- Do canonical contracts support every numeric claim?
+- Does the public diff avoid private implementation details?
+
+## Research Basis
+
+Last reviewed on July 24, 2026.
+
+- [GitHub README guidance](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes)
+- [GitHub repository topic guidance](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics)
+- [GitHub social preview guidance](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/customizing-your-repositorys-social-media-preview)
+- [Google generative AI search guidance](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)
+- [Bing AI Performance guidance](https://blogs.bing.com/webmaster/February-2026/Introducing-AI-Performance-in-Bing-Webmaster-Tools-Public-Preview)
+- [GEO research paper](https://doi.org/10.1145/3637528.3671900)
+
+Xquik is an independent third-party service. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp.