@seasonkoh/webaz 0.1.24 → 0.1.26

package/dist/layer2-business/L2-9-contribution/identity-binding-store.js

@@ -0,0 +1,101 @@
+const IDENTITY_TABLES = ['identity_bindings_active', 'identity_binding_events']; // child-first for DROP
+const CREATE_EVENTS = `
+  CREATE TABLE IF NOT EXISTS identity_binding_events (
+    event_id             TEXT PRIMARY KEY,
+    event_type           TEXT NOT NULL CHECK (event_type IN ('bound','revoked')),
+    github_actor_id      TEXT NOT NULL,
+    account_id           TEXT NOT NULL REFERENCES users(id),
+    visibility           TEXT NOT NULL DEFAULT 'private' CHECK (visibility IN ('private','public')),
+    proof_method         TEXT NOT NULL CHECK (proof_method IN ('github_publication_challenge','admin_manual')),
+    proof_ref            TEXT,
+    supersedes_event_id  TEXT REFERENCES identity_binding_events(event_id),
+    created_at           TEXT NOT NULL DEFAULT (datetime('now')),
+    immutable            INTEGER NOT NULL DEFAULT 1 CHECK (immutable = 1),
+    UNIQUE (event_id, event_type, github_actor_id, account_id, visibility)
+  )
+`;
+const CREATE_ACTIVE = `
+  CREATE TABLE IF NOT EXISTS identity_bindings_active (
+    github_actor_id      TEXT PRIMARY KEY,
+    account_id           TEXT NOT NULL REFERENCES users(id),
+    visibility           TEXT NOT NULL DEFAULT 'private' CHECK (visibility IN ('private','public')),
+    bound_event_id       TEXT NOT NULL,
+    ref_event_type       TEXT NOT NULL DEFAULT 'bound' CHECK (ref_event_type = 'bound'),
+    bound_at             TEXT NOT NULL,
+    FOREIGN KEY (bound_event_id, ref_event_type, github_actor_id, account_id, visibility)
+      REFERENCES identity_binding_events(event_id, event_type, github_actor_id, account_id, visibility)
+  )
+`;
+const CREATE_INDEX = `CREATE INDEX IF NOT EXISTS idx_ibe_github_actor_id ON identity_binding_events(github_actor_id)`;
+// req1: DB-level immutability of the event log (SQLite). The PG generator emits the equivalent guard.
+const TRIGGER_NO_UPDATE = `CREATE TRIGGER IF NOT EXISTS trg_ibe_no_update BEFORE UPDATE ON identity_binding_events BEGIN SELECT RAISE(ABORT, 'identity_binding_events is append-only (UPDATE forbidden)'); END`;
+const TRIGGER_NO_DELETE = `CREATE TRIGGER IF NOT EXISTS trg_ibe_no_delete BEFORE DELETE ON identity_binding_events BEGIN SELECT RAISE(ABORT, 'identity_binding_events is append-only (DELETE forbidden)'); END`;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const tableExists = (db, name) => db.prepare(`SELECT 1 FROM sqlite_master WHERE type='table' AND name=?`).get(name) !== undefined;
+const triggerExists = (db, name) => db.prepare(`SELECT 1 FROM sqlite_master WHERE type='trigger' AND name=?`).get(name) !== undefined;
+const hasColumn = (db, table, col) => db.prepare(`SELECT 1 FROM pragma_table_info('${table}') WHERE name=?`).get(col) !== undefined;
+function hasUniqueOnCols(db, table, cols) {
+    for (const idx of db.prepare(`SELECT * FROM pragma_index_list('${table}')`).all()) {
+        if (idx.unique !== 1)
+            continue;
+        const onCols = db.prepare(`SELECT name FROM pragma_index_info('${idx.name}') ORDER BY seqno`).all().map(r => r.name);
+        if (onCols.length === cols.length && onCols.every((c, i) => c === cols[i]))
+            return true;
+    }
+    return false;
+}
+/**
+ * The req2 composite FK must REALLY exist (not just the ref_event_type column): a half-migrated
+ * `active` with the column but no FK would otherwise be misjudged as current and let mismatched
+ * projections through (Codex). Verify a FK on identity_bindings_active maps EXACTLY
+ * (bound_event_id, ref_event_type, github_actor_id, account_id, visibility) →
+ * identity_binding_events(event_id, event_type, github_actor_id, account_id, visibility).
+ */
+function activeHasCompositeFk(db) {
+    const wantFrom = ['bound_event_id', 'ref_event_type', 'github_actor_id', 'account_id', 'visibility'];
+    const wantTo = ['event_id', 'event_type', 'github_actor_id', 'account_id', 'visibility'];
+    const byId = new Map();
+    for (const r of db.prepare(`SELECT * FROM pragma_foreign_key_list('identity_bindings_active')`).all()) {
+        const g = byId.get(r.id);
+        if (g)
+            g.push(r);
+        else
+            byId.set(r.id, [r]);
+    }
+    for (const rows of byId.values()) {
+        if (rows[0].table !== 'identity_binding_events')
+            continue;
+        const sorted = [...rows].sort((a, b) => a.seq - b.seq);
+        const from = sorted.map(r => r.from), to = sorted.map(r => r.to);
+        if (from.length === wantFrom.length && from.every((c, i) => c === wantFrom[i]) && to.every((c, i) => c === wantTo[i]))
+            return true;
+    }
+    return false;
+}
+/** Full-structure check: both tables + req2 composite-UNIQUE + projection column + composite FK + req1 triggers. */
+function isCurrentShape(db) {
+    return IDENTITY_TABLES.every(t => tableExists(db, t))
+        && hasColumn(db, 'identity_bindings_active', 'ref_event_type')
+        && hasUniqueOnCols(db, 'identity_binding_events', ['event_id', 'event_type', 'github_actor_id', 'account_id', 'visibility'])
+        && activeHasCompositeFk(db)
+        && triggerExists(db, 'trg_ibe_no_update')
+        && triggerExists(db, 'trg_ibe_no_delete');
+}
+export function initIdentityBindingSchema(db) {
+    const apply = db.transaction(() => {
+        const present = IDENTITY_TABLES.filter(t => tableExists(db, t));
+        if (present.length > 0 && !isCurrentShape(db)) {
+            const total = present.reduce((n, t) => n + db.prepare(`SELECT COUNT(*) AS c FROM ${t}`).get().c, 0);
+            if (total !== 0)
+                throw new Error('identity binding store is old/partial shape but NOT empty — manual migration required (refusing to drop data)');
+            for (const t of IDENTITY_TABLES)
+                db.exec(`DROP TABLE IF EXISTS ${t}`); // child-first; events' triggers drop with it
+        }
+        db.exec(CREATE_EVENTS);
+        db.exec(CREATE_ACTIVE);
+        db.exec(CREATE_INDEX);
+        db.exec(TRIGGER_NO_UPDATE);
+        db.exec(TRIGGER_NO_DELETE);
+    });
+    apply.immediate();
+}

