@reinconsole/graph 0.1.1 → 0.3.0-rc.1

package/README.md

@@ -2,7 +2,7 @@
 
 Phase 3 of **[Rein](https://github.com/bugiiiii11/rein)** — the reputation graph. Guard receipts say what agents tried to spend; gate receipts say what vendors actually earned. The graph listens to both, scores every vendor and payer it has evidence on, and feeds the scores back into enforcement on both sides of the wire.
 
-> **Status: v0.1 — early open-source infrastructure, live on testnet.** APIs may change before 1.0. See the live scoreboard: [Rein console](https://app.reinconsole.com).
+> **Status: v0.2 — early open-source infrastructure, live on testnet.** APIs may change before 1.0. See the live scoreboard: [Rein console](https://app.reinconsole.com).
 
 ## Install
 
@@ -31,7 +31,7 @@ createGate({ screen: { check: payerCheck(graph, { denyBelow: 40 }) }, /* ... */
 - **Unknown is not bad.** The evaluator never fires `vendorReputationLt` without data, `syncVendors` withholds scores under the confidence floor, and `payerCheck` passes wallets it knows nothing about. A newcomer is served; a *confidently* bad actor is refused.
 - **No-fault refusals carry no evidence.** Rate limits, velocity caps, and rails outages at one vendor's gate never bleed into a payer's global score.
 - **One identity, one history.** `graph.link(canonical, alias)` merges subjects across id spaces — an agent's engine ULID, its paying wallets, its on-chain [ERC-8004](https://www.npmjs.com/package/@reinconsole/erc8004) identity — so evidence follows the party, not the key. Key rotation never splits a score.
-- **Run it as a service.** `buildGraphServer()` — remote producers `POST /v1/events`, anyone reads `GET /v1/scores/:kind/:subject` and gets the score *and* the evidence behind it. The durable variant (evidence survives restarts) lives in the [monorepo](https://github.com/bugiiiii11/rein) (`@reinconsole/store`).
+- **Run it as a service.** `buildGraphServer()` — remote producers `POST /v1/events`, anyone reads `GET /v1/scores/:kind/:subject` and gets the score *and* the evidence behind it. Pass `{ auth }` (an `ApiKeyAuth` from `@reinconsole/core/auth`, or set `REIN_GRAPH_API_KEY`) and the write routes demand a key holding the `report` scope while reads stay open; without one the server binds loopback and refuses a public bind. The durable variant (evidence survives restarts) lives in the [monorepo](https://github.com/bugiiiii11/rein) (`@reinconsole/store`).
 
 Scoring weights are deliberately transparent v0.1 heuristics (`DEFAULT_WEIGHTS`, overridable) — scores are pure functions of the evidence ledger, so the model can evolve without migrations.
 

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ReputationSubject, ReputationComponents, ReinEvent, ReputationScore, Receipt } from '@reinconsole/core';
 import { FastifyInstance } from 'fastify';
+import { ApiKeyAuth } from '@reinconsole/core/auth';
 
 /** A value that may be produced synchronously or awaited (durable writes). */
 type MaybePromise<T> = T | Promise<T>;
@@ -186,8 +187,21 @@ declare function reliabilityComponent(ev: SubjectEvidence): number;
  * Confidence is first-class (see core ReputationScore): a thin or brand-new
  * history yields LOW confidence rather than a misleading score, so consumers
  * (engine sync, gate screening) can refuse to act on it. Depth of evidence
- * saturates around 10 observations; age discounts same-day evidence to 40%
- * and stops mattering after a week.
+ * saturates around 10 observations; age stops mattering after a week.
+ *
+ * The 0.1 age floor is load-bearing for fairness. Both consumers act at a 0.3
+ * confidence floor (`syncVendors`, `payerCheck`), so capping a day-0 subject at
+ * 0.1 makes first-day enforcement impossible BY CONSTRUCTION rather than by
+ * arithmetic luck. It used to be 0.4, which left day-0 subjects enforceable
+ * after only 14 observations — `depth` saturates so fast that a busy vendor
+ * cleared that in seconds, and the console's own vendor sat at 0.30136 against
+ * the 0.3 floor, i.e. inside the newcomer grace period by 0.0014. Enforcement
+ * now needs roughly 1.6 days (high volume) to 2.3 days (moderate) of history:
+ * a grace period measured in time, which is what "newcomer" means.
+ *
+ * Note the constant only ever applies to subjects younger than a week — past
+ * 7 days `min(1, d/7)` saturates and age is 1.0 under any floor — so lowering
+ * it leaves every mature score bit-for-bit unchanged.
  */
 declare function confidence(ev: SubjectEvidence, nowMs: number): number;
 /** Blend all five components into the headline 0–100 score. */
@@ -364,11 +378,50 @@ interface PayerCheckOptions {
  */
 declare function payerCheck(graph: ReputationGraph, options?: PayerCheckOptions): (payer: string) => string | undefined;
 
+interface GraphServerOptions {
+    /**
+     * API-key authentication for the WRITE routes. Omit for embedded use (the
+     * console world holds the graph object directly) or for a loopback-only
+     * process; pass an {@link ApiKeyAuth} and every write demands a `report`
+     * scope while reads stay open.
+     */
+    auth?: ApiKeyAuth;
+}
 /**
  * Build the graph HTTP API. Remote producers POST their events here; anyone
  * can read scores with the evidence behind them. Pass a graph for tests, or
  * let it create a fresh in-memory one.
+ *
+ * READS ARE OPEN BY DESIGN and that is the whole point of a reputation graph:
+ * a score nobody can read governs nothing. WRITES are the asymmetry — an event
+ * posted here becomes evidence about a subject that did not post it — so when
+ * `auth` is supplied they require the `report` scope. Without `auth` the server
+ * is exactly as open as it always was, which is why the bins that expose it
+ * refuse a public bind unless a key exists or the operator says otherwise.
  */
-declare function buildGraphServer(graph?: ReputationGraph): FastifyInstance;
+declare function buildGraphServer(graph?: ReputationGraph, options?: GraphServerOptions): FastifyInstance;
+/**
+ * Build the graph's auth layer from the environment, or explain why there is
+ * none. `REIN_GRAPH_API_KEY` seeds one or more comma-separated secrets.
+ *
+ * They are seeded with `report` and nothing else: the graph has no key-issuing
+ * routes to bootstrap (unlike the engine, which seeds `admin` so `/v1/keys` is
+ * reachable), so an `admin` secret here would grant authority no route needs.
+ */
+declare function graphAuthFromEnv(env: NodeJS.ProcessEnv): Promise<ApiKeyAuth | undefined>;
+/**
+ * Where a graph process binds, given whether auth exists.
+ *
+ * Until D1(a) the graph had no key to trade, so the only trade available was a
+ * statement: `REIN_GRAPH_PUBLIC=1`. Now that writes can demand a `report` key,
+ * the rule matches the engine's — a key buys a public bind, and asking for one
+ * without a key is a startup ERROR rather than a warning. `REIN_GRAPH_PUBLIC=1`
+ * survives as the deliberate override for an open graph, because a read-only
+ * showcase is a real deployment and reads were never the exposure.
+ */
+declare function resolveGraphHost(env: NodeJS.ProcessEnv, hasAuth?: boolean): {
+    host: string;
+    warning?: string;
+};
 
-export { type CounterpartyLine, DEFAULT_CORRELATION_LIMIT, DEFAULT_WEIGHTS, type EventSource, EvidenceLedger, type EvidenceLedgerPort, InMemoryIntentStore, type IntentCorrelationPort, type IntentFacts, type ManualReport, type MaybePromise, type PayerCheckOptions, type ReputationExplanation, ReputationGraph, type ReputationGraphOptions, type ScoreWeights, type SubjectEvidence, type SyncOptions, type SyncedVendorScore, type VendorReputationSink, blend, blendBase, buildGraphServer, confidence, disputeComponent, longevityComponent, normalizeSubject, payerCheck, reliabilityComponent, subjectKey, volumeComponent };
+export { type CounterpartyLine, DEFAULT_CORRELATION_LIMIT, DEFAULT_WEIGHTS, type EventSource, EvidenceLedger, type EvidenceLedgerPort, type GraphServerOptions, InMemoryIntentStore, type IntentCorrelationPort, type IntentFacts, type ManualReport, type MaybePromise, type PayerCheckOptions, type ReputationExplanation, ReputationGraph, type ReputationGraphOptions, type ScoreWeights, type SubjectEvidence, type SyncOptions, type SyncedVendorScore, type VendorReputationSink, blend, blendBase, buildGraphServer, confidence, disputeComponent, graphAuthFromEnv, longevityComponent, normalizeSubject, payerCheck, reliabilityComponent, resolveGraphHost, subjectKey, volumeComponent };