cpac-trust-db Documentation

Community-maintained trust data for CPAC.

The Cinder Project — “Burn the Blind Spots”

---

What is cpac-trust-db?

cpac-trust-db is the trust data backend for CPAC. It stores:

1. PKGBUILD snapshots — anonymized, crowdsourced snapshots submitted by CPAC clients, used to detect divergence from known-good package states
2. Advisories — maintainer-curated records of known malicious, compromised, or suspicious packages (e.g. Atomic Arch-style hijacks)
3. Advisory history — append-only version history of advisory changes (never overwritten)
4. AI analysis cache — on-demand AI analysis results cached for 3 hours

---

Key Features

• Advisory lifecycle — versioned advisories with append-only history
• Reputation system — strike tracking, trust tiers (Trusted/Standard/Probation/Suspended)
• Weekly email reports — staggered by account creation date
• Admin panel — account management, advisory review, volunteer stats
• AUR proxy — CORS fix for browser-based PKGBUILD comparison
• Suspicious pattern detection — 15+ patterns including npm/bun pipe-to-shell

---

Documentation

• Architecture — System design and tech stack
• API Endpoints — REST API reference
• Staleness Check — How CPAC detects stale data
• Local Cache — Local storage structure
• Advisories — Advisory data format and trust impact
• Snapshots — Snapshot data format and submission pipeline
• GitHub Actions — Sync pipeline (TOML → Supabase)
• Auth Model — Authentication and authorization
• Governance — Who can submit what
• Roadmap — Planned features
• Related Projects — Ecosystem overview

---

Part of The Cinder Project — github.com/SabeeirSharrma/cpac-trust-db

Architecture

Overview