package/dist/layer2-business/L2-9-contribution/identity-claim-challenge-engine.js

@@ -0,0 +1,126 @@
+/**
+ * PR-F3b — GitHub identity-claim challenge ISSUANCE engine (internal). Issues an identity_claim_challenges
+ * row for an ACTIVE GitHub credential-backed contribution fact, and returns the proof marker the user
+ * copies into a GitHub Gist. NO API/MCP/UI; does NOT verify the gist (F3a) or bind (F2/4a).
+ *
+ * Security:
+ *   - Same trust root as F2: the fact must be GitHub credential-BACKED (assertGithubCredentialBackedFact)
+ *     — not governance/in_protocol/transaction, not a github fact without a credential link, not a
+ *     credential naming another actor.
+ *   - If the actor is already actively bound: same account → already_bound_self (no new challenge);
+ *     other account → refused already_bound_other (no challenge).
+ *   - nonce / challenge_id / expires_at are ENGINE-generated (crypto random; never caller-supplied —
+ *     the strict input rejects them). Only sha256(nonce) is stored; the plaintext nonce is returned ONLY
+ *     inside the proof_marker (never persisted).
+ *   - One synchronous db.transaction().immediate(); non-sqlite backend → fail-closed backend_unsupported.
+ *   - Predictable failures are typed results; unexpected errors throw loud.
+ */
+import { randomBytes } from 'node:crypto';
+import { z } from 'zod';
+import { seamBackendKind, seamSqliteHandle } from '../../layer0-foundation/L0-1-database/db.js';
+import { sha256hex } from './github-credential/canonical.js';
+import { assertGithubCredentialBackedFact } from './identity-claim-fact-precondition.js';
+import { CLAIM_MARKER_PREFIX } from './identity-claim-proof-verifier.js';
+const CHALLENGE_TTL = '+30 minutes'; // SQLite datetime modifier
+// Strict input — accountId/githubActorId/sourceEventKey only; caller-supplied nonce/challengeId/
+// expiresAt/unknown keys are rejected (engine generates those) → invalid_request.
+const IssueArgs = z.strictObject({
+    accountId: z.string().min(1),
+    githubActorId: z.string().min(1),
+    sourceEventKey: z.string().min(1),
+});
+const MAX_BUSY_RETRIES = 5;
+const BUSY_BACKOFF_MS = 25;
+const isSqliteBusy = (e) => { const c = e?.code; return c === 'SQLITE_BUSY' || c === 'SQLITE_BUSY_SNAPSHOT'; };
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+const refused = (reason, detail) => ({ ok: false, status: 'refused', reason, detail });
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export async function issueGithubIdentityClaimChallenge(args) {
+    const parsed = IssueArgs.safeParse(args);
+    if (!parsed.success) {
+        const reasons = parsed.error.issues.map(i => i.code === 'unrecognized_keys' ? `unrecognized argument(s): ${i.keys?.join(', ')}` : `${i.path.join('.') || '(args)'}: ${i.code}`);
+        return refused('invalid_request', reasons.join('; '));
+    }
+    const { accountId, githubActorId, sourceEventKey } = parsed.data;
+    const kind = seamBackendKind();
+    const db = seamSqliteHandle();
+    if (kind !== 'sqlite' || db === null)
+        return refused('backend_unsupported', `backend=${kind ?? 'uninitialized'}`);
+    const txn = db.transaction(() => {
+        // 1) credential-backed fact precondition (shared with F2). No write if it fails.
+        const pre = assertGithubCredentialBackedFact(db, sourceEventKey, githubActorId);
+        if (!pre.ok)
+            return refused(pre.reason, pre.detail);
+        // 2) already-bound state — never issue if the identity is already claimed.
+        const active = db.prepare('SELECT account_id FROM identity_bindings_active WHERE github_actor_id = ?')
+            .get(githubActorId);
+        if (active) {
+            if (active.account_id === accountId)
+                return { ok: true, status: 'already_bound_self', github_actor_id: githubActorId, account_id: accountId };
+            return refused('already_bound_other', 'github id is actively bound to a different account');
+        }
+        // 3) engine-generated, crypto-random nonce + id + expiry; store ONLY sha256(nonce).
+        const nonce = randomBytes(32).toString('hex'); // 64 lowercase hex
+        const challengeId = `icc_${randomBytes(20).toString('hex')}`; // icc_ + 40 hex
+        const nonceHash = sha256hex(nonce); // 64 lowercase hex (matches the table CHECK)
+        const expiresAt = db.prepare(`SELECT datetime('now', ?) AS t`).get(CHALLENGE_TTL).t;
+        db.prepare(`INSERT INTO identity_claim_challenges
+      (challenge_id, account_id, github_actor_id, source_event_key, nonce_hash, status, expires_at)
+      VALUES (?, ?, ?, ?, ?, 'issued', ?)`)
+            .run(challengeId, accountId, githubActorId, sourceEventKey, nonceHash, expiresAt);
+        // proof_marker carries the PLAINTEXT nonce (returned to caller, never persisted); prefix imported from
+        // the F3a verifier so the two never drift.
+        const proofMarker = `${CLAIM_MARKER_PREFIX}${challengeId}:${nonce}`;
+        return { ok: true, status: 'issued', challenge_id: challengeId, expires_at: expiresAt, proof_marker: proofMarker };
+    });
+    for (let attempt = 0;; attempt++) {
+        try {
+            return txn.immediate();
+        }
+        catch (err) {
+            if (isSqliteBusy(err) && attempt < MAX_BUSY_RETRIES) {
+                await sleep(BUSY_BACKOFF_MS * (attempt + 1));
+                continue;
+            }
+            if (isSqliteBusy(err))
+                return refused('db_busy', `busy after ${MAX_BUSY_RETRIES} retries`);
+            throw err;
+        }
+    }
+}
+// ── READ-ONLY: fetch the verification inputs the F3c API needs before it calls the F3a verifier ──
+// The API never embeds SQL against a core table (iron-rule rule4) and never holds the nonce plaintext:
+// it only needs the stored `nonce_hash` (the F3a `expectedNonceHash`) for a challenge that is ISSUED,
+// not expired, and owned by THIS (account, actor, source). Seam-based + read-only like the engines, so a
+// non-sqlite backend fails closed. This is ADVISORY (lets the API reject early / avoid a pointless GitHub
+// fetch); the AUTHORITATIVE single-use consume is still the CAS inside the F2 claim engine, so a
+// race here can never double-spend a challenge.
+const LookupArgs = z.strictObject({
+    challengeId: z.string().min(1),
+    accountId: z.string().min(1),
+    githubActorId: z.string().min(1),
+    sourceEventKey: z.string().min(1),
+});
+export function getIssuedChallengeForVerification(args) {
+    const parsed = LookupArgs.safeParse(args);
+    if (!parsed.success)
+        return { ok: false, reason: 'invalid_request' };
+    const { challengeId, accountId, githubActorId, sourceEventKey } = parsed.data;
+    const kind = seamBackendKind();
+    const db = seamSqliteHandle();
+    if (kind !== 'sqlite' || db === null)
+        return { ok: false, reason: 'backend_unsupported' };
+    // Bind ownership in the WHERE clause: a row for another account/actor/source is reported as not-found
+    // (no information about challenges the caller doesn't own).
+    const row = db.prepare(`SELECT status, nonce_hash, (expires_at > datetime('now')) AS not_expired
+    FROM identity_claim_challenges
+    WHERE challenge_id = ? AND account_id = ? AND github_actor_id = ? AND source_event_key = ?`)
+        .get(challengeId, accountId, githubActorId, sourceEventKey);
+    if (!row)
+        return { ok: false, reason: 'challenge_not_found' };
+    if (row.status === 'consumed')
+        return { ok: false, reason: 'challenge_already_used' };
+    if (row.status !== 'issued' || row.not_expired !== 1)
+        return { ok: false, reason: 'challenge_expired' };
+    return { ok: true, nonceHash: row.nonce_hash };
+}

