@ocap/chain-node 1.32.1 → 1.32.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,6 +2,11 @@ import { ChainNodeTestHooks, ChainProfile, RunningChainNode, StartChainNodeOptio
2
2
 
3
3
  //#region src/start-chain-node.d.ts
4
4
 
5
+ /**
6
+ * Write a small file atomically and durably (`wx` `0o600` temp file + `fsync` + `rename` + parent dir `fsync`),
7
+ * refusing symlinks on both the target file and its immediate parent directory (#2026, #2036, #2039).
8
+ */
9
+ declare function writeFileDurably(filePath: string, content: string): void;
5
10
  /**
6
11
  * Boot a unified OCAP chain node (`validator`, `follower`, or `hotstuff`) with a 12-step LIFO rollback guard
7
12
  * and 9-step reverse graceful shutdown (`docs/chain-node-design.md` §2.3–§2.4).
@@ -11,4 +16,4 @@ declare function startChainNode(profile: ChainProfile & {
11
16
  testHooks?: ChainNodeTestHooks;
12
17
  }): Promise<RunningChainNode>;
13
18
  //#endregion
14
- export { startChainNode };
19
+ export { startChainNode, writeFileDurably };
package/lib/types.d.cts CHANGED
@@ -1,8 +1,10 @@
1
1
  import { FutureTimestampGuardConfig, TChainConfigCheckMode } from "./standalone-env.cjs";
2
+ import { DidTlsAllowedIssuerPinsInput, DidTlsWireAlgorithm } from "./did-tls.cjs";
2
3
  import { CHAIN_NODE_TEST_HOOKS_TOKEN } from "./test-hooks-token.cjs";
3
4
  import express from "express";
4
5
  import { IChainConfig, IPipelineLogger, TFollowerSyncMode, TNodeWritePolicy } from "@ocap/types";
5
6
  import http from "node:http";
7
+ import tls from "node:tls";
6
8
  import { AnchorPublisher, ICheckpointSignerWallet, IHotStuffRuntimeValidatorMember, ILedgerHealth, INodeRoleConfig, ISegmentArchiveStore, IWriterLeaseConfig, Ledger, LedgerConfig } from "@arcblock/ledger-core";
7
9
  import { SqliteLedgerStorage } from "@arcblock/ledger-sqlite";
8
10
  import SqliteIndexDB from "@ocap/indexdb-sqlite";
@@ -16,6 +18,8 @@ type ILedgerHealthStatus = ILedgerHealth;
16
18
  type TNodeRetentionMode = INodeRoleConfig['retentionMode'];
17
19
  type ChainNodeSegmentPublisher = NonNullable<LedgerConfig['segmentPublisher']> & {
18
20
  getArchiveStore?: () => ISegmentArchiveStore | undefined;
21
+ /** Present on `BackgroundSegmentPublisher`: DA publisher status, `null` outside DA mode (#2016) */
22
+ getDaStatus?: () => Record<string, unknown> | null;
19
23
  };
