# AISFOR Network Integration Map

This document records the source-level findings used to shape AISFOR-CHAIN. It is intentionally kept in `D:\aisfor-chain` as the coordination layer.

## Project Roots

- AISFOR: `E:\aisfor`
- AISTALK: `F:\aistalk`
- AISGROUP: `E:\aisfor-group`
- AISMALL: `E:\aismall`
- AISFOR-CHAIN: `D:\aisfor-chain`

## Identity

AISFOR should be the identity master.

Observed fields:

- AISFOR `models/User.js`: `userid`, `_id`, `name`, `email`, `phone`, profile and plan fields.
- AISTALK `models/User.js`: own `userid`, `_id`, session fields, nullable `aisforUserId`.
- AISGROUP `models/User.js`: own `userid`, `_id`, profile and group fields, nullable `aisforUserId`.
- AISMALL `models/User.js`: already has `aisforUserId` and `mariaeUserId`.

Integration rule:

- AISFOR `_id` is the canonical account id.
- Other services should eventually store a nullable `aisforUserId` reference.
- AISFOR-CHAIN receives that value as `actorId`.

## AISFOR Proof Sources

AISFOR already has internal proof and point chains:

- `models/StorageProofLog.js`
  - `eventKey`
  - `eventType`
  - `userId`
  - `chunkId`
  - `nodeId`
  - `deviceId`
  - `payloadHash`
  - `proofHash`
  - `previousProofHash`

- `models/PointLedger.js`
  - `eventKey`
  - `userId`
  - `nodeId`
  - `deviceId`
  - `eventType`
  - `pointAmount`
  - `payloadHash`
  - `pointProofHash`
  - `previousPointProofHash`

- `models/BlockchainProofBundle.js`
  - `bundleKey`
  - `storageProofRootHash`
  - `pointProofRootHash`
  - `combinedRootHash`
  - `payloadHash`
  - `bundleHash`
  - `status`
  - `anchorTxHash`

Best first anchor:

- Submit `BlockchainProofBundle` rows to AISFOR-CHAIN as `BLOCKCHAIN_PROOF_BUNDLE`.
- Do not duplicate AISFOR's internal proof chain logic in AISFOR-CHAIN.

## First Payload Shape

```json
{
  "sourceService": "AISFOR",
  "proofType": "BLOCKCHAIN_PROOF_BUNDLE",
  "externalProofId": "bundle:...",
  "idempotencyKey": "AISFOR:BUNDLE:bundle:...",
  "contentHash": "combinedRootHash",
  "payloadHash": "payloadHash",
  "bundleHash": "bundleHash",
  "metadata": {
    "storageProofFromSeq": 1,
    "storageProofToSeq": 100,
    "pointProofFromSeq": 1,
    "pointProofToSeq": 50,
    "storageProofRootHash": "...",
    "pointProofRootHash": "..."
  }
}
```

## Suggested Order

1. Keep AISFOR-CHAIN independent and accept `BLOCKCHAIN_PROOF_BUNDLE`. Done.
2. Add service authentication to AISFOR-CHAIN. Done.
3. Add a thin AISFOR client that submits prepared bundles. Done in `E:\aisfor\services\aisforChainClient.js`.
4. Mark AISFOR bundles anchored after AISFOR-CHAIN accepts them. Done in `E:\aisfor\services\blockchainProofBundleService.js`.
5. Add `aisforUserId` references to AISTALK and AISGROUP. Done.
6. Reuse AISMALL's existing `aisforUserId` link for mall proofs. Done.

## AISFOR Client Hook

AISFOR now has a client-side hook:

- `E:\aisfor\services\aisforChainClient.js`
- `submitBundleToAisforChain(bundle)`
- admin route: `POST /admin/blockchain/bundles/:id/submit-chain`
- admin page button: `AISFOR-CHAIN`

The client posts to:

- default URL: `http://localhost:4317/api/proof`
- override: `AISFOR_CHAIN_URL`
- optional key: `AISFOR_CHAIN_SERVICE_KEY` or `AISFOR_CHAIN_KEY_AISFOR`

## AISTALK Client Hook

AISTALK now has a message proof hook:

- `F:\aistalk\services\aisforChainClient.js`
- route hook: `F:\aistalk\routes\chat.js`
- proof type: `MESSAGE_CREATED`
- source service: `AISTALK`
- actor id: `aisforUserId` when linked, otherwise local AISTALK user id

The hook submits proof after text/file messages are saved. It does not send raw message text to AISFOR-CHAIN; it submits hashes and metadata only. Submission errors are logged and do not block chat delivery.

## AISGROUP Client Hook

AISGROUP now has a group activity proof hook:

- `E:\aisfor-group\services\aisforChainClient.js`
- route hook: `E:\aisfor-group\routes\event-records.js`
- proof type: `GROUP_ACTIVITY`
- source service: `AISGROUP`
- actor id: `aisforUserId` when linked, otherwise local AISGROUP user id

The hook submits proof after event records are created. It sends hashes and compact metadata, and proof submission errors do not block the group activity workflow.

## AISMALL Client Hook

AISMALL now has a commerce activity proof hook:

- `E:\aismall\services\aisforChainClient.js`
- route hook: `E:\aismall\routes\checkout.js`
- proof type: `MALL_ACTIVITY`
- source service: `AISMALL`
- first activity type: `ORDER_CREATED`
- actor id: `aisforUserId` when linked, otherwise local AISMALL user id

The hook submits proof after the master order and store orders are created. It sends hashes, item/store counts, amounts, and status metadata without sending buyer/receiver personal information to AISFOR-CHAIN. Submission errors are logged and do not block checkout.

## Chain Wallet Identity Link

AISFOR-CHAIN now supports canonical user wallet creation using AISFOR `_id` as the owner id.

Rules:

- AISFOR `_id` remains the canonical account id.
- Chain wallet owner type for AISFOR users is `aisfor_user`.
- Chain wallet owner id is the AISFOR `_id` string.
- User wallet creation is idempotent: the same AISFOR user id maps to the same wallet.
- Service wallets remain separate from user wallets and use owner type `service`.

Primary API:

- `GET /api/wallet/user/:userId`
- `POST /api/wallet/user/:userId`
- `GET /api/wallet/users/list`

Admin route:

- `POST /admin/wallet/user`

This keeps chain identity aligned with AISFOR while avoiding direct dependency on AISFOR's database during the mock-chain stage.

## Wallet Recovery Vault

- Server-managed test wallets can now create a recovery phrase and mock private key.
- Recovery material is encrypted with wallet PIN using AES-256-GCM and scrypt-derived keys.
- The chain stores only hashes/proofs; plaintext recovery phrase and private key are shown only during PIN-authenticated export.
- PIN changes are blocked after a recovery vault is enabled unless recovery material is exported and handled manually first.
- This is still mock-mainnet infrastructure and does not represent a withdrawable external coin wallet.

## HMAC v2 Service Signing

AISFOR, AISTALK, AISGROUP, and AISMALL chain clients now send HMAC v2 headers when their service key is configured.

Client headers:

- `X-AISFOR-SERVICE`
- `X-AISFOR-API-KEY`
- `X-AISFOR-SIGNATURE`
- `X-AISFOR-TIMESTAMP`
- `X-AISFOR-NONCE`

The v2 signature covers service name, timestamp, nonce, HTTP method, request path, and normalized request body. This keeps the existing service-key deployment model while adding replay resistance for service proof submission.

Updated clients:

- `E:\aisfor\services\aisforChainClient.js`
- `F:\aistalk\services\aisforChainClient.js`
- `E:\aisfor-group\services\aisforChainClient.js`
- `E:\aismall\services\aisforChainClient.js`

Auth-required mode is enabled on AISFOR-CHAIN. Service keys are stored in each service .env and in D:\aisfor-chain\.env. Values must not be committed or exposed in public documentation.


## Service-Side Chain Status Views

The service apps now expose protected admin views for recent AISFOR-CHAIN proof confirmation state:

- AISTALK: `/admin/chain-status`
- AISGROUP: `/master/chain-status`
- AISMALL: `/admin/chain-status`

Each view summarizes total, confirmed, and pending proof-backed records and links available chain transaction hashes and block heights to AISFOR-CHAIN Explorer.