package/dist/layer2-business/L2-9-contribution/identity-claim-challenge-store.js

@@ -0,0 +1,30 @@
+export function initIdentityClaimChallengeSchema(db) {
+    // DB-enforced state machine (Codex F1 P1) — illegal states must be rejected by the DB, not merely by
+    // a future engine:
+    //   - nonce_hash CHECK: a 64-char LOWERCASE sha256 hex digest, never a short/plaintext/upper value (P2).
+    //     `length=64 AND NOT GLOB '*[^0-9a-f]*'` (no char outside lowercase hex). gen-pg-schema translates
+    //     the GLOB to the PG regex `!~ '[^0-9a-f]'`.
+    //   - consumed_at NOT NULL IFF status='consumed' (the row-level consistency CHECK below).
+    //   - INSERT must be status='issued' (the BEFORE INSERT trigger below; a CHECK can't be INSERT-scoped).
+    //     consumed/expired/revoked are only reachable FROM 'issued' via the sanctioned status CAS (UPDATE).
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS identity_claim_challenges (
+      challenge_id         TEXT PRIMARY KEY,
+      account_id           TEXT NOT NULL REFERENCES users(id),
+      github_actor_id      TEXT NOT NULL,
+      source_event_key     TEXT NOT NULL,
+      nonce_hash           TEXT NOT NULL UNIQUE CHECK (length(nonce_hash) = 64 AND nonce_hash NOT GLOB '*[^0-9a-f]*'),
+      status               TEXT NOT NULL CHECK (status IN ('issued','consumed','expired','revoked')),
+      expires_at           TEXT NOT NULL,
+      consumed_at          TEXT,
+      created_at           TEXT NOT NULL DEFAULT (datetime('now')),
+      immutable            INTEGER NOT NULL DEFAULT 1 CHECK (immutable = 1),
+      CHECK ((status = 'consumed' AND consumed_at IS NOT NULL) OR (status <> 'consumed' AND consumed_at IS NULL))
+    )
+  `);
+    // Supports the future CAS lookup "find the issued challenge for this account+github+source event".
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_icc_lookup ON identity_claim_challenges(account_id, github_actor_id, source_event_key)`);
+    // INSERT-status guard: a row may only be created in 'issued' (the gen-pg-schema PG generator emits the
+    // equivalent BEFORE INSERT trigger). Status then migrates issued→{consumed,expired,revoked} via UPDATE.
+    db.exec(`CREATE TRIGGER IF NOT EXISTS trg_icc_insert_issued BEFORE INSERT ON identity_claim_challenges WHEN NEW.status <> 'issued' BEGIN SELECT RAISE(ABORT, 'identity_claim_challenges must be inserted with status=issued'); END`);
+}