20
24
  interface TrustedAccountConfig {
21
25
  address: string;
@@ -64,12 +68,25 @@ interface FollowerRoleConfig {
64
68
  clusterPeerUrls?: string[];
65
69
  snapshotBaseUrl?: string | null;
66
70
  snapshotPrefix?: string;
71
+ /**
72
+ * `FOLLOWER_BOOTSTRAP_SOURCE` (#2017): absent or `snapshot` = start from the sanitized snapshot (the default); `da` =
73
+ * start a fresh data dir from the G0 of the DA archive described by `da`, then follow its segments, then the hot tail.
74
+ */
75
+ bootstrapSource?: INodeRoleConfig['bootstrapSource'];
76
+ /** The pinned DA archive (`DA_BASE_URL`, `DA_GENESIS_MANIFEST_HASH`, ...); required with `bootstrapSource: 'da'` */
77
+ da?: INodeRoleConfig['da'];
78
+ /** `DA_BASE_URL` in snapshot mode (#2018): the DA archive a fresh snapshot bootstrap is cross-checked against */
79
+ daCrossCheck?: INodeRoleConfig['daCrossCheck'];
80
+ /** `DA_BASE_URL` set but incomplete in snapshot mode (#2018): enforced only when the node would bootstrap */
81
+ daCrossCheckIncomplete?: INodeRoleConfig['daCrossCheckIncomplete'];
67
82
  trustedProposer?: string | null;
68
83
  trustedProposerPublicKey?: string | null;
69
84
  hotstuffValidators?: IHotStuffRuntimeValidatorMember[];
70
85
  hotstuffQuorumThreshold?: number;
71
86
  /** Whether `127.0.0.1` / RFC1918 private peers are allowed (`false` by default for SSRF safety) */
72
87
  allowPrivatePeers?: boolean;
88
+ /** Optional local `afs-mesh` loopback egress gateway (`http://127.0.0.1:<port>` or `http://[::1]:<port>`, #2025) */
89
+ meshEgressUrl?: string;
73
90
  /** Reject cascaded keyless/unsigned follower upstreams with `UPSTREAM_CASCADED_FORBIDDEN` */
74
91
  disallowKeylessCascadedUpstream?: boolean;
75
92
  allowUnauthenticatedBootstrap?: boolean;
@@ -86,6 +103,11 @@ interface FollowerRoleConfig {
86
103
  signer?: ChainNodeSignerConfig;
87
104
  /** Optional explicit runtime role (`'follower'` default or `'standby'`) */
88
105
  runtimeRole?: 'follower' | 'standby';
106
+ /**
107
+ * First sequence whose orphan ledger entries the initial index build indexes (default: where the chain's leader
108
+ * began indexing them, see `orphanIndexFromSequence`; 1 for chains not listed there).
109
+ */
110
+ orphanIndexFromSequence?: number;
89
111
  }
90
112
  interface HotStuffValidatorRoleConfig {
91
113
  kind: 'hotstuff';
@@ -97,6 +119,8 @@ interface HotStuffValidatorRoleConfig {
97
119
  allowPublicConsensusBind?: boolean;
98
120
  writePolicy?: TNodeWritePolicy;
99
121
  allowPrivatePeers?: boolean;
122
+ /** Optional local `afs-mesh` loopback egress gateway (`http://127.0.0.1:<port>` or `http://[::1]:<port>`, #2025) */
123
+ meshEgressUrl?: string;
100
124
  retentionMode?: TNodeRetentionMode;
101
125
  hotWindowEntries?: number;
102
126
  hotWindowCheckpoints?: number;
@@ -117,11 +141,47 @@ interface ChainAppHookContext {
117
141
  preferencesManager: NodePreferencesManager;
118
142
  maintenanceController: INodeMaintenanceController;
119
143
  }
144
+ interface ChainHttpTlsConfig {
145
+ enabled?: boolean;
146
+ /** TLS wire key/signature algorithm (`'p256'` universal BoringSSL/OpenSSL default with Ed25519 `DIDBindingProof`, or `'ed25519'` on OpenSSL) */
147
+ wireAlgorithm?: DidTlsWireAlgorithm;
148
+ /** Optional Ed25519 DID seed / secretKey for server cert synthesis (defaults to node signer / `CHAIN_SK`) */
149
+ identitySecretKey?: string;
150
+ /** Optional explicit W3C or OCAP server DID (`did:abt:z...` or `z...`) */
151
+ subjectDid?: string;
152
+ /** Optional PEM certificate file override (`lstatSync` non-symlink verified) */
153
+ certFile?: string;
154
+ /** Optional PEM private key file override (`lstatSync` non-symlink verified) */
155
+ keyFile?: string;
156
+ /** Require client mTLS certificate (`true` by default whenever `enabled: true`) */
157
+ requireClientCert?: boolean;
158
+ /** Fail-closed pinned 32-byte Ed25519 issuer public keys (hex, `0x` hex, multibase `z...`, or `<did>=<pk>`) */
159
+ allowedIssuerPublicKeys?: DidTlsAllowedIssuerPinsInput;
160
+ /** Optional allowlist of permitted client subject DIDs */
161
+ allowedClientDids?: readonly string[];
162
+ /** Optional DNS SubjectAltName entries for synthesized server certificate */
163
+ sanDnsNames?: readonly string[];
164
+ /** Optional IPv4 / IPv6 SubjectAltName entries for synthesized server certificate */
165
+ sanIpAddresses?: readonly string[];
166
+ /** Synthesized server certificate validity duration in days (`1..3650`, default `365`) */
167
+ validityDays?: number;
168
+ /** TLS handshake timeout in milliseconds (default `10_000`) */
169
+ handshakeTimeoutMs?: number;
170
+ /** Allowed clock skew in seconds for client cert verification (default `60`) */
171
+ clockSkewSeconds?: number;
172
+ }
173
+ interface ReloadedTlsCredentialsInfo {
174
+ reloaded: boolean;
175
+ subjectDid: string | null;
176
+ spkiSha256Hex: string | null;
177
+ }
120
178
  interface ChainProfileBase {
121
179
  /** Optional explicit nodeId (otherwise loaded/persisted in `<dataDir>/.node-id`) */
122
180
  nodeId?: string;
123
181
  /** Exclusive node data directory (`statedb.sqlite`, `ledger.sqlite`, `indexdb.sqlite`, `trusted.sqlite`, `.node-id`) */
124
182
  dataDir: string;
183
+ /** Optional local `afs-mesh` loopback egress gateway (`http://127.0.0.1:<port>` or `http://[::1]:<port>`, #2025) */
184
+ meshEgressUrl?: string;
125
185
  http: {
126
186
  /** Default `'127.0.0.1'`; pass `'0.0.0.0'` explicitly to listen on all interfaces */
127
187
  host?: string;
@@ -137,6 +197,8 @@ interface ChainProfileBase {
137
197
  onGraphqlError?: (err: Error & {
138
198
  originalError?: Error;
139
199
  }) => void;
200
+ /** Optional zero-CA DID-TLS / mTLS listener configuration (#2025) */
201
+ tls?: ChainHttpTlsConfig;
140
202
  };
141
203
  storage?: {
142
204
  statedbPath?: string;
@@ -165,6 +227,8 @@ interface ChainProfileBase {
165
227
  coldArchiveReader?: IColdSegmentReader | null;
166
228
  anchorPublisher?: AnchorPublisher | null;
167
229
  env?: Record<string, string | undefined>;
230
+ /** Test seam: the `fetch` the env-built segment publisher uses (e.g. a fake R2). Unset in production. */
231
+ fetchImpl?: typeof fetch;
168
232
  };
169
233
  genesisTime?: string;
170
234
  reservedSymbols?: string[];
@@ -296,15 +360,17 @@ interface RunningChainNode {
296
360
  readonly indexdb: SqliteIndexDB;
297
361
  readonly trustedStorage: SqliteTrustedStorage;
298
362
  readonly server: http.Server;
363
+ readonly tlsServer?: tls.Server;
299
364
  readonly followerSync?: FollowerSyncService;
300
365
  readonly hotstuffRuntime?: HotStuffNodeRuntime;
301
366
  readonly preferencesManager: NodePreferencesManager;
302
367
  readonly maintenanceController: INodeMaintenanceController;
303
368
  ledgerHealth(): Promise<ILedgerHealthStatus>;
369
+ reloadTlsCredentials(): Promise<ReloadedTlsCredentialsInfo>;
304
370
  advanceClock?(seconds: number): number;
305
371
  restart(nextProfile?: Partial<ChainProfile>): Promise<RunningChainNode>;
306
372
  stop(): Promise<void>;
307
373
  }
308
374
  type ChainNodeHandle = RunningChainNode;
309
375
  //#endregion
310
- export { ChainAppHookContext, ChainNodeHandle, ChainNodeProfile, ChainNodeRoleConfig, ChainNodeSegmentPublisher, ChainNodeSignerConfig, ChainNodeTestHooks, ChainNodeTestHooksInput, ChainProfile, ChainProfileBase, FollowerRoleConfig, FollowerSyncTestController, FollowerUpstreamInterceptorContext, HotStuffValidatorRoleConfig, ILedgerHealthStatus, ILedgerLeaseOptions, PublicKeyOnlyValidatorSignerConfig, RunningChainNode, StartChainNodeOptions, TNodeRetentionMode, TrustedAccountConfig, ValidatorRoleConfig, ValidatorSignerConfig };
376
+ export { ChainAppHookContext, ChainHttpTlsConfig, ChainNodeHandle, ChainNodeProfile, ChainNodeRoleConfig, ChainNodeSegmentPublisher, ChainNodeSignerConfig, ChainNodeTestHooks, ChainNodeTestHooksInput, ChainProfile, ChainProfileBase, FollowerRoleConfig, FollowerSyncTestController, FollowerUpstreamInterceptorContext, HotStuffValidatorRoleConfig, ILedgerHealthStatus, ILedgerLeaseOptions, PublicKeyOnlyValidatorSignerConfig, ReloadedTlsCredentialsInfo, RunningChainNode, StartChainNodeOptions, TNodeRetentionMode, TrustedAccountConfig, ValidatorRoleConfig, ValidatorSignerConfig };
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "publishConfig": {
4
4
  "access": "public"
5
5
  },
6
- "version": "1.32.1",
6
+ "version": "1.32.3",
7
7
  "description": "Unified OCAP chain node runtime assembly (Validator, Standby, Keyless Follower)",
8
8
  "type": "module",
9
9
  "main": "./lib/index.cjs",
@@ -54,26 +54,26 @@
54
54
  "author": "wangshijun <wangshijun2010@gmail.com> (http://github.com/wangshijun)",
55
55
  "license": "MIT",
56
56
  "devDependencies": {
57
- "@ocap/mcrypto": "1.32.1",
58
- "@ocap/message": "1.32.1",
57
+ "@ocap/mcrypto": "1.32.3",
58
+ "@ocap/message": "1.32.3",
59
59
  "@types/express": "^4.17.23",
60
60
  "@types/node": "^20.10.0",
61
61
  "tsdown": "^0.18.4"
62
62
  },
63
63
  "dependencies": {
64
- "@arcblock/did": "1.32.1",
65
- "@arcblock/ledger-core": "1.32.1",
66
- "@arcblock/ledger-sqlite": "1.32.1",
67
- "@ocap/config": "1.32.1",
68
- "@ocap/gql": "1.32.1",
69
- "@ocap/indexdb-sqlite": "1.32.1",
70
- "@ocap/resolver": "1.32.1",
71
- "@ocap/state": "1.32.1",
72
- "@ocap/statedb-sqlite": "1.32.1",
73
- "@ocap/trusted-storage": "1.32.1",
74
- "@ocap/types": "1.32.1",
75
- "@ocap/util": "1.32.1",
76
- "@ocap/wallet": "1.32.1",
64
+ "@arcblock/did": "1.32.3",
65
+ "@arcblock/ledger-core": "1.32.3",
66
+ "@arcblock/ledger-sqlite": "1.32.3",
67
+ "@ocap/config": "1.32.3",
68
+ "@ocap/gql": "1.32.3",
69
+ "@ocap/indexdb-sqlite": "1.32.3",
70
+ "@ocap/resolver": "1.32.3",
71
+ "@ocap/state": "1.32.3",
72
+ "@ocap/statedb-sqlite": "1.32.3",
73
+ "@ocap/trusted-storage": "1.32.3",
74
+ "@ocap/types": "1.32.3",
75
+ "@ocap/util": "1.32.3",
76
+ "@ocap/wallet": "1.32.3",
77
77
  "cors": "^2.8.5",
78
78
  "express": "^4.22.1"
79
79
  }