@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/risk-compliance/doc-authenticity/scripts/validate_verdict.test.mjs

@@ -0,0 +1,212 @@
+// @covers doc-authenticity:routed-verdict-contract
+// @level integration
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPTS = dirname(fileURLToPath(import.meta.url));
+const VALIDATOR = join(SCRIPTS, 'validate_verdict.py');
+const VALIDITY_IDS = {
+  bank_statement: [...Array.from({ length: 5 }, (_, i) => `C${i + 1}`), ...Array.from({ length: 5 }, (_, i) => `D${i + 1}`)],
+  invoice: Array.from({ length: 8 }, (_, i) => `N${i + 1}`),
+  agreement: Array.from({ length: 8 }, (_, i) => `A${i + 1}`),
+  conversation_log: [],
+  other: [],
+};
+const CONTENT_IDS = new Set([
+  ...Array.from({ length: 5 }, (_, i) => `C${i + 1}`),
+  'N2', 'N3', 'N4', 'N7',
+  'A2', 'A4', 'A5', 'A7',
+]);
+
+function check(id) {
+  const authenticity = id.startsWith('F') || id.startsWith('I');
+  return {
+    id,
+    name: `Check ${id}`,
+    axis: authenticity ? 'authenticity' : 'validity',
+    dimension: authenticity ? 'file_forensics' : CONTENT_IDS.has(id) ? 'content' : 'domain',
+    result: 'PASS',
+    decisive: false,
+    evidence: `Concrete evidence for ${id}.`,
+  };
+}
+
+function verdict(fileType, docType) {
+  const prefix = fileType === 'pdf' ? 'F' : 'I';
+  const authIds = Array.from({ length: 9 }, (_, i) => `${prefix}${i + 1}`);
+  const validityIds = VALIDITY_IDS[docType];
+  return {
+    schema_version: '2.2',
+    artifact: {
+      path: `/tmp/${fileType}-${docType}`,
+      file_type: fileType,
+      media_type: fileType === 'pdf' ? 'application/pdf' : 'image/jpeg',
+      size_bytes: 1234,
+      sha256: 'a'.repeat(64),
+      extension_magic_match: true,
+      doc_type: docType,
+      detail: 'route fixture',
+      claimed_issuer: null,
+      supplied_claim: 'Test document.',
+    },
+    authenticity: {
+      verdict: 'NO_EVIDENCE_OF_MODIFICATION',
+      confidence: 'MEDIUM',
+      summary: 'No modification evidence.',
+    },
+    validity: {
+      verdict: validityIds.length ? 'VALID' : 'INCONCLUSIVE',
+      confidence: 'LOW',
+      summary: 'Validity route result.',
+    },
+    checks: [...authIds, ...validityIds].map(check),
+    summary: 'Route test.',
+    checked_at: '2026-09-03T13:30:00+08:00',
+  };
+}
+
+function runValidator(directory, name, value) {
+  const path = join(directory, `${name}.json`);
+  writeFileSync(path, `${JSON.stringify(value)}\n`);
+  return spawnSync('python3', [VALIDATOR, path], { encoding: 'utf8' });
+}
+
+test('all file-type and document-type routes require the correct check set', () => {
+  const directory = mkdtempSync(join(tmpdir(), 'doc-auth-routes-'));
+  try {
+    for (const fileType of ['pdf', 'image']) {
+      for (const docType of Object.keys(VALIDITY_IDS)) {
+        const result = runValidator(directory, `${fileType}-${docType}`, verdict(fileType, docType));
+        assert.equal(result.status, 0, `${fileType}/${docType}: ${result.stdout}${result.stderr}`);
+        assert.match(result.stdout, new RegExp(`valid: ${fileType}/${docType} route`));
+      }
+    }
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+test('conversation logs and other documents cannot claim specialized validity', () => {
+  const directory = mkdtempSync(join(tmpdir(), 'doc-auth-no-validity-'));
+  try {
+    for (const docType of ['conversation_log', 'other']) {
+      const value = verdict('image', docType);
+      value.validity.verdict = 'VALID';
+      const result = runValidator(directory, docType, value);
+      assert.notEqual(result.status, 0);
+      assert.match(result.stdout, /validity verdict must be INCONCLUSIVE/);
+    }
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+test('missing and cross-profile validity checks fail closed', () => {
+  const directory = mkdtempSync(join(tmpdir(), 'doc-auth-invalid-route-'));
+  try {
+    const missing = verdict('pdf', 'invoice');
+    missing.checks = missing.checks.filter(({ id }) => id !== 'N8');
+    const missingResult = runValidator(directory, 'missing-invoice-check', missing);
+    assert.notEqual(missingResult.status, 0);
+    assert.match(missingResult.stdout, /missing checks: \['N8'\]/);
+
+    const mixed = verdict('image', 'agreement');
+    mixed.checks.push(check('N1'));
+    const mixedResult = runValidator(directory, 'mixed-agreement-check', mixed);
+    assert.notEqual(mixedResult.status, 0);
+    assert.match(mixedResult.stdout, /checks do not belong to the selected route: \['N1'\]/);
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+test('artifact audit fields and checked_at timezone are mandatory', () => {
+  const directory = mkdtempSync(join(tmpdir(), 'doc-auth-artifact-'));
+  try {
+    const missingAudit = verdict('pdf', 'invoice');
+    delete missingAudit.artifact.sha256;
+    const missingResult = runValidator(directory, 'missing-hash', missingAudit);
+    assert.notEqual(missingResult.status, 0);
+    assert.match(missingResult.stdout, /artifact missing keys: \['sha256'\]/);
+
+    const badTimestamp = verdict('pdf', 'invoice');
+    badTimestamp.checked_at = '2026-99-99T13:30:00';
+    const timestampResult = runValidator(directory, 'bad-timestamp', badTimestamp);
+    assert.notEqual(timestampResult.status, 0);
+    assert.match(timestampResult.stdout, /valid ISO 8601 timestamp with timezone/);
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+test('authenticity verdict must match decisive, FAIL, FLAG, and NA thresholds', () => {
+  const directory = mkdtempSync(join(tmpdir(), 'doc-auth-rubric-'));
+  try {
+    const tooManyFlags = verdict('pdf', 'other');
+    for (const id of ['F1', 'F2', 'F3']) tooManyFlags.checks.find((item) => item.id === id).result = 'FLAG';
+    const flagsResult = runValidator(directory, 'flags', tooManyFlags);
+    assert.notEqual(flagsResult.status, 0);
+    assert.match(flagsResult.stdout, /authenticity verdict must be SUSPICIOUS/);
+
+    const unavailable = verdict('pdf', 'other');
+    for (const id of ['F1', 'F2', 'F3', 'F4', 'F5']) unavailable.checks.find((item) => item.id === id).result = 'NA';
+    const unavailableResult = runValidator(directory, 'unavailable', unavailable);
+    assert.notEqual(unavailableResult.status, 0);
+    assert.match(unavailableResult.stdout, /authenticity verdict must be INCONCLUSIVE/);
+
+    const decisive = verdict('image', 'other');
+    decisive.authenticity.verdict = 'LIKELY_MODIFIED';
+    const splice = decisive.checks.find((item) => item.id === 'I7');
+    splice.result = 'FAIL';
+    splice.decisive = true;
+    const decisiveResult = runValidator(directory, 'decisive', decisive);
+    assert.equal(decisiveResult.status, 0, decisiveResult.stdout);
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+test('validity verdict must match decisive, FAIL, FLAG, and NA thresholds', () => {
+  const directory = mkdtempSync(join(tmpdir(), 'doc-validity-rubric-'));
+  try {
+    const unavailable = verdict('pdf', 'invoice');
+    unavailable.validity.verdict = 'INCONCLUSIVE';
+    for (const id of ['N1', 'N2', 'N3', 'N4']) unavailable.checks.find((item) => item.id === id).result = 'NA';
+    const unavailableResult = runValidator(directory, 'unavailable-validity', unavailable);
+    assert.equal(unavailableResult.status, 0, unavailableResult.stdout);
+
+    const decisive = verdict('pdf', 'agreement');
+    decisive.validity.verdict = 'INVALID';
+    const conflict = decisive.checks.find((item) => item.id === 'A4');
+    conflict.result = 'FAIL';
+    conflict.decisive = true;
+    const decisiveResult = runValidator(directory, 'decisive-validity', decisive);
+    assert.equal(decisiveResult.status, 0, decisiveResult.stdout);
+
+    const invalidDecisive = verdict('pdf', 'invoice');
+    invalidDecisive.checks.find((item) => item.id === 'N1').decisive = true;
+    const invalidResult = runValidator(directory, 'decisive-pass', invalidDecisive);
+    assert.notEqual(invalidResult.status, 0);
+    assert.match(invalidResult.stdout, /only a FAIL can be decisive/);
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+test('the schema advertises every routed document type and check family', () => {
+  const schema = JSON.parse(readFileSync(join(SCRIPTS, '..', 'references', 'verdict.schema.json'), 'utf8'));
+  assert.deepEqual(
+    schema.properties.artifact.properties.doc_type.enum,
+    ['bank_statement', 'conversation_log', 'invoice', 'agreement', 'other'],
+  );
+  assert.equal(schema.properties.schema_version.const, '2.2');
+  assert.ok(schema.properties.artifact.required.includes('sha256'));
+  assert.ok(schema.$defs.check.required.includes('decisive'));
+  assert.match(schema.$defs.check.properties.id.pattern, /N\[1-8\]/);
+  assert.match(schema.$defs.check.properties.id.pattern, /A\[1-8\]/);
+});

package/skills/risk-compliance/fraud-analysis/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/risk-compliance/fraud-analysis/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: fraud-analysis
+description: >
+  Analyze tabular payment, transfer, collection, payout, account, or fraud-case
+  data (CSV, XLSX, TXT) to find interpretable features and operable risk rules.
+  Supports third-party fraud (including stolen credentials and account takeover),
+  first-party fraud or deliberate account abuse, and authorized payment scams
+  (including APP scams), across card payments, collections, bank transfers, and
+  payouts. Produces temporal holdout metrics, domain-appropriate actions, strategy
+  impact, and a business report. Use for fraud, scam, mule, account-takeover,
+  chargeback, dispute, transfer, collection, or payout risk analysis even when the
+  user does not name this skill.
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Fraud Analysis
+
+Analyze fraud through composable dimensions rather than treating every case as
+card fraud:
+
+- **Archetype** — the genuine customer's relationship to the fraud
+- **Mechanism** — how compromise, deception, or abuse occurred
+- **Context** — the product or money-movement surface where a rule fires
+
+Run this **10-step** loop:
+
+0. Pre-flight → 1. Profile → 2. Label → 3. Time split → 4. Engineer features →
+5. Shortlist → 6. Score rules → 7. Map actions + packages → 8. Write report →
+9. Review
+
+**Produce:** operable rules and portfolio impact in a business report.  
+**Do not produce:** a black-box model as the main answer.
+
+> Paths under `references/` are relative to this skill directory. Step detail:
+> [references/workflow.md](references/workflow.md).
+
+## Required references
+
+| File | When |
+|---|---|
+| [references/workflow.md](references/workflow.md) | Every step — full procedure |
+| [references/taxonomy.md](references/taxonomy.md) | Step 1; select archetype, mechanism, and context |
+| [references/feature-engineering.md](references/feature-engineering.md) | Step 4; shared decision-time rules |
+| [references/report-template.md](references/report-template.md) | Step 8; common report contract and overlay selection |
+| [references/terminology.md](references/terminology.md) | Step 8; fixed terms and language proofread |
+| [references/review-checklist.md](references/review-checklist.md) | Step 9; common and selected-profile checks |
+
+After Step 1, read only the selected profile references:
+
+| Dimension | References |
+|---|---|
+| Archetype | `references/archetypes/<archetype>.md` |
+| Mechanism | `references/mechanisms/<mechanism>.md` when present |
+| Context | `references/contexts/<context>.md` for every selected context |
+
+Current packs: archetypes `third-party-fraud`, `first-party-fraud`,
+`authorized-payment-scam`; mechanism `account-takeover`; contexts
+`card-payment`, `payment-collection`, `bank-transfer`, `payout`.
+
+## Progress
+
+Track a task plan. One item is `in_progress` at a time.
+
+1. Pass pre-flight
+2. Select analysis profile
+3. Formalize label
+4. Freeze time split
+5. Engineer candidate features
+6. Select shortlist
+7. Score candidate rules
+8. Map actions and packages
+9. Write business report and proofread language
+10. Independent review
+
+Suggested notes: `preflight=…`, `profile=…`, `label=…`, `cut=…`,
+`allowed/excluded=…`, `shortlist=…`, `N rules, holdout|in-sample`,
+`packages=…`, `report=…`, `verdict=…`.
+
+## Input
+
+CSV / XLSX / TXT; one row per event or case; optional outcome column. A dataset
+may contain more than one event type, but every scored rule needs a declared
+event grain and decision point.
+
+## Workflow
+
+Follow [references/workflow.md](references/workflow.md) for each step. The map:
+
+| Step | Do | Gate |
+|---|---|---|
+| 0 Pre-flight | Label provenance; pass / needs-user-input / descriptive-only / blocked | No supervised metrics until pass |
+| 1 Profile | Archetype + mechanism(s) + context(s) from taxonomy | Read selected packs before Step 2 |
+| 2 Label | Formalize positive / negative / unlabeled | Both classes defined before scoring |
+| 3 Time split | Freeze train/holdout before features | No random shuffle as headline |
+| 4 Features | Engineer candidates at decision time | Train-only thresholds |
+| 5 Shortlist | Lift / support / stability / operability | Train only |
+| 6 Score | occurrence → precision → recall on holdout | Headline = holdout |
+| 7 Actions | Map to context packs + strategy packages | Freeze packages before report |
+| 8 Report | Business report per template; grep terminology banned strings | No review process in the file |
+| 9 Review | Checklist + selected packs | Prefer fresh independent reviewer |
+
+## Output contract
+
+| Item | Requirement |
+|---|---|
+| Analysis profile | Archetype, role, consent, technical authentication, mechanism, context, confidence, grain, decision point |
+| Rule metrics | occurrence → precision → recall; headline window identified |
+| Strategy coverage | triggered count + rate and amount + share, with currency |
+| Domain impact | Measures and denominators from selected context packs only |
+| Uncertainty | Proxy labels, immature outcomes, weak identity links, and unresolved attribution stated |
+| Report file | Business content only; no reviewer model, verdict, or repair log |
+
+Steps 0–7 are analysis and its entry gate. Step 8 writes the report. Step 9
+reviews it.

package/skills/risk-compliance/fraud-analysis/references/archetypes/authorized-payment-scam.md

@@ -0,0 +1,41 @@
+# Archetype: authorized payment scam
+
+The genuine customer consents to a payment but is deceived about the recipient
+or purpose. The customer is the victim and is not knowingly party to the fraud.
+
+Use subtype `app-scam` only for an authorized push payment, normally a bank
+transfer. Record the scam subtype when supported, such as impersonation,
+purchase, investment, romance, or invoice redirection; do not infer it from
+amount or beneficiary shape alone.
+
+## Label guidance
+
+Prefer adjudicated scam outcomes. Customer reports, recalls, warnings ignored,
+beneficiary risk, and reimbursement decisions can be useful but may be proxies
+or policy outcomes rather than ground truth. Distinguish scams from civil
+disputes and first-party participation.
+
+## Feature families
+
+- New beneficiary, beneficiary risk, payee-name mismatch, and counterparty graph
+- Unusual amount, frequency, payment purpose, and deviation from customer history
+- Session/payment journey, warning interaction, confirmation responses, and
+  contact-channel changes available before execution
+- Urgency patterns, repeated limit-sized payments, and rapid beneficiary changes
+- Prior complaints or confirmed beneficiary outcomes known before the payment
+
+## Actions and impact
+
+Potential actions include contextual warning, payee confirmation, customer
+confirmation, cooling-off delay, manual review, transfer hold, or reject where
+policy permits. Measure warning/review/hold volume and value, completion and
+abandonment, review workload, delay, reimbursement exposure, and confirmed scam
+value captured. Do not optimize only for authorization success.
+
+## Review overlay
+
+- Genuine customer consent and deception are both supported.
+- The customer is not knowingly participating; otherwise route to first-party.
+- APP terminology is used only for push payments.
+- Post-payment reports, recalls, reimbursements, and investigations do not leak.
+- Warnings and holds account for vulnerable-customer and policy considerations.

package/skills/risk-compliance/fraud-analysis/references/archetypes/first-party-fraud.md

@@ -0,0 +1,44 @@
+# Archetype: first-party fraud
+
+The genuine customer or account holder is the perpetrator or a knowing
+participant who misrepresents, manipulates, or deliberately misuses their own
+account for financial or material gain.
+
+## Label guidance
+
+Prefer confirmed investigation outcomes that establish knowing participation.
+Operational holds, rapid payout, negative balance, returns, complaints, or mule
+signals are proxies unless the business has validated them as outcomes. State
+whether the target is account misuse, collection abuse, payout abuse, false
+claim, knowing mule activity, or another subtype.
+
+Do not classify a deceived, coerced, compromised, or merely unusual customer as
+first-party fraud without evidence of participation. Outcome maturity may extend
+beyond transaction settlement and must be reflected in the split.
+
+## Feature families
+
+- Account age, identity/KYC state, linked accounts, and shared devices
+- Collection-to-transfer/payout sequence, elapsed time, and value passed through
+- Fan-in, fan-out, counterparty concentration, and beneficiary reuse
+- Balance drain, return/recall history, negative exposure, and claim behavior
+- Deviation from the account's history and cross-account coordinated behavior
+
+Graph and network features must be point-in-time snapshots. Investigation
+findings and future counterparties must not leak into earlier rows.
+
+## Actions and impact
+
+Potential actions include review, reserve, delayed availability, payout hold,
+account restriction, enhanced due diligence, or rejection where authorized by
+policy. Report review workload, legitimate-customer impact, completion/release
+rate, delay, exposure, and confirmed value captured. Do not claim loss prevented
+from a proxy label alone.
+
+## Review overlay
+
+- Evidence supports knowing participation rather than victimization.
+- Mule status is not inferred from transaction shape alone.
+- Graph features and linked-entity lists are train-fit and point-in-time.
+- Account restrictions and reporting recommendations identify policy and legal
+  dependencies.

package/skills/risk-compliance/fraud-analysis/references/archetypes/third-party-fraud.md

@@ -0,0 +1,27 @@
+# Archetype: third-party fraud
+
+The genuine customer did not consent; an external actor used the customer's
+identity, account, credentials, token, or payment instrument.
+
+## Label guidance
+
+Prefer confirmed unauthorized-fraud outcomes. Chargebacks, customer claims,
+issuer codes, account compromise flags, and manual decisions may be proxies;
+state their scope and maturity. Do not treat every decline or dispute as fraud.
+
+## Useful evidence
+
+- Instrument, account, customer, device, IP, email, phone, and session history
+- Deviation from the genuine customer's prior behavior
+- New or shared identifiers, credential failures, and compromise events
+- Transaction velocity, retries, beneficiary novelty, and location changes
+
+Use only evidence available at the selected decision point. A current response,
+claim, chargeback, or investigation outcome is not a pre-decision feature.
+
+## Actions and review
+
+Actions depend on context: block or authenticate a card payment; terminate or
+reauthenticate a compromised session; hold/review a transfer or payout; restrict
+an account where policy permits. Review that technical authentication is not
+used as proof of genuine-customer consent.

package/skills/risk-compliance/fraud-analysis/references/contexts/bank-transfer.md

@@ -0,0 +1,24 @@
+# Context: bank transfer
+
+Typical grains are beneficiary creation, transfer instruction, transfer
+execution, recall, or case. Decision points may be beneficiary setup,
+pre-execution, or post-transfer investigation.
+
+## Features
+
+Beneficiary novelty and age, payee verification, amount deviation, transfer
+velocity, device/session context, customer history, beneficiary/account graph,
+counterparty concentration, and prior confirmed outcomes known at the time.
+
+For APP scams, the genuine customer authorizes the push payment while deceived.
+For account takeover, technical authentication may pass without customer consent.
+
+## Actions and impact
+
+Actions: warning, payee/customer confirmation, reauthentication, cooling-off,
+manual review, hold, reject, or monitor. Measure interventions by count/value,
+completion/abandonment, delay, review workload, recalls/reimbursements, and
+confirmed fraud or scam value captured.
+
+Irreversibility and hold authority depend on rail, market, and policy; state the
+applicable assumptions.

package/skills/risk-compliance/fraud-analysis/references/contexts/card-payment.md

@@ -0,0 +1,30 @@
+# Context: card payment
+
+Typical grains are authorization attempt, payment attempt, clearing event, or
+dispute. Default decision point for preventive rules is pre-authorization.
+
+## Features
+
+Amount and currency, network, card type, token/PAN-derived identity, BIN, country,
+channel, entry method, MCC, merchant, device, customer history, and prior-event
+velocity. A masked PAN may be a weak identity key.
+
+CVV, AVS, authorization response, and 3DS result are same-response or later
+fields unless the chosen decision point explicitly occurs after them. Issuing
+bank name may be derived; prefer BIN for pre-authorization lists.
+
+Fit BIN, country, merchant, and other rate lists on train only. Tiny lists remain
+monitor-only.
+
+## Actions and impact
+
+Actions: block, require 3DS/additional authentication, route, manual review, or
+monitor. For 3DS scenarios, failed authentication does not enter the subsequent
+authorization denominator. Report authorization success and absolute approval
+change only when measured or under explicit pass/conversion assumptions.
+
+## Review overlay
+
+- Current CVV/AVS/auth response/3DS result respects decision timing.
+- BIN lists are train-fit; issuer names are operable only if available live.
+- 3DS and authorization denominators are explicit.

package/skills/risk-compliance/fraud-analysis/references/contexts/payment-collection.md

@@ -0,0 +1,20 @@
+# Context: payment collection
+
+Typical grains are collection attempt, receipt, settlement, return, or linked
+collection-to-outflow sequence. State whether funds are card, bank debit,
+transfer, cash-equivalent, or mixed because timing and reversibility differ.
+
+## Features
+
+Payer and funding-source novelty, amount and velocity, return history, settlement
+state known at decision time, payer concentration, many-payer fan-in, linked
+accounts/devices, account age, and elapsed time from receipt to intended outflow.
+
+Do not use a later return, recall, dispute, or investigation outcome to decide an
+earlier collection. Do not describe unsettled or reversible funds as final.
+
+## Actions and impact
+
+Actions: accept, review, delay availability, reserve, restrict downstream use,
+or reject where supported. Measure accepted/held value, return and loss exposure,
+funds-availability delay, review workload, and legitimate-customer impact.

package/skills/risk-compliance/fraud-analysis/references/contexts/payout.md

@@ -0,0 +1,20 @@
+# Context: payout
+
+Typical grains are beneficiary setup, payout request, approval, release,
+completion, return, or investigation. State the rule's exact decision point.
+
+## Features
+
+Beneficiary novelty and sharing, payout velocity and amount, balance-drain ratio,
+time from collection to payout, account age, KYC state, device/account links,
+fan-out, counterparty concentration, prior returns, and point-in-time graph risk.
+
+Do not use later payout completion, return, recall, restriction, or investigation
+as a pre-release feature.
+
+## Actions and impact
+
+Actions: approve, verify, review, delay, hold, reject, restrict account, or
+monitor where policy permits. Measure held/reviewed count and value, payout
+completion, release delay, review workload, legitimate-customer intervention,
+exposure, and confirmed value captured.