package/dist/layer2-business/L2-9-contribution/identity-claim-discovery.js

@@ -0,0 +1,55 @@
+/**
+ * F10 — claimable GitHub contribution DISCOVERY (read-only). Lets a logged-in account see which
+ * credential-backed GitHub contribution facts are currently CLAIMABLE — i.e. their GitHub actor is not
+ * yet bound by ANY account — so the F9 claim UI no longer depends on a maintainer hand-delivering
+ * `source_event_key` / `github_actor_id` (dogfood R3 finding F10, proposal tp_ce110fed).
+ *
+ * Trust / safety boundaries (mirrors identity-claim-read.ts, PR-F4):
+ *   - READ-ONLY: this module issues SELECT only — it never writes identity_bindings_active /
+ *     identity_binding_events / contribution_facts / github_fact_credentials /
+ *     identity_claim_challenges, never issues a challenge, never touches accountable_ref.
+ *   - Same credential-backed trust root as F2/F3b/F4: a fact is surfaced only when it is
+ *     `source='github'` + `status='active'` + linked to a credential whose actor matches the fact's
+ *     `executor_ref` ('github:' || actor) — a forged executor_ref without a credential never appears.
+ *   - CLAIMABLE = the actor has NO active binding (LEFT JOIN … IS NULL): an actor bound by another
+ *     account is excluded (it is theirs), and an actor bound by the CALLER is also excluded here —
+ *     those facts already appear in /github/me's attributable_facts (the F4 surface).
+ *   - No secret in the output: no account_id, credential_id, core_json/digest, token, nonce,
+ *     nonce_hash, proof material. Only minimal display fields + what the claim form needs
+ *     (source_event_key + github_actor_id — both already disclosed-by-design at claim-challenge).
+ *   - `accountId` is accepted for interface parity with the other read engines (the route always passes
+ *     the SESSION user) and reserved for future per-account filtering; discovery output is currently
+ *     account-independent by construction (unbound actors only).
+ *
+ * Visibility posture: same as claim-challenge (#311, by design) — an unclaimed, credential-backed
+ * contribution is discoverable and claimable; that is the point of the GitHub-first promise.
+ * No reward / score / valuation anywhere; the route wraps the response in the uncommitted-value boundary.
+ */
+import { dbAll } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 async read seam
+// Active, credential-backed, executor-matching GitHub facts whose actor is NOT bound by any account.
+// DISTINCT collapses credential-version upgrade chains (multiple credentials → the same fact carry the
+// same PR identity fields). Newest merged work first; bounded.
+const CLAIMABLE_SQL = `
+  SELECT DISTINCT f.fact_id, f.source_event_key, f.source, f.type, f.artifact_ref, f.occurred_at,
+         f.created_at, c.github_actor_id, c.repository_id, c.pr_number, c.merge_commit_sha,
+         c.merged_at, c.lifecycle_event
+  FROM contribution_facts f
+  JOIN github_fact_credentials l
+    ON l.fact_id = f.fact_id AND l.source_event_key = f.source_event_key
+  JOIN github_contribution_credentials c
+    ON c.credential_id = l.credential_id AND c.source_event_key = l.source_event_key
+  LEFT JOIN identity_bindings_active b
+    ON b.github_actor_id = c.github_actor_id
+  WHERE f.source = 'github'
+    AND f.status = 'active'
+    AND f.executor_ref = 'github:' || c.github_actor_id
+    AND b.github_actor_id IS NULL
+  ORDER BY COALESCE(c.merged_at, f.created_at) DESC, f.fact_id
+  LIMIT 50`;
+/** List the currently claimable (unbound-actor) credential-backed GitHub facts. Read-only. */
+export async function listClaimableGithubIdentityFacts(accountId) {
+    if (!accountId || typeof accountId !== 'string')
+        return { claimable_facts: [] };
+    const rows = await dbAll(CLAIMABLE_SQL, []);
+    return { claimable_facts: rows };
+}