CPAC client
       ↓
  api.thecinderproject.qd.je/cpac-trust-db/api/*
  Cloudflare Worker (URL proxy, rate limiting, CORS)
       ↓
  Supabase (Postgres)
  qzhhsyucnlswmsvpssdh.supabase.co
       ↓
  CPAC client reads → local cache at ~/.cpac/trust-db/
       ↑
  GitHub Actions (runs nightly)
  Reads from Supabase → commits updated TOML to repo

Why This Stack

• Cloudflare Worker — proxies api.thecinderproject.qd.je to Supabase. Provides a stable API URL independent of the backend, handles CORS, and can add rate limiting or request logging later.
• Supabase (Postgres) — stable, mature, generous free tier, auto-generated REST API, row-level security handles public read / authenticated write cleanly.
• GitHub — source of truth, fully auditable, human-readable TOML diffs on every advisory or snapshot change. GitHub Actions reads aggregated data from Supabase and commits updated TOML files on a schedule (nightly). One single commit per run, no overlap possible.

Data Flow

1. Snapshots — CPAC clients POST to api.thecinderproject.qd.je/cpac-trust-db/api/snapshots → Worker proxies to Supabase
2. Advisories — Core team merges TOML to main → GitHub Actions upserts to Supabase
3. Sync — GitHub Actions runs nightly → reads from Supabase → commits TOML to repo
4. Queries — CPAC client hits Worker API → Worker proxies to Supabase → CPAC caches locally

Direct Supabase (Fallback)

If the proxy is unavailable, CPAC clients can fall back to direct Supabase access at https://qzhhsyucnlswmsvpssdh.supabase.co. The anon key is embedded in the client, which is safe because row-level security policies enforce public reads and rate-limited writes only.

---

Part of The Cinder Project

API Endpoints

All endpoints are served through a Cloudflare Worker proxy at:

https://api.thecinderproject.qd.je/cpac-trust-db/api

The worker proxies requests to Supabase at https://qzhhsyucnlswmsvpssdh.supabase.co/rest/v1/*.

All reads are public. Writes require an anonymous client token (rate limiting only, not authentication).

---

Meta

GET /cpac-trust-db/api/meta
→ [{
    version: "abc123",          # hash of current DB state
    updated_at: "2026-06-26T12:00:00Z",
    advisory_count: 12,
    snapshot_package_count: 847,
    schema_version: 1
  }]

Used by CPAC clients to check if their local cache is stale without downloading full data. This is the only request made on every cpac install.

---

Advisories

GET /cpac-trust-db/api/advisories
→ [ ...all advisories... ]

GET /cpac-trust-db/api/advisories?package=eq.<package-name>
→ advisory object or empty array

---

Snapshots

GET /cpac-trust-db/api/snapshots?package=eq.<package-name>
→ [ ...snapshot entries for a package... ]

GET /cpac-trust-db/api/snapshots?package=eq.<package-name>&version=eq.<version>
→ snapshot entries for a specific version

---

Submissions (Authenticated)

POST /cpac-trust-db/api/snapshots
Authorization: Bearer <anon-key>
X-Client-Token: <anonymous-token>
Content-Type: application/json

→ Submit a PKGBUILD hash or full sanitized PKGBUILD

Tokens are issued per CPAC installation on first run (anonymous, non-identifying). Used for rate limiting and abuse prevention only — not for identifying users. See Auth Model for token issuance details.

---

Part of The Cinder Project

Staleness Check System

CPAC never blindly re-downloads the full database. Instead it uses a lightweight two-step check.

---

Step 1 — Meta Check

When: Every cpac install, cpac trust, cpac audit

GET /api/meta
  → { version: "abc123" }
          ↓
Compare against local ~/.cpac/trust-db/meta.toml
  → version matches?  Use local cache. Done. (one cheap HTTP request)
  → version differs?  Queue a delta sync for next cpac update.
  → no local cache?   Fetch full DB immediately.

---

Step 2 — Delta Sync

When: cpac update, or when meta check detects a change

GET /api/delta?since=<last_sync_timestamp>
  → only changed advisories and snapshots since last sync
          ↓
Merge into local cache
          ↓
Update local meta.toml with new version hash + timestamp

---

Summary

Command	Network Request	Behavior
cpac install	GET /api/meta	One cheap request, uses local cache
cpac update	GET /api/delta	Full delta sync if version changed
Offline	None	Uses local cache, warns user

---

Part of The Cinder Project

Local Cache

Storage Location

~/.cpac/trust-db/
  meta.toml           # version hash, last sync timestamp, schema version
  advisories.db       # compiled advisory index (fast lookup by package name)
  snapshots.db        # compiled snapshot index (fast lookup by package + version)

How It Works

The raw TOML from the GitHub repo is compiled into a local binary format on sync, so runtime queries are fast and don’t require network access.

Offline Behavior

If the local cache is stale and the network is unavailable, CPAC warns the user but continues using the local copy — never blocks on network.

---

Part of The Cinder Project

Advisories

Maintained directly by The Cinder Project core team. Stored as TOML in the GitHub repo, synced to Supabase via GitHub Actions on merge.

Format

[advisory]
package = "malicious-pkg"
severity = "critical"          # critical | high | medium | low
status = "confirmed"           # confirmed | suspected | resolved
reported = "2026-06-14"
updated = "2026-06-14"
reported_by = "The Cinder Project"
cve = ""                       # if applicable

[details]
summary = "PKGBUILD modified to execute remote script post-install"
description = """
On 2026-06-14, maintainer transferred ownership and introduced a
curl | bash call targeting an external IP.
"""
affected_versions = ["1.2.3-1", "1.2.4-1"]
safe_versions = []

[references]
urls = ["https://thecinderproject.qd.je/advisories/malicious-pkg-2026-06-14"]

Submission

Community members report via GitHub issue or Discord. Core team reviews evidence and publishes. No automated advisory submissions.

Trust Score Impact

The severity and status fields in the TOML advisory are evaluated independently. Severity applies a base penalty; status applies an additional adjustment on top. For example, severity = "critical" with status = "suspected" applies the critical penalty (-30) plus the suspected adjustment (-15) for a combined -45.

Severity	Trust Penalty	Recommendation Floor
Critical	-30	DANGER
High	-20	WARNING
Medium	-10	CAUTION
Low	-5	No floor change

Status	Additional Adjustment
Confirmed	0 (no change to severity penalty)
Suspected	-15
Resolved	Reverts severity penalty to 0

---

Part of The Cinder Project

PKGBUILD Snapshots

Submitted anonymously by CPAC clients that opted into crowdsourced sharing. Two formats depending on user consent level.

Hash Submissions (consent: hash)

[[entry]]
version = "152.0.1-1"
sha256 = "abc123..."
submitted_count = 847
first_seen = "2026-05-01"
last_seen = "2026-06-20"

[[entry]]
version = "152.0.1-1"
sha256 = "def456..."           # minority hash — potential divergence
submitted_count = 2
first_seen = "2026-06-14"
last_seen = "2026-06-14"

Full PKGBUILD Submissions (consent: full)

Stored as sanitized PKGBUILD text. Pass 1 structural redaction (local paths, hostname, local IPs, non-public emails) runs locally before submission. See CPAC_SPEC.md for the full sanitization pipeline.

Submission Pipeline

cpac install some-aur-package
        ↓
Fetch PKGBUILD locally
        ↓
Pass 1 sanitization (strip paths/hostname/IPs/emails)
        ↓
Pass 2 anomaly detection (flag suspicious patterns → trust signals, shown to user)
        ↓
consent=hash → compute SHA-256, queue locally
consent=full → queue sanitized PKGBUILD locally
        ↓
cpac update → batch POST to /api/submit/snapshot
        ↓
GitHub Actions aggregates into TOML → commits to repo → syncs to Supabase

Submissions are queued locally and sent in batch on cpac update — never sent mid-install, never blocking the install flow.

Trust Score Impact

• Hash matches majority consensus → positive trust signal
• Hash matches small minority or no known submissions → warning signal

---

Part of The Cinder Project

GitHub Actions Pipeline

Trigger

Push to main (advisory added or snapshot aggregated).

Pipeline Steps

Trigger: push to main (advisory added or snapshot aggregated)
        ↓
Action 1: Validate TOML schema
        ↓
Action 2: Compile TOML → Supabase (upsert changed records)
        ↓
Action 3: Update meta/db.toml with new version hash + timestamp
        ↓
Action 4: Cut a new GitHub release with changelog (advisories only)

Note: meta/db.toml is the repo-side state file updated by this pipeline. Do not confuse it with ~/.cpac/trust-db/meta.toml (the local cache, documented in Local Cache) or the /api/meta endpoint (documented in API Endpoints).

What It Does

1. Validates TOML files against the schema
2. Upserts changed records into Supabase
3. Updates meta/db.toml with new version hash and timestamp
4. Releases changelog for advisory changes (not snapshots)

---

Part of The Cinder Project

Auth Model

Public API

Operation	Auth Required
Read advisories	None — fully public
Read snapshots	None — fully public
GET /api/meta	None — fully public
POST /api/snapshots	Bearer token (per-install, anonymous)
Write advisories (direct)	Maintainer only (Supabase RLS)

Panel Auth

The maintainer and volunteer panels use Supabase Auth (email/password).

Panel	Access	Auth Method
/panel/login	Anyone with credentials	Supabase Auth
/panel/volunteer	Volunteers only	Supabase Auth + role check
/panel/maintainer	Maintainers only	Supabase Auth + role check

No Public Signups

Accounts are created manually by administrators. To request access, open a ticket on Discord. Credentials are shared via DM.

Roles

Role	Capabilities	Rate Limit
maintainer	Publish advisories, review/approve/reject submissions, manage panels	Unlimited
volunteer	Submit advisories for review, use comparer tool	5 submissions/day

RLS Policies

• Profiles: users read their own; maintainers read all
• Pending advisories: volunteers read/insert their own; maintainers read/update all
• Advisories: public read; maintainer write via approve_advisory() function

Anonymous Tokens

Anonymous tokens are issued on first CPAC run. They are used for rate limiting and abuse prevention only — not linked to any user identity.

---

Part of The Cinder Project

Governance

Submission Policy

Data Type	Who Can Submit	Review Required
Advisories (published)	Maintainers only	N/A — maintainer publishes directly
Advisories (proposed)	Approved volunteers	Yes — maintainer approval required
Snapshots (hash)	Automated CPAC clients	No — aggregated automatically
Snapshots (full)	Automated CPAC clients	No — aggregated automatically

Roles

Maintainers

• Can publish advisories directly to the database
• Review and approve/reject volunteer-submitted advisories
• Manage volunteer accounts
• Full access to the maintainer panel

Volunteers

• Submit advisories for review via the volunteer panel
• Rate-limited to 5 submissions per day
• Submissions go to a pending queue for maintainer approval
• Cannot publish directly — all advisories require review

Advisory Workflow

Volunteer runs comparer → flags package
        ↓
Fills advisory form → submits
        ↓
Goes to pending queue (rate-limited: 5/day)
        ↓
Maintainer reviews → approves or rejects
        ↓
Approved → published to advisories table (goes live immediately)
Rejected → volunteer notified with reviewer notes

Access Requests

Access to the volunteer/maintainer panels is granted via Discord ticket. No public signups. Contact the project maintainer to request access.

Reporting

Community members can report potential advisories via:

• GitHub issues
• Discord server

Core team reviews evidence and publishes the advisory if confirmed.

---

Part of The Cinder Project

Roadmap

• Supabase schema setup (advisories + snapshots tables)
• GitHub Actions sync pipeline (TOML → Supabase)
• /api/meta endpoint
• /api/advisories + /api/snapshots endpoints
• /api/delta endpoint
• CPAC integration — meta check on install, delta sync on update
• Submission pipeline — anonymous tokens, batch POST on update
• First advisory entries (Atomic Arch affected packages)
• Public advisory index on website

---

Part of The Cinder Project

Related Projects

Project	Role
cpac	Consumes trust-db; submits snapshots on cpac update
website	Public advisory index at thecinderproject.qd.je/advisories

---

Part of The Cinder Project