package/dist/layer2-business/L2-9-contribution/identity-claim-engine.js

@@ -0,0 +1,109 @@
+/**
+ * PR-F2 — GitHub identity claim engine (NO API). Consumes an issued publication challenge and binds the
+ * GitHub actor → WebAZ account, in ONE synchronous transaction. Design: docs/IDENTITY-CLAIM-DESIGN.md.
+ *
+ * Trust boundary (F2 vs F3): F2 takes `proofVerified: true` — the publication proof (gist via the #295
+ * authenticated read) is F3's job. F2 REFUSES (proof_not_verified) if the flag is not explicitly true,
+ * so an un-verified proof can never complete a binding. No API/MCP/UI, no GitHub fetch here.
+ *
+ * Binding granularity is IDENTITY-level: `github_actor_id → account_id` (the stable actor id, NEVER the
+ * renameable login). The fact/source_event_key is only a PRECONDITION GUARD ("this GitHub actor has a
+ * claimable contribution"): the fact must exist and its executor must be this github_actor_id.
+ *
+ * Atomicity (Codex F2): challenge consume (CAS) + bind run in ONE synchronous `db.transaction().immediate()`.
+ * The fact/actor precondition is checked BEFORE the CAS, so a doomed claim never consumes the challenge.
+ * The CAS requires status='issued' AND not expired AND account/github/source all match → changes=1. If the
+ * bind then refuses (already_bound_to_other) or anything throws, the whole tx ROLLS BACK — the challenge is
+ * NOT left consumed. No async/await inside the transaction. proof_method is always
+ * 'github_publication_challenge' (never the governance/manual override path). visibility defaults 'private'.
+ */
+import { seamBackendKind, seamSqliteHandle } from '../../layer0-foundation/L0-1-database/db.js';
+import { bindGithubIdentityCore } from './identity-binding-engine.js';
+import { assertGithubCredentialBackedFact } from './identity-claim-fact-precondition.js';
+const MAX_BUSY_RETRIES = 5;
+const BUSY_BACKOFF_MS = 25;
+const isSqliteBusy = (e) => {
+    const c = e?.code;
+    return c === 'SQLITE_BUSY' || c === 'SQLITE_BUSY_SNAPSHOT';
+};
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+const refused = (reason, detail) => ({ ok: false, status: 'refused', reason, detail });
+// Sentinel thrown inside the tx to ROLL BACK a consumed challenge (e.g. bind refused) — caught outside.
+class ClaimRollback extends Error {
+    outcome;
+    constructor(outcome) {
+        super('claim rollback');
+        this.outcome = outcome;
+    }
+}
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export async function claimGithubIdentity(input) {
+    const { accountId, githubActorId, sourceEventKey, challengeId } = input;
+    if (!accountId || !githubActorId || !sourceEventKey || !challengeId) {
+        return refused('invariant_violation', 'accountId, githubActorId, sourceEventKey, challengeId are required');
+    }
+    // Proof gate — F2 only completes a binding for a PRE-VERIFIED proof (F3 verifies the gist).
+    if (input.proofVerified !== true)
+        return refused('proof_not_verified', 'publication proof is not verified (F3 must verify before F2 binds)');
+    const kind = seamBackendKind();
+    const db = seamSqliteHandle();
+    if (kind !== 'sqlite' || db === null)
+        return refused('backend_unsupported', `backend=${kind ?? 'uninitialized'}`);
+    const txn = db.transaction(() => {
+        // 1) precondition (BEFORE the CAS, so a doomed claim leaves the challenge ISSUED): the fact must be a
+        //    GitHub credential-BACKED active fact whose AUTHENTICATED credential names this actor (Codex F2 P1).
+        //    Shared with the F3b issuance engine via assertGithubCredentialBackedFact (behavior-zero).
+        const pre = assertGithubCredentialBackedFact(db, sourceEventKey, githubActorId);
+        if (!pre.ok)
+            return refused(pre.reason, pre.detail);
+        // 2) CAS consume the issued challenge (single-use; all of account/github/source must match).
+        const cas = db.prepare(`UPDATE identity_claim_challenges
+      SET status = 'consumed', consumed_at = datetime('now')
+      WHERE challenge_id = ? AND status = 'issued' AND expires_at > datetime('now')
+        AND account_id = ? AND github_actor_id = ? AND source_event_key = ?`)
+            .run(challengeId, accountId, githubActorId, sourceEventKey);
+        if (cas.changes !== 1) {
+            // 0 changes → no write happened; determine WHY (commit is a no-op, challenge state untouched).
+            const row = db.prepare(`SELECT status, (expires_at > datetime('now')) AS not_expired, account_id, github_actor_id, source_event_key
+        FROM identity_claim_challenges WHERE challenge_id = ?`).get(challengeId);
+            if (!row)
+                return refused('challenge_not_found');
+            if (row.status === 'consumed')
+                return refused('challenge_already_used');
+            if (row.status === 'expired' || row.status === 'revoked')
+                return refused('challenge_expired');
+            if (row.status === 'issued' && row.not_expired !== 1)
+                return refused('challenge_expired');
+            // issued + not expired but account/github/source didn't match this claim → no matching challenge.
+            if (row.account_id !== accountId || row.github_actor_id !== githubActorId || row.source_event_key !== sourceEventKey)
+                return refused('challenge_not_found');
+            return refused('invariant_violation', 'challenge CAS matched 0 rows for an otherwise-valid challenge');
+        }
+        // 3) bind (challenge now consumed in THIS tx). bound→claimed; already_bound(self)→commit idempotently;
+        //    already_bound_to_other / unexpected → THROW to roll back the consumed challenge.
+        const b = bindGithubIdentityCore(db, { githubActorId, accountId, proofMethod: 'github_publication_challenge', proofRef: challengeId, visibility: 'private' });
+        if (b.ok && b.status === 'bound')
+            return { ok: true, status: 'claimed', github_actor_id: githubActorId, account_id: accountId, challenge_id: challengeId };
+        if (b.ok && b.status === 'already_bound')
+            return { ok: true, status: 'already_bound_self', github_actor_id: githubActorId, account_id: accountId, challenge_id: challengeId };
+        if (!b.ok && b.reason === 'already_bound_to_other')
+            throw new ClaimRollback(refused('already_bound_other', b.detail));
+        throw new ClaimRollback(refused('invariant_violation', `unexpected bind result: ${JSON.stringify(b)}`));
+    });
+    for (let attempt = 0;; attempt++) {
+        try {
+            return txn.immediate();
+        }
+        catch (err) {
+            if (err instanceof ClaimRollback)
+                return err.outcome;
+            if (isSqliteBusy(err) && attempt < MAX_BUSY_RETRIES) {
+                await sleep(BUSY_BACKOFF_MS * (attempt + 1));
+                continue;
+            }
+            if (isSqliteBusy(err))
+                return refused('db_busy', `busy after ${MAX_BUSY_RETRIES} retries`);
+            throw err;
+        }
+    }
+}

package/dist/layer2-business/L2-9-contribution/identity-claim-fact-precondition.js

@@ -0,0 +1,22 @@
+export function assertGithubCredentialBackedFact(db, sourceEventKey, githubActorId) {
+    const backed = db.prepare(`
+    SELECT 1 AS ok
+    FROM contribution_facts f
+    JOIN github_fact_credentials l ON l.fact_id = f.fact_id AND l.source_event_key = f.source_event_key
+    JOIN github_contribution_credentials c ON c.credential_id = l.credential_id AND c.source_event_key = l.source_event_key
+    WHERE f.source_event_key = ? AND f.source = 'github' AND f.status = 'active'
+      AND f.executor_ref = ? AND c.github_actor_id = ?
+    LIMIT 1`).get(sourceEventKey, `github:${githubActorId}`, githubActorId);
+    if (backed)
+        return { ok: true };
+    // Not credential-backed. Distinguish actor_mismatch (a github fact exists but its generic executor
+    // names another actor) from fact_not_found (everything else: no fact / not active / wrong source /
+    // no link / credential names another actor).
+    const f = db.prepare('SELECT executor_ref FROM contribution_facts WHERE source_event_key = ?')
+        .get(sourceEventKey);
+    if (!f)
+        return { ok: false, reason: 'fact_not_found', detail: sourceEventKey };
+    if (f.executor_ref !== `github:${githubActorId}`)
+        return { ok: false, reason: 'actor_mismatch', detail: `fact executor ${f.executor_ref} != github:${githubActorId}` };
+    return { ok: false, reason: 'fact_not_found', detail: 'no active GitHub credential-backed fact for this actor/source' };
+}

package/dist/layer2-business/L2-9-contribution/identity-claim-proof-verifier.js

@@ -0,0 +1,97 @@
+/**
+ * PR-F3a — GitHub identity-claim publication-proof verifier (GitHub Gist proof v1). INTERNAL.
+ *
+ * Trust root (lesson from #308): identity-claim authenticity must come from WebAZ's OWN authenticated
+ * re-fetch, never from caller-supplied JSON / owner / digest. This verifier RE-FETCHES the gist via the
+ * #295/#301 audited primitives (`pathFromOrigin` + `getJson`, fixed origin https://api.github.com,
+ * GET-only, manual-redirect, AbortSignal timeout) and verifies:
+ *   - the gist's `owner.id` STRICTLY equals `githubActorId` (the stable id — NEVER login);
+ *   - a gist file contains the marker `webaz-identity-claim:v1:<challengeId>:<nonce>`;
+ *   - `sha256(nonce)` equals `expectedNonceHash` (the value stored in identity_claim_challenges).
+ *
+ * Scope: ONLY GitHub Gist proof v1. No API/DB write/claim-commit here. The production entry takes NO
+ * fetchImpl/now/caller-owner injection (uses globalThis.fetch; tests swap the global). `token` is a
+ * trusted-config dep (optional — public gists need none); it is sent ONLY to api.github.com and NEVER
+ * appears in any result/reasons. Truncated content → refused `proof_truncated` (raw_url is NEVER
+ * followed). Every failure is a TYPED outcome; the function never throws a predictable error.
+ */
+import { z } from 'zod';
+import { getJson, pathFromOrigin, DEFAULT_TIMEOUT_MS } from './github-credential/github-fetch-adapter.js';
+import { sha256hex } from './github-credential/canonical.js';
+export const CLAIM_MARKER_PREFIX = 'webaz-identity-claim:v1:'; // full marker: <prefix><challengeId>:<nonce>
+const NONCE_RE_BODY = '([A-Za-z0-9_-]+)';
+// Strict args — rejects unknown keys (fetchImpl / now / caller-supplied owner all refused as invalid_request).
+const ArgsSchema = z.strictObject({
+    gistId: z.string().min(1),
+    githubActorId: z.string().min(1),
+    challengeId: z.string().min(1),
+    expectedNonceHash: z.string().regex(/^[0-9a-f]{64}$/), // sha256 hex
+    token: z.string().min(1).optional(), // trusted config; public gists need none
+    timeoutMs: z.number().int().positive().max(30_000).optional(),
+});
+// Tolerant view of the GitHub Gist response (extra fields ignored; missing/typed-wrong → malformed_response).
+const GistResponse = z.object({
+    owner: z.object({ id: z.union([z.number(), z.string()]) }).passthrough().nullable().optional(),
+    truncated: z.boolean().optional(),
+    files: z.record(z.string(), z.object({ content: z.string().optional(), truncated: z.boolean().optional() }).passthrough()),
+}).passthrough();
+const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+export async function verifyGithubGistProof(args) {
+    const parsed = ArgsSchema.safeParse(args);
+    if (!parsed.success) {
+        // codes only — never echo a value (no token / nonce / url leak)
+        const reasons = parsed.error.issues.map(i => i.code === 'unrecognized_keys'
+            ? `unrecognized argument(s): ${i.keys?.join(', ')}`
+            : `${i.path.join('.') || '(args)'}: ${i.code}`);
+        return { ok: false, outcome: 'invalid_request', reasons };
+    }
+    const a = parsed.data;
+    const timeoutMs = a.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const doFetch = globalThis.fetch; // runtime transport — NOT caller-injectable
+    try {
+        let url;
+        try {
+            url = pathFromOrigin('gists', a.gistId);
+        } // fixed origin api.github.com; encodes the id
+        catch {
+            return { ok: false, outcome: 'invalid_request', reasons: ['could not build a safe api.github.com gist URL'] };
+        }
+        // WebAZ's own authenticated read (getJson rejects any non-https://api.github.com URL — #301 P1).
+        const res = await getJson(doFetch, url, a.token, timeoutMs);
+        if (res.kind === 'fail')
+            return { ok: false, outcome: res.outcome, reasons: res.reasons }; // getJson reasons are token-free
+        const parsedGist = GistResponse.safeParse(res.body);
+        if (!parsedGist.success)
+            return { ok: false, outcome: 'malformed_response', reasons: ['gist response missing/typed-wrong fields'] };
+        const gist = parsedGist.data;
+        // owner.id must STRICTLY equal the claimed stable actor id (never login; anonymous gist → no owner).
+        if (!gist.owner || String(gist.owner.id) !== a.githubActorId) {
+            return { ok: false, outcome: 'owner_mismatch', reasons: ['gist owner.id != githubActorId'] };
+        }
+        // search every NON-truncated file for the challenge marker; raw_url is NEVER followed.
+        const re = new RegExp(escapeRegex(`${CLAIM_MARKER_PREFIX}${a.challengeId}:`) + NONCE_RE_BODY);
+        let anyTruncated = gist.truncated === true;
+        for (const fname of Object.keys(gist.files)) {
+            const f = gist.files[fname];
+            if (f?.truncated === true) {
+                anyTruncated = true;
+                continue;
+            } // incomplete → don't trust; don't fetch raw_url
+            const content = f?.content;
+            if (typeof content !== 'string')
+                continue;
+            const m = re.exec(content);
+            if (m) {
+                if (sha256hex(m[1]) === a.expectedNonceHash)
+                    return { ok: true, github_actor_id: a.githubActorId, challenge_id: a.challengeId };
+                return { ok: false, outcome: 'nonce_mismatch', reasons: ['sha256(nonce) != expectedNonceHash'] };
+            }
+        }
+        if (anyTruncated)
+            return { ok: false, outcome: 'proof_truncated', reasons: ['gist content truncated; raw_url NOT followed — re-post the marker in a small file'] };
+        return { ok: false, outcome: 'proof_not_found', reasons: ['claim marker not found in gist files'] };
+    }
+    catch {
+        return { ok: false, outcome: 'upstream_unavailable', reasons: ['unexpected verifier error'] }; // never leak the token
+    }
+}

package/dist/layer2-business/L2-9-contribution/identity-claim-read.js

@@ -0,0 +1,59 @@
+/**
+ * PR-F4 — GitHub identity-claim READ surface (contribution attribution visibility). INTERNAL read-only.
+ *
+ * Lets a logged-in account see (a) its OWN current GitHub identity bindings and (b) the contribution
+ * facts that are currently attributable to it via those bindings — the accountable READ-OVERLAY. This
+ * does NOT change `contribution_facts.accountable_ref` (which stays NULL — facts are immutable; the
+ * accountable party is resolved at read time from `identity_bindings_active`, per RFC-017 I-3 and the
+ * 4a engine's `resolveAccountable`).
+ *
+ * Scope is the WHOLE security argument here: every query is anchored on `account_id = <the caller>`, so
+ * a row for any OTHER account is never selected. No other account's id is returned; no token / email /
+ * nonce / nonce_hash / gist content is read or returned. No reward / score / KYC — visibility only.
+ *
+ * A fact is "mine" iff it is an ACTIVE GitHub credential-BACKED fact (same trust root as the F2/F3b
+ * precondition: contribution_facts ⋈ github_fact_credentials ⋈ github_contribution_credentials) AND its
+ * `executor_ref` is `github:<actor>` for an `<actor>` CURRENTLY bound to me. The credential join means a
+ * fact with a merely-matching generic `executor_ref` but no authenticated credential is NOT shown (the
+ * #308 lesson), and the executor-match means a credential for my actor on a fact executed by someone else
+ * is NOT shown either.
+ *
+ * Read path: the async seam (dbAll) — no transaction, backend-agnostic. spec: docs/IDENTITY-CLAIM-DESIGN.md §8.7.
+ */
+import { dbAll } from '../../layer0-foundation/L0-1-database/db.js';
+// SELECT only the caller's OWN active bindings — never another account's. account_id is NOT returned
+// (the surface is the caller's own); visibility is shown to its OWNER only (this endpoint never serves
+// another account), so a `private` binding is never disclosed to anyone else.
+const BINDINGS_SQL = `
+  SELECT github_actor_id, visibility, bound_at
+  FROM identity_bindings_active
+  WHERE account_id = ?
+  ORDER BY bound_at DESC, github_actor_id`;
+// Accountable overlay, anchored on the caller's bindings: a fact is attributable to me iff it is an
+// active GitHub credential-BACKED fact whose executor is an actor I currently hold a binding for. The
+// b.account_id = ? anchor + identity_bindings_active's actor PK mean only MY facts can be returned.
+const FACTS_SQL = `
+  SELECT DISTINCT f.fact_id, f.source_event_key, f.source, f.type, f.artifact_ref, f.occurred_at,
+         f.executor_ref, f.provenance, f.status, f.created_at, b.github_actor_id
+  FROM identity_bindings_active b
+  JOIN github_contribution_credentials c
+    ON c.github_actor_id = b.github_actor_id
+  JOIN github_fact_credentials l
+    ON l.credential_id = c.credential_id AND l.source_event_key = c.source_event_key
+  JOIN contribution_facts f
+    ON f.fact_id = l.fact_id AND f.source_event_key = l.source_event_key
+  WHERE b.account_id = ?
+    AND f.source = 'github'
+    AND f.status = 'active'
+    AND f.executor_ref = 'github:' || b.github_actor_id
+  ORDER BY f.created_at DESC, f.fact_id`;
+/** The caller's OWN GitHub identity bindings + the contribution facts currently attributable to them. */
+export async function getMyGithubIdentitySurface(accountId) {
+    if (!accountId)
+        return { bindings: [], attributable_facts: [] }; // defensive — route always passes the session user
+    const [bindings, attributable_facts] = await Promise.all([
+        dbAll(BINDINGS_SQL, [accountId]),
+        dbAll(FACTS_SQL, [accountId]),
+    ]);
+    return { bindings, attributable_facts };
